[extend-a-story-devel] Re: Extend-A-Story and GPL

[Jeff W. (S. Toby) <jjw...@ke...>]

On Tue, 15 Jul 2003, Matthew Duhan wrote:

> That was me. In making the changes to Extend-A-Story to support Style
> Sheets and potentially support additional tags, I wanted to make it as
> HTML4/XHTML compliant as possible, according to the W3C specs. While
> case does not matter for HTML, it does for XML (and some translators of
> XHTML), so I decided to go with a more standard lowercase format for the
> XHTML code. I also removed some of your formatting that used depreciated
> tags, such as the CENTER tag.

I see... I was not aware of the specification. I might have a few choice
words for the W3C consortium, but this isn't your fault. I'll have to
think about what I want to do about this. I do agree that deprecated tags
such as the CENTER tag should probably be removed. However, I am concerned
that some of my users may be using older browsers and will not understand
the new HTML specification we will be using. If this turns out to be an
issue, I'd like to find some way to provide support for older browsers.

Have I mentioned I hate HTML coding? :) You'd think its funny for a web
developer to hate HTML coding, but here we are. I just can't stop thinking
about how something so useful can be made so annoying. Anyways, I digress.  
These issues are not your fault.

> I guess that didn't occur to me, as the editor that I use (BBEdit)  
> automatically color codes and differentiates between code, string, and
> plain text. As I said above, I'd prefer to keep within the W3C specs.  
> If you feel strongly about it, I'm not opposed to using uppercase HTML
> tags, but I would at least prefer to use lowercase attributes
> (align="center" vs ALIGN="CENTER").

Well, my editor (TextPad) does syntax highlighting as you describe. I've
just gotten used to the case difference in addition to the highlighting to
help differentiate between the various bits of code. Originally,
Extend-A-Story was built using the pico editor on Linux. That editor of
course has no syntax highlighting, so the case difference made it
incredibly easier to see what was going on. I just kept the same standard
when I moved to more powerful editors.

Incidentally, I also prefer uppercase attribute names, but I see that
those are also required to be lower case by the new standard. *sigh*

> I believe that my changes shouldn't break this functionality the way
> I've coded it. Unless I sent you the wrong version, looking at my
> version of general.php, line 640 is where
> getEpisodeBodyTranslationTable( ) begins. On the left side of the
> replacement array (lines 642-661) I have kept the various upper- and
> lowercase permutations. On the right side, where the replacement is
> returned, I am returning only lowercase HTML code. This lowercase code
> is what will be translated by the browser. When I tested this, it worked
> as expected, with authors being able to use both upper-and lowercase
> tags.

You are quite correct. I was in a hurry and read the code too fast, thus
getting it backwards. Your version should work fine.

> This by the way brings up an interesting point, and one which we should
> probably try to hash out. The way EAS is coded now, it leaves authors'
> input untouched, and does the translation on display only. This can
> become a hindrance if we want to add support for more tags, as we will
> have to check for every permutation of every tag. This is partly why I
> see using a BBCode derivative easier. I think that it would add a little
> more load on input, but less load on output, if we were to check for the
> presence of tags first, and automatically toLower them before inserting
> into the db. This way, the getEpisodeBodyTranslationTable function only
> has to search for the lowercase version. Or better yet, why not
> translate on input, so that the complete tags go into the db for those
> tags we deem 'valid,' and others would remain < and >.  What are
> your thoughts on this?

