Re: INFO on add-ons

[Robert J. Chassell]

       Miles> ... how did people write info files then (by hand?!)?

"Stephen J. Turnbull" <address@hidden> responded:

   Been there, done that.  Texinfo is not an improvement, if restricted
   to generating Info files.  (Obviously the retargetable backend is a
   _huge_ improvement, and I wouldn't go back, ...

and then said:

    .... although I'd like to go forward from Texinfo to XMLinfo.)

Please write a short, introductory document explaining how to convert
a document written with XML markup to good, readable Texinfo
automatically, so it can then be converted to DVI (and Postscript,
PDF, etc), to HTML, to Info, and back again to DocBook and XML.

Also, please explain how to output a document written in an XML format
to Info and to the various other output formats. 

This is important.

Pretty obviously, many people are writing documentation in some form
or other of XML.  The best can be converted to Texinfo.  Some XML
formats require high resolution interfaces for people using their
eyes; these formats are poor for documentation.

Note that one of the major goals of Texinfo is to inspire and
constrain people to write documentation that is readable when typeset
and printed, when using a slow connection, or when working eyes-free
(as with driving a car or being permanently blind).  (That is to say,
`readable' means `listen-able using Emacspeak to convert text to
speech'.)

More than a decade ago, we considered switching from Texinfo to LaTeX
as the base markup language.  However, I found that people tended to
use LaTeX as a markup language for high-resolution typesetting and it
could not be used in all the output formats that Texinfo supports.

A great XML documentation format has to be constrained in the same way
as Texinfo -- this means that the best test for a great XML
documentation format is that it converts to good, readable Texinfo
automatically.

(I keep saying `good, readable Texinfo' because I have been told that
sometimes, XML sources are harder to read than Texinfo sources;
obviously, if this is true, we want to make sure that Texinfo keeps
its good qualities; and in any case, the converter should do a good
job.)

I am primarily a Texinfo person; I know little about the procedures
for converting one or other XML format to Texinfo (although I have
done it , to be sure it can be done).  I can never remember quite how
to describe how XML works.  (I.e., XML itself is not a mark up
language, but is a set of rules for creating different ones.  What
determines the mark up language itself, and how do you employ that?)

I cannot remember how to determine whether an XML source can be
converted to at least as many different output formats as Texinfo, nor
how to do that.  I cannot remember how to convert an XML source to
Texinfo.

I do remember how to convert Texinfo to DocBook and XML -- I put the
commands in the front of documents I write, so it is easy for me to
check my work by copying the commands and executing them in a shell.
For example:

    ## DocBook output
    makeinfo --docbook --no-split --paragraph-indent=0 \
    --verbose Rights-duty-metaphor.texi

    ## XML output
    makeinfo --xml --no-split --paragraph-indent=0 \
    --verbose Rights-duty-metaphor.texi

Please tell me how to create a file for printing, how to 
convert to Info, and how to convert to HTML these DocBook and XML
outputs that makeinfo creates.  

Also, more generally, please tell me about and what to do with XML:
how to convert to Texinfo, how to convert to the various output
formats, how to determine if the XML format is any good for
documentation and what the good ones are, where to get them for
sources, and how to install them from Debian.

And when you write, please presume that at least one of your readers
(me) is very tired, does not have much time, is situationally (or
maybe natively) stupid ....  and will have to come back to what you
wrote to determine yet again how to do the simplest thing.

Thank you.

-- 
    Robert J. Chassell            address@hidden  address@hidden
    Rattlesnake Enterprises       http://www.rattlesnake.com
    Free Software Foundation      http://www.gnu.org   GnuPG Key ID: 004B4AC8