Received: from mail.proteosys.com ([213.139.130.197]) by nummer-3.proteosys with Microsoft SMTPSVC(5.0.2195.6713); Sun, 21 Mar 2004 18:17:00 +0100 Received: by mail.proteosys.com (8.12.10/8.12.2) with ESMTP id i2LHGv1s004355 for ; Sun, 21 Mar 2004 18:16:58 +0100 Received: from listserv.uni-heidelberg.de (listserv.uni-heidelberg.de [129.206.119.176]) by relay.uni-heidelberg.de (8.12.10/8.12.10) with ESMTP id i2LHBIiv008059; Sun, 21 Mar 2004 18:11:18 +0100 (MET) MIME-Version: 1.0 Content-Type: multipart/alternative; boundary="----_=_NextPart_001_01C40F68.52008E00" 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 i2L77qU2029452; Sun, 21 Mar 2004 18:09:18 +0100 X-MimeOLE: Produced By Microsoft Exchange V6.5 Received: from LISTSERV.UNI-HEIDELBERG.DE by LISTSERV.UNI-HEIDELBERG.DE (LISTSERV-TCP/IP release 1.8e) with spool id 53557 for LATEX-L@LISTSERV.UNI-HEIDELBERG.DE; Sun, 21 Mar 2004 18:09:17 +0100 Received: from relay2.uni-heidelberg.de (relay2.uni-heidelberg.de [129.206.210.211]) by listserv.uni-heidelberg.de (8.12.7/8.12.7/SuSE Linux 0.6) with ESMTP id i2LGxGN6001416 for ; Sun, 21 Mar 2004 17:59:17 +0100 Received: from fencepost.gnu.org (fencepost.gnu.org [199.232.76.164]) by relay2.uni-heidelberg.de (8.12.10/8.12.10) with ESMTP id i2LGxlSe020155 for ; Sun, 21 Mar 2004 17:59:48 +0100 (MET) Received: from fencepost.gnu.org ([127.0.0.1] helo=lola.goethe.zz) by fencepost.gnu.org with esmtp (Exim 4.24) id 1B56EU-0005Mz-Dh for LATEX-L@listserv.uni-heidelberg.de; Sun, 21 Mar 2004 11:55:30 -0500 Lines: 101 Return-Path: X-OriginalArrivalTime: 21 Mar 2004 17:17:00.0811 (UTC) FILETIME=[527C4DB0:01C40F68] User-Agent: Gnus/5.09 (Gnus v5.9.0) Emacs/21.3.50 X-Scanned-By: MIMEDefang 2.28 (www . roaringpenguin . com / mimedefang) X-Spam-Score: 0 () Content-class: urn:content-classes:message Subject: DocTeX -- the next generation? Date: Sun, 21 Mar 2004 17:59:38 +0100 Message-ID: A X-MS-Has-Attach: X-MS-TNEF-Correlator: Thread-Topic: DocTeX -- the next generation? Thread-Index: AcQPaFKfehxwCWKvQyCn9a6jcQpxlw== From: "David Kastrup" Sender: "Mailing list for the LaTeX3 project" To: Reply-To: "Mailing list for the LaTeX3 project" Status: R X-Status: X-Keywords: X-UID: 4762 This is a multi-part message in MIME format. ------_=_NextPart_001_01C40F68.52008E00 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable 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} \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. 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 ------_=_NextPart_001_01C40F68.52008E00 Content-Type: text/html; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable DocTeX -- the next generation?

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}
\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.

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

------_=_NextPart_001_01C40F68.52008E00--