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

Sadly, TUG did not
this year accept us as a mentoring organisation.

I hope you mean Google :-)

Arthur

Jonathan Fine

2009-03-22 20:01:20 UTC

Sadly, TUG did not
this year accept us as a mentoring organisation.

I hope you mean Google :-)

Yes, you're right here. I was wanting to say that "TUG was not accepted
this year ...", but changed construction in mid-phrase.

Arthur: Do you have any helpful or encouraging comment about the work I
reported in my message?

--
Jonathan

Arthur Reutenauer

2009-03-22 22:16:07 UTC

Post by Jonathan Fine
Arthur: Do you have any helpful or encouraging comment about the work I
reported in my message?

I wondered about how you handled things like:

\newcommand{\ip}[2]{(#1, #2)}

in the current code. Both control sequences are linked to an
independent page, which I think is not right: \newcommand should of
course have a page of its own (I understand it still needs to be
written; that's why the link is broken); but \ip certainly shouldn't,
since it's only defined in the document.

Maybe trying to do both syntax highlighting and command reference in
the same code is too much; do you have any plan on how to deal with
that?

Arthur

Jonathan Fine

2009-03-24 06:59:03 UTC

Post by Jonathan Fine
Arthur: Do you have any helpful or encouraging comment about the work I
reported in my message?

\newcommand{\ip}[2]{(#1, #2)}
in the current code. Both control sequences are linked to an
independent page, which I think is not right: \newcommand should of
course have a page of its own (I understand it still needs to be
written; that's why the link is broken); but \ip certainly shouldn't,
since it's only defined in the document.

Arthur: Thank you for this.

Yes. This is a little bit thorny. However, I'm confident that the
hyperlinks will be useful even if some of them are broken, and so I this
I'm inclined to be guided by the experience of early users.

Here are some possible solutions:

1. Have the hyperlinker understand \newcommand.
2. Link only to commands that are in a dictionary.
3. Have the document state up front, that such-and-such are the
commands it provides. (This is like 1, except easier for me).
4. Do nothing.

I'm inclined to have simple constructs like \newcommand understood, but
implementing this is not yet a priority. However, (2) might also be
sensible, if the dictionary is large enough.

Post by Arthur Reutenauer
Maybe trying to do both syntax highlighting and command reference in
the same code is too much; do you have any plan on how to deal with
that?

I've written only about 200 lines of fairly simple code, so the it's not
yet time for refactoring.

I think my next priority is to write a 'dtx2html' translator, so that I
can produce some pages to link to.

My other priority is to write regular expressions that will hilight and
hyperlink style files (rather than tex documents).

--
Jonathan

Ross Moore

2009-03-22 22:40:11 UTC

Post by Jonathan Fine
Sadly, TUG
did not this year accept us as a mentoring organisation.

I hope you mean Google :-)

Yes, you're right here. I was wanting to say that "TUG was not
accepted this year ...", but changed construction in mid-phrase.
Arthur: Do you have any helpful or encouraging comment about the
work I reported in my message?

Surely there should be some extra blank lines (via )

Post by Jonathan Fine
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.

Otherwise the intention is lost.

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

Post by Jonathan Fine
<a class=csname href="cs/end.html">\end</a>{document}

I'd prefer to see home-grown attribute values properly quoted; viz,

Post by Jonathan Fine
<a class="csname" href="cs/end.html">\end</
a>{document}

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.

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.

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.

Post by Jonathan Fine
--
Jonathan

Hope this helps,

Ross

------------------------------------------------------------------------
Ross Moore ross at maths.mq.edu.au
Mathematics Department office: E7A-419
Macquarie University tel: +61 (0)2 9850 8955
Sydney, Australia 2109 fax: +61 (0)2 9850 8114
------------------------------------------------------------------------

Jonathan Fine

2009-03-24 07:12:50 UTC