Print

Print


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 = 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