Received: from mail.proteosys.com ([213.139.130.197]) by nummer-3.proteosys with Microsoft SMTPSVC(5.0.2195.6713); Tue, 23 Mar 2004 16:11:48 +0100 Received: by mail.proteosys.com (8.12.10/8.12.2) with ESMTP id i2NFBg1s016758 for ; Tue, 23 Mar 2004 16:11:45 +0100 Received: from listserv.uni-heidelberg.de (listserv.uni-heidelberg.de [129.206.119.176]) by relay2.uni-heidelberg.de (8.12.10/8.12.10) with ESMTP id i2NF4xSe006158; Tue, 23 Mar 2004 16:04:59 +0100 (MET) MIME-Version: 1.0 Content-Type: multipart/alternative; boundary="----_=_NextPart_001_01C410E9.2953D200" Received: from listserv (listserv.uni-heidelberg.de [129.206.119.176]) by listserv.uni-heidelberg.de (8.12.7/8.12.7/SuSE Linux 0.6) with ESMTP id i2L77qCW029452; Tue, 23 Mar 2004 16:03:59 +0100 Received: from LISTSERV.UNI-HEIDELBERG.DE by LISTSERV.UNI-HEIDELBERG.DE (LISTSERV-TCP/IP release 1.8e) with spool id 57189 for LATEX-L@LISTSERV.UNI-HEIDELBERG.DE; Tue, 23 Mar 2004 16:03:58 +0100 X-MimeOLE: Produced By Microsoft Exchange V6.5 Received: from relay.uni-heidelberg.de (relay.uni-heidelberg.de [129.206.100.212]) by listserv.uni-heidelberg.de (8.12.7/8.12.7/SuSE Linux 0.6) with ESMTP id i2NF3vN6026730 for ; Tue, 23 Mar 2004 16:03:57 +0100 Received: from ext0.ml.kva.se (ext0.ml.kva.se [130.237.201.25]) by relay.uni-heidelberg.de (8.12.10/8.12.10) with ESMTP id i2NF4Siv004781 for ; Tue, 23 Mar 2004 16:04:29 +0100 (MET) Received: from [130.237.201.206] (dhcp06.ml.kva.se [130.237.201.206]) by ext0.ml.kva.se (8.12.10/8.12.9) with ESMTP id i2NEiRii000038 for ; Tue, 23 Mar 2004 15:44:28 +0100 (CET) In-Reply-To: Return-Path: X-OriginalArrivalTime: 23 Mar 2004 15:11:48.0820 (UTC) FILETIME=[29D0F140:01C410E9] X-Sender: lars@abel.math.umu.se x-mime-autoconverted: from quoted-printable to 8bit by listserv.uni-heidelberg.de id i2NF3wN6026731 X-Scanned-By: MIMEDefang 2.28 (www . roaringpenguin . com / mimedefang) X-Spam-Score: 1.797 (*) DOMAIN_BODY Content-class: urn:content-classes:message Subject: Re: DocTeX -- the next generation? Date: Tue, 23 Mar 2004 15:44:03 +0100 Message-ID: A X-MS-Has-Attach: X-MS-TNEF-Correlator: Thread-Topic: DocTeX -- the next generation? Thread-Index: AcQQ6SnvOAoSHBvURSuHMpu8UP2BxA== From: =?iso-8859-1?Q?Lars_Hellstr=F6m?= Sender: "Mailing list for the LaTeX3 project" To: Reply-To: "Mailing list for the LaTeX3 project" Status: R X-Status: X-Keywords: X-UID: 4769 This is a multi-part message in MIME format. ------_=_NextPart_001_01C410E9.2953D200 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable 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} >\begin{equation} > E =3D mc^2 >\end{equation} >\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} \begin{equation} E =3D mc^2 \end{equation} % \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=F6m ------_=_NextPart_001_01C410E9.2953D200 Content-Type: text/html; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable Re: DocTeX -- the next generation?

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}
>\begin{equation}
>  E =3D mc^2
>\end{equation}
>\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}
\begin{equation}
  E =3D mc^2
\end{equation}
% \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
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=F6m

------_=_NextPart_001_01C410E9.2953D200--