[Gnu-arch-users] doc formats

[Thomas Lord]

There's a general sentiment against (what I'm calling) a 
wiki-style markup but I really don't see why.

One of the possibilities Andrew suggests is:

 > Plain text. Difficult to convert to HTML or print, but if you don't
 > care, this is by far the easiest option.

I think that the priorities for the docs, in order, are:

      1. quality as plain text and in source form
      2. quality as HTML or print
      3. quality as semantic-markup XML

with none of those being particularly *un*important.

I also observe that for technical documentation the 
variety of mark-up needed is almost always quite 
small.   One wants to be able to say (with mark-up)
"this section documents a function named FOO" and
a few things like that.   One wants stress, emphasis,
lists, simple footnotes, simple tables, sections, chapters
...  Perhaps the runners up are mathematical notations 
and simple diagrams.

With the exception of the diagrams each of those kinds
of mark-up has a familiar ASCII-art rendering.  _Right?_

So I advise:

     1. Make the source form and plain text form
        the same.   Writers can make the plain text
        look nice by hand.

     2. Make the plain-text conventions for lists,
        stress, emphasis, sections, function documentation
        etc. syntactically unambiguous and easy to 
        cheaply parse.   This is certainly the hardest
        part -- designing both an unambiguous syntax and
        a parser for it.   Some parts (e.g., stress, 
        emphasis) are easy but other parts (e.g., tables
        that look nice *in source form*) require pretty
        unconventional parsing techniques.  In spite
        of the trickiness, this is a tractable problem
        that admits solutions in the <10KLOC range.

     3. Write a translator that accepts such source
        forms and emits XML, preserving the non-ambiguity
        of the mark-up.

     4. Write XSLT filters to generate the specific flavor
        of XML you want for downstream processing.

This problem -- how to mark-up technical docs -- has been around
and annoying for decades with many half-baked solutions being
generated and used as a stop-gap.  The amount of effort that has
been spent on and working around half-baked solutions seems to me
to be many multiples of what it would take to do right.  The 
technology I'm describing to solve the problem has many interesting
applications.

-t