In the version 1 releases of Extend-A-Story, things were quite a bit
different. The HTML entities (<, >, &, ") were all escaped out to their
HTML escape sequences when written to the database. When displaying an
episode, the allowed HTML sequences were scanned for and then converted
back to HTML.

When I built version 2, I moved away from that approach. I didn't like how
the data in the database was so HTML-centric. If I decided to display an
episode using some other format, you would need to go to a lot of effort
to remove the HTML specific coding and put some other coding in place. As
it stands right now, the data the user enters in is stored directly in the
database as entered. When displaying the episode (in this case, to a
browser rendering HTML) the conversion of special character to HTML
entities, and the conversion of formatting codes to HTML is done at that
time.

Now don't get hung up on the fact that the tags I'm using for formatting
episodes are the same as the HTML tags with the same purpose. This was
done because I knew my target audience knew HTML already, and so that I
didn't have to invent some new way of doing the tagging. I could have
easily used [P], (bold=ON), *hr*, or whatever mechanism I could come up
with. The tags would still get processed the same way.

I understand your concern that the current approach is not the best way to
go at it. In particular, if one wants to add a large number of tags, one
would have to add a large amount of code to the decoding functions to
handle it. It would be nice if we could make the tagging a data driven
element, such that the allowed tags, and how they are decoded, is put in
the database somehow. That way someone could easily add new tags to the
database without having to touch the code. We could probably build an
interface for it. Also, it would make it easy to have different tag
schemes that an administrator, or users would be able to choose between.  
It sounds like your users want a BBCode like scheme, while I think my
users are more familiar with an HTML tagging scheme. It would be nice to
be able to support both without too much hassle.

You bring up another good point about the uppercase/lowercase issue with
formatting tags. We certainly don't want to be checking for every possible
permutation of a tag. If we force all the tags to be of a certain case
(say, lower case for now), we can do a toLower on the episode text, locate
the tags, and convert the tags in the original episode to lower case. Then
searching for the tags when displaying an episode becomes much simpler.

> > In particular, the change of HTML coding style of the files in the doc
> > directory has changed the files so much that they are nearly
> > unrecognizable.
> 
> My apologies for that. After I had gotten your initial e-mail, it
> sounded like the work that I would be doing might not be integrated into
> the main branch, so I edited HTML as well as code.

I think the main thing that bothered me about the documentation HTML was
that my version was word wrapped at something like 78 characters, while
yours had no word wrap at all.

> I can try to separate out some of the HTML formatting changes and
> document it or send you another tgz. To be honest, though, most places
> (other than the docs) where I made changes to the HTML formatting I also
> made other changes to the HTML, such as adding the warning or error
> class, or removing depreciated tags such as CENTER. You may have noticed
> I also attempted to separate content from presentation where possible,
> creating a set of inclusion files (named "inc-") for repeated bits of
> formatting.

Yeah, I did see your additional changes. I like abstracting out common
bits of logic (such as the Story Home and Site Home navigation logic) into
a common file that can be used elsewhere.

> I really feel that the benefits of standardizing on the current W3C
> recommendations for XHTML (http://www.w3c.org/TR/xhtml1/#guidelines)  
> will outweigh the short term difficulty of integrating these changes
> into EAS. Some features that I can foresee adding would be more easily
> implemented if we adhere as much as possible to XML/XHTML specs.

Yes, I'm sure you're right. If I seem grumpy about it, its because I'm
grumpy at the specification. I really see no reason why they couldn't
allow for both upper case and lower case tags to be used. Sure, they are
different XML elements, but the elements could be defined to mean the same
thing. There's nothing in XML that would prevent this. I don't know if a
similar trick can be used for the attributes though...

Again, I digress. We have the standard, and I don't like it. I guess I'll
have to live with it. Although... I could in theory write the HTML however
I darn well please and then use an XSLT transform to turn it into proper
HTML. But, that's too much work. Again, as I said earlier, I hate HTML
coding. :)

> I agree. We just need to decide the standard. :) I understand your
> desire to use uppercase HTML for easier readability in the code view.  
> If you feel strongly about it then I am willing to work that way, and I
> feel confident that I can fairly quickly change the 2.2.0 code back to
> uppercase if need be. As I mentioned above, though, I think in the long
> run it will benefit us to try to use current W3C specs.

I think I'll agree to try to keep it within the W3C specs. I'll find some
way to not complain too loudly about it.

> > Just so you know, here are the features I'm thinking of starting work
> > on: Showcase Random Episodes, and Sort Search Results by Chronological
> > Order.
> 
> Sounds good. I would also like to add additional tag support, but I can
> hold off on that until we hash things out.

Sounds like a good plan. I've actually not done any work in anticipation
of incorporating your changes. I agree with your suggestion of holding off
on further changes until we hammer out these first round of changes.

> I agree. With any collaboration such as this there are bound to be
> initial hurdles to work through. This is especially the case because I
> began modifying something which was initially a one person project,
> using my own coding practices. I'm sure that we'll be able to hash it
> out.

Yeah, its always hard to open up something you've worked on by yourself.  
But, I think the benefits of collaboration far outweigh the hassles of
getting these issues ironed out.

> If you ever want to chat about it online, I'm on AIM under [snip], or we
> can continue using e-mail.

I do use online IM clients on occasion, but I don't have any installed
right now. However, considering the length of our emails, and the highly
technical nature of our discussions, I think email will be the preferred
discussion medium. However, I would like to suggest continuing the
discussion on the devel mailing list. I see that you've subscribed, so I'm
sending this response to the list itself.

I don't know how familiar you are with the SourceForge lists, but just as
a general warning, they don't set the "reply to" header to actually point
back to the list. If you want to reply to a posting and have it go back to
the list, you have to use "reply to all" to do it.


Here's how I'd like to move forward:

Let's stick with the W3C standard. I'll take a closer look at the files
you've submitted and see just what the changes are. This will take me some
time, and I can't really guarantee I'll have lots of time to look at your
changes in great detail until the weekend. I'm sure I'll have questions
about what you've done, so we'll likely have additional discussions about
them. In general, my goal for integrating your changes is to keep the user
experience for the users on my site identical to the current user
experience while still maintaining the features you want in the code base.
Ideally, I should be able to have my look and feel, and you should be able
to have your look and feel while using an identical code base, with only a
different style sheet.

We should hold off on working on any new features until we get the above
changes ironed out. However, it sounds like the enhanced tagging
capability is an important feature to you. That will likely be a
complicated enough change that we should start talking about how we want
to improve upon the current system.

Once we've handled the coding style changes, I'll evaluate additional
patches from you, and when I'm comfortable with giving you direct access
to the CVS repository, I'll add you as a developer. I'll try to do this
quickly, since I understand that the anonymous pserver access is quite
lousy right now.


Whew! This email is a mouthful, but I think we're getting on the right
track. Hopefully you feel the same way. Let me know your impressions as
well. Please be sure to respond to the mailing list so that we can keep an
archive of our discussions.

-- 
Jeff Weston (Sir Toby)