Re: Doc Tasks (was RE: docstrings in Guile!)

["Greg J. Badros" <gjb at cs dot washington dot edu>]

Clark McGrew <mcgrew@ale.physics.sunysb.edu> writes:

> >>>>> "gjb" == Greg J Badros <gjb@cs.washington.edu> writes:
> 
>     gjb> But if we can convert to TeXInfo from DocBook (and rumour has
>     gjb> it that the tools are there, though I've not had time to try
>     gjb> them yet), then these problems go away and we're able to just
>     gjb> use the strictly richer SGML markup.
> 
> What does DocBook have that TeXInfo doesn't have (and you think you'll

I don't know TeXInfo that well, but from a very brief look at the guile
sources, it seems like @code{foo} is used all over the place and tells
me nothing about whether foo is a formal parameter name, a function
name, an expression, or something else.  That's unacceptable.

Actually, I just looked at the TeXInfo page:

  "Thus, you should use `@code' for an expression in a program, for the
name of a variable or function used in a program, or for a keyword.
Also, you should use `@code' for the name of a program, such as `diff',
that is a name used in the machine. (You should write the name of a
program in the ordinary text font if you regard it as a new English
word, such as `Emacs' or `Bison'.)

  "Use `@code' for environment variables such as `TEXINPUTS', and other
variables.

  "Use `@code' for command names in command languages that resemble
programming languages, such as Texinfo or the shell.  For example,
`@code' and `@samp' are produced by writing `@code{@@code}' and
`@code{@@samp}' in the Texinfo source, respectively."

This is *insane*!  We need to distinguish among these incredibly
different cases mechanically.  SGML DocBook gives that to us, TeXInfo
definitely does not.

<snip>

> It's also easy to add new tags to TeXInfo, but I've always thought
> that was a bad idea.

Yep, especially when DocBook has been iteratively refined to be pretty
damn complete for lots of big documentation projects.

Greg