Re: [Gnu-arch-users] Re: documentation as info

[Tom Lord]

    > From: John Goerzen <address@hidden>

    > Actually, I found it the opposite.  When I look at a DocBook document,
    > I can tell immediately what I'm looking at: something that's supposed
    > to be a program listing is labeled as <programlisting>, footnotes are
    > labeled as <footnote>, etc.

    > The very nice advantage of this is that it separates presentation from
    > content.  

That's precisely why I made my .doc format.  It works quite well as a
pun for comments in C source code.  The input to .doc format is _also_
the presentation of content.  (It's uses in docs not derived from
source, like the tutorial, are largely a matter of "it was there; it's
convenient; i'm not adding to the list of dependencies if i use this")


    > When I look at Tom's language, I can't tell what I'm seeing.  For
    > instance, at the top of a file, it has /* copyright statement (several
    > lines here) */.  Then for an apparent section, it looks like the whole
    > thing is a comment.  I don't know how monospaced type is indicated for
    > things that occur within a paragraph, and I can *guess* that for long
    > examples, if the line starts with whitespace, it's treated as
    > monospace.

Other users have found that a few minutes of looking back and forth
between .html output and .doc source resolves these mysteries.

I very much do not claim that the .doc foo is a work of art or, in the
slightest degree, properly documented.  It's an unfinished line of
development.  But it's not nearly so mysterious as you indicate.


    > What does it mean when I see:

    > |whats-missing|

It means "Add an index entry for `whats-missing' referring to this
point in the text."   It seemed like a reasonably unobtrusive notation
and one that could be reasonably processed by many
imprecise-yet-useful tools.  Like, say, `grep'.


-t