Re: INFO on add-ons

["Stephen J. Turnbull" <stephen@xemacs.org>]

>>>>> "Robert" == Robert J Chassell <bob@rattlesnake.com> writes:

    Robert> Please write a short, introductory document explaining how
    Robert> to convert a document written with XML markup to good,
    Robert> readable Texinfo automatically,

It wouldn't be hard to write such a backend.  But we must agree on a
DTD first.

    Robert> A great XML documentation format has to be constrained in
    Robert> the same way as Texinfo

I would probably investigate a restriction of the DocbookXML DTD to
something isomorphic to Texinfo.

However, I would also want other constraints, constraints that would
make docstring-to-XML/Info conversion easy, and possibly additional
structure that would make it easier to create a structure editor that
moves nodes around.  In particular, nodes would be textually nested in
the markup, rather than implicitly via linking commands such as @menu
and the optional arguments of @node.

I also would like the various link formats (*ref, url, htmlurl) to be
unified in a single element that permits all of them simultaneously.
Designing this will take a fair amount of thought, though.  Eg, if
you're currently using an Info browser, you probably like Info.  So
first the browser tries to follow an Info link; if that fails, an HTML
URL, etc.

    Robert> Also, please explain how to output a document written in
    Robert> an XML format to Info

I don't currently know how to do that, because there is not yet a
suitable DTD.

    Robert> I keep saying `good, readable Texinfo' because I have been
    Robert> told that sometimes, XML sources are harder to read than
    Robert> Texinfo sources;

It shouldn't be hard to fix this.  It would be fairly easy to add a
feature to PSGML (if it isn't there already) to suppress uninteresting
attributes and tags, making _any_ XML more readable in PSGML.  More
important, the restricted Docbook (or whatever) would _have_ to have
fewer "uninteresting" attributes and tags, as they are generally
presentation features which should be excluded from the XML/Info DTD.

    Robert> I can never remember quite how to describe how XML works.

Here's your blurb.  Material in square brackets is rationale that
wouldn't actually appear in the blurb.  Comments welcome.

WHAT IS XML?

An XML processor reads several sets of rules.  The ruleset called the
"DTD" is concerned with the structure of a document.  Basically, XML
says "a document is a single sexp with colored parentheses," and the
DTD describes what colors are permitted, and the nesting rules among
colors.  The ruleset called the "style sheet" is concerned with
presentation of elements, such as logical faces like "emphasis,"
indentation, link coloring or underlining, and so on.

DTDs are written in a language defined by the SGML standard.  Style
sheets have a couple of alternative languages, such as the cascading
style sheet (CSS) specification and XML schemas.  Many processors
support both.  In general, to use XML/Info you will rarely need to
read, much less write, DTDs or style sheets.  But it may be comforting
to know a little about the structure of the process.  And it's
possible that you'll want to read the DTD to understand why the PSGML
mode or the XML processor doesn't like your documents, or the style
sheet to understand the formatting you see on output.

The presentation itself might be quite abstract.  For example, it
would be straightforward to create an XMLlikeTeXInfo DTD that simply
implements Texinfo @ macros as XML elements of the same name.  The
style sheet would simply be the inverse mapping back to Texinfo.  [For
a number of reasons, I would prefer to derive an XMLInfo DTD from
something like DocbookXML, but that's not the users' problem.]

Once set up in this way, you feed the document to the XML processor,
optionally specifying a target format (such as PDF, XHTML, or even
Texinfo as in the example of the preceding paragraph).  Then you
publish the output in the ways usual for the target format.

HOW DO I USE XML/Info?

In order to create an XML Info document source, you first put an XML
declaration at the top of the file, followed by a document type
declaration.  For normal use, these are boilerplate (which would be
automatically inserted by an xmlinfo-mode derived from PSGML).  Then
you use a structure-based editor such as PSGML, along with the style
rules in the Creating a Texinfo File node of Info (suitably translated
to treat XML rather than Texinfo markup) to edit the text and markup.

Finally, you run the XML processor on the document.  There are any
number of XML processors which are suitable for implementing this
process.  [to be filled in with names and URLs, and sample commands]
Most allow you to specify the target.  XML/Info also provides
xml2texi.el, a mode for converting a buffer from XML/Info to Texinfo,
for those who prefer that format for proofreading.  [Hypothetically it
does ;]  xmlinfo-mode would also probably provide C-c C-c bindings for
commands to run the XML processor and produce output.


-- 
Institute of Policy and Planning Sciences     http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba                    Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
 My nostalgia for Icon makes me forget about any of the bad things.  I don't
have much nostalgia for Perl, so its faults I remember.  Scott Gilbert c.l.py