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

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

 Subject: Re: DocTeX -- the next generation? From: David Kastrup <[log in to unmask]> Reply To: Mailing list for the LaTeX3 project <[log in to unmask]> Date: Tue, 23 Mar 2004 17:27:43 +0100 Content-Type: text/plain Parts/Attachments: text/plain (187 lines)

> At 17.59 +0100 2004-03-21, David Kastrup wrote:
> >
> >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.

Whatever.  Of course I meant the markup commonly employed for
documentation, not the mechanism behind it.  So what I am bothering

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

No, I mean mandatory and formalised markup.  In order for this to be
acceptable, it will have to become richer, too.

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

The part before \StopEventually{} in preview.dtx is turned by a perl
script into structured Texinfo documentation (a chapter in the
Texinfo manual).  So there is some subset that works (more or less
accidentally, since the author massaged the Perl script _until_ this
was the case).

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

I am not, repeat not, talking about any LaTeX->something converter.
That is defeating the whole point entirely.  I am explicitly talking
about restricting oneself to a format that is parseable without much
LaTeX or TeX knowledge, by separate tools that are not yet written.

[typeset example aside of input]

> Any idea whatsoever on how that could be achieved in the typeset
> version?

Running external programs on external files and using pdfpages and
similar.  Nothing that write18 could not do, or a Makefile in a
multipass setting.

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

I don't let myself be dictated what I can hope for.

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

Using LaTeX isn't easy.  The existence and utility and necessity of
TLC in the first place is an admittance that the .dtx file is not
working for the purpose of providing accessible documentation to the
user.

Personally, I'd be willing to pay three times the price of TLC easily
to have the information readily accessible.  And that does not mean a
batch of scattered dvi files (which are for printing, not screen
viewing), but something like TeXinfo with embedded graphics and
copy-and-paste code (preview-latex).  Unfortunately, I had to postpone
a personal project in that area which I wanted to get going last year

But that does not mean that task in itself is nonsensical.

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

PDF is junk.  You can't cut&paste from it, and it is a format fit for
printing, not screen viewing.  I want to have screen fonts, I want to
have a screen layout, I don't want to have page-oriented stuff and so
on.

This is supposed to result in material that one can work with, not
material that one will have to print out in order not ruin his eyes.

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

I don't have time left over.  I am not doing LaTeX development in my
free time, but my whole time, and so my pet projects suffer vastly

It's a pity, but I can't keep as much going as I consider
worthwhile.  My target line is to make LaTeX an acceptable standard
way of producing text in the humanities, and this involves
a) catering for layouts no other system can produce (my current
bigfoot work)
b) having a standard editing platform that conveniently supports
everything needed (I am project leader for AUCTeX and preview-latex
and Emacs developer/nagger)
c) documenting the complete work flow required to arrive at the
result.  It is not acceptable to have to consult a dozen different
books in order to produce a footnote (LaTeX documentation, editor
documentation, operating system documentation, various installation
manuals of TeX, FAQs for telling which systems to prefer and why,
and so on and so on).
d) working on further usability projects.

I'll not be able to start writing a book before next year at the
earliest, and Frank can testify that one wants to rather have things
changed than document the ugly.

While I can't work on a lot of things yet, I can tell people not to
overlook them so that at some later point of time either I myself or
somebody else can take up the task without unnecessary complications.

That is why I am saying here that the lack of machine readability of
the user documentation part of .dtx files is a problem.

Never mind about the code part: I don't see any immediate necessity
for having that being autoconverted into other formats.  Even though
things like a LaTeX error hyperlinking to the .dtx source or so would
be nice at times (but then TeX would need to keep track of the source
of tokens).

--
David Kastrup, Kriemhildstr. 15, 44793 Bochum