[tug-summer-of-code] A hyperlinked and highlighted version of sample2e.tex

[Jonathan Fine]

Ross Moore wrote:

> Surely there should be some extra blank lines (via <br/>)
> within this block:
> 
>>>> The ends  of words and sentences are marked
>>>>   by   spaces. It  doesn't matter how many
>>>> spaces    you type; one is as good as 100.  The
>>>> end of   a line counts as a space.
>>>>
>>>>
>>>> One   or more   blank lines denote the  end
>>>> of  a paragraph.

If you look at the HTML closely enough, I think you'll see that there is 
extra vertical space between paragraphs.  (That's what I get on FF2.)

This sort of think is controlled by a style-sheet, which is a present 
hard coded.

> Also, it's interesing that the HTML coding you generate
> has no DOCTYPE, so cannot be validated, except in the most
> generic sense.

I ran out of time.  Like the style-sheet, top and tail of the page comes 
from a couple of simple string templates.  So this is easy to fix, or to 
make configurable.

> With a line such as:
> 
>>>>   <p class=tex><a class=csname href="cs/end.html">\end</a><span 
>>>> class=chars>{document}
> 
> I'd prefer to see home-grown attribute values properly quoted; viz,
> 
>>>>   <p class="tex"><a class="csname" href="cs/end.html">\end</a><span 
>>>> class="chars">{document}

Well, I suppose that depends on the DOCTYPE.  I can see benefits in 
being able to apply a parser to validate the output, and if the 
validation requires the quote then we supply the quotes.

The href, and perhaps also the class names, need to be configurable. 
I'm not sure yet what the best way of solving this problem is, in part 
because I've not yet had to configure the system.

> so as to be more consistent with XHTML usage.
> That way you'd be able to Copy/Paste, or otherwise include, such
> automatically-generated HTML coding within Wikis, etc.

Copy-and-paste is really important, as is being able to incorporate 
snippets into another page.

At some point I should sit down and see how Pygments (the widely used 
hilighter coded in Python) does these various things.  One of my goals 
is to write something that will work 'drop in' on sites that use Pygments.

> I have other comments too, regarding source-code layout.
> But these aren't generally adopted.
> 
> e.g., I really hate the use of \ip as a macro name.

The sample file comes from the LaTeX2e distribution, and I'm not going 
to change it.  But I can process some other sample files.

>  1- and 2-letter (lowercase) names for home-grown macros
> should be completely discouraged, as there is too great
> a chance of a clash with the macro for a letter or special
> character that can occur in a foreign script or language.
> (Just think of what this would do to someone's name that
> may need that letter, in a bibliographic entry, say.)
> 
> 
> When producing materials that are intended to teach people
> how to use LaTeX, then some thought should be given to
> avoiding such undesirable practices.

Perhaps there's a call for a TeX-focussed site similar to
     http://www.djangosnippets.org/

-- 
Jonathan