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

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

 DocTeX -- the next generation? David Kastrup <[log in to unmask]> Sun, 21 Mar 2004 17:59:38 +0100 text/plain (101 lines) 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:   File: latex.info, Node: \makebox, Next: \mbox, Prev: lrbox, Up: Spaces & Boxes   \makebox   --------      \makebox[width][position]{text}'      The \makebox' command creates a box just wide enough to contain the   text' specified. The width of the box is specified by the optional   width' argument. The position of the text within the box is   determined by the optional position' argument.      * c' -- centred (default)      * l' -- flushleft      * r' -- flushright      * s' -- stretch from left to right margin. The text must contain        stretchable space for this to work.      See *Note \makebox (picture)::. and so forth and so on (not to mention syntax highlighting). Now the usual way DocTeX files describe things are with \DescribeMacro{...}, with examples of code, with the synposis of commands (using things like \marg, \oarg and so in the descriptions). I would propose that the next iteration of DocTeX should try to formalize most of the stuff into somewhat more rigid patterns. It would appear that the material before \StopEventually{} would usually, if just given a bit more formal markup, 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. 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. The usual AUCTeX input system will let you do something like C-c RET \makebox RET optional width: RET optional position: RET text: Or, if the synopsis specifies that \makebox is considered to be long' in some manner, it will just place {} with the cursor inside and revert to normal text editing again. 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? 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. -- David Kastrup, Kriemhildstr. 15, 44793 Bochum