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

#### View:

 Message: [ First | Previous | Next | Last ] By Topic: [ First | Previous | Next | Last ] By Author: [ First | Previous | Next | Last ] Font: Proportional Font

Subject:

Re: DocTeX -- the next generation?

From:

Date:

Tue, 23 Mar 2004 15:44:03 +0100

Content-Type:

text/plain

Parts/Attachments:

 text/plain (143 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} % % \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} % % \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 to worry about whether the text will survive the typographical downgrading 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 hyperlinking and such things. Lars Hellström