## LATEX-L@LISTSERV.UNI-HEIDELBERG.DE

 Options: Use Forum View Use Monospaced Font Show Text Part by Default Show All Mail Headers Message: [<< First] [< Prev] [Next >] [Last >>] Topic: [<< First] [< Prev] [Next >] [Last >>] Author: [<< First] [< Prev] [Next >] [Last >>]

 Subject: Re: DocTeX -- the next generation? From: Lars Hellström <[log in to unmask]> Reply To: Mailing list for the LaTeX3 project <[log in to unmask]> Date: Tue, 23 Mar 2004 15:44:03 +0100 Content-Type: text/plain Parts/Attachments: text/plain (144 lines)
At 17.59 +0100 2004-03-21, David Kastrup wrote:
>Hello,
>
>I have been musing about the best ways of providing people with
>integrated help systems, input helps and so forth and so on.
>
>The usual TeX authoring system (like Emacs with AUCTeX, or kile, or
>WinEdt, or even LyX) will provide menu entries for commands,
>descriptions like the following:
[snip]
>and so forth and so on (not to mention syntax highlighting).  Now the
>usual way DocTeX files describe things are with \DescribeMacro{...},

("DocTeX" --- that had me confused for quite a while. "doc.sty", "the doc
package", or "the .dtx system" I would have understood, but "DocTeX" was
definitely a new name for this.)

>with examples of code, with the synposis of commands (using things
>like \marg, \oarg and so in the descriptions).

Interestingly enough, neither \marg nor \oarg are defined by doc.sty, but
by ltxdoc.cls.

>I would propose that the next iteration of DocTeX should try to
>formalize most of the stuff into somewhat more rigid patterns.

Richer markup, you mean? It could probably be done, and it would probably
be a Good Thing.

>It would appear that the material before \StopEventually{} would
>usually, if just given a bit more formal markup,

Hmm... "just a *bit* more formal markup". That might have to be quite a
large bit, I'm afraid. The current amount of markup (\DescribeMacro and
friend) in the description parts of .dtx files is little more than special
commands for putting stuff into the index. OTOH small additions could give
large gains. A more formalised environment for code examples could help a
lot.

>be quite sufficient
>to let the following be generated:
>
>Pages fit for TeXinfo or similar systems (like the above example)
>that can be accessed once the editing system knows what packages one
>uses, by referring to the name of the defined commands.

Exporting text from .dtx files may be more work than you think. Many
"general purpose" LaTeX->Something converters choke on or get thoroughly
confused by .dtx files because they don't support \catcode changes, whereas
pretty much all markup in .dtx files relies on some particular \catcode
change.

>Examples typeset with something like
>\begin{examplepreamble}
>\documentclass[fleqn]{article}
>\usepackage{amsmath}
>\end{examplepreamble}
>With the fleqn class option to article, the look will be as follows:
>\begin{examplebody}
>$$> E = mc^2 >$$
>\end{examplebody}
>In the typeset version, the source text of the example body and the
>result would be side by side (hello Frank, nice you managed doing
>this sort of thing in TLC2), in the help text version, an
>appropriately generated image will be placed.

Any idea whatsoever on how that could be achieved in the typeset version?
In general, I frankly don't think it is! (And Frank probably relied on
duplicating code and a certain amount of hacking in the production of
TLC2.) The best you can hope to automate is to have these examples written
to separate files that can then be typeset separately. To that end, you
should probably make use of docstrip and rather write something like

% \begin{exampleshow}
%<*example>
\documentclass[fleqn]{article}
\usepackage{amsmath}
%</example>
% \end{exampleshow}
% \begin{examplehide}
%<*example>
\begin{document}
% \end{examplehide}
% With the fleqn class option to article, the look will be as follows:
% \begin{exampleshow}
$$E = mc^2$$
% \end{exampleshow}
% \begin{examplehide}
\end{document}
%</example>
% \end{examplehide}

>If the next DocTeX format is enhanced like this, we will gain
>
>a) automatically generated help systems including examples and
>graphics in HTML, TeXinfo and other editing-system friendly ways.
>b) instructions sufficient for helping with the entry of commands and
>arguments.
>c) graphical examples and cut&paste code guaranteed to run.
>d) producing TLC3 will just entail listing all the names of the .dtx
>files to some program, and it will be able to gather all the rest
>automatically.
>e) a hyperlink into the complete program source documentation for more
>info.
>
>Of course, for help texts and stuff like that, one should try to come
>up with a nice scheme that would help adding translations into
>different languages, too.
>
>Pipe dream?

(d) definitely is. Some of the other stuff probably could be done, but it
certainly isn't easy.

Targeting PDF should be easier than .info or HTML, because (i) then one
wouldn't have to invent a separate LaTeX parser and (ii) there is no need
it would mean to convert it to .info or HTML.

>Maybe.  But I think there is a case to be made to formalize quite a
>bit more in the usage instructions part of DocTeX files, to a degree
>where mechanical exploitation becomes feasible.

You're probably welcome to develop something. Keep in mind though that you
need some sort of idea how the processing you want to make should be
accomplished before inventing markup for it.

If you do work on this, you'll probably want to take a look at
CTAN:macros/latex/contrib/xdoc/, which reimplements a lot of the inner
workings of doc so that they are not so tied to particular user commands.
Most of it is aimed at enriching the implementation part (the .dtx files I
write are mostly implementation), but it should be useful also for writing
new description part commands. In particular there is a small system for
handling "strings" of arbitrary characters (not just those with catcode
ordinary or letter); this could be useful when making anchor names for