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

[John Goerzen]

Miles Bader <address@hidden> writes:

> My problem with xml/sgml is as a human-edited source language, i.e.,
> what the tla docs are.

As someone that writes a lot in DocBook SGML, as my preferred
human-edited source language, I have to seriously disagree here.

> If you read the source for a DocBook document, and then read the source
> for a document in Tom's doc language, the latter is like a breath of
> fresh air -- you can actually _read_ it, the tagging doesn't get in the
> way.  For documents that are mean to be edited without special structure
> editors, this is _important_.

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.  One rarely does things like indicate bold or italics or
underline or monospace in a DocBook manual.  Rather, you indicate
filename, or command, or argument.  Different outputs may render these
different ways: for instance, manpages have different conventions than
one would usually see in a printed book.

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.

What does it mean when I see:

|whats-missing|

It's not obvious at all, or is it obvious what to do if I want to use
a pipe in my own text.

> I realize that a DocBook document probably has many more tag types, and

I don't see that more tag types really makes that much of a difference
here.

> more functionality, and that Tom's language might become less readable
> if enhanced to the point where they were equivalent.  None-the-less,
> looking at DocBook input, it appears as if the designers simply didn't
> care about this issue, and it shows -- even HTML, horrid though it is,
> tries a little bit to make the markup a  bit more digestible, e.g., by
> using very short tags for common inline annotations (e.g., <i>).

If your quibble is relating to reading, I don't see why longer tags
mean any problem.

> As for sgml-derivatives in general, it obviously depends on the
> particular variant/DTD used -- you can make things a bit better by
> making end-tags omittable (or I guess XML's <tag/> syntax), and thinking

You can end any docbook tag with </>.

> a bit harder about how a human might use it -- but it seems to be a
> common property of the DTDs I've seen that they're way too verbose, and
> clearly not _really_ intended for humans to edit on a regular basis.

I really disagree, as I am a human that edits these things on a
regular basis.  I have made some fairly substantial (100+-page)
documents with it, too, and I must say, for anything of that kind of
length, it shows its true colors with great support for indexing and
table of contents, all controllable on a per-backend basis without
modifying the document at all.  I can do things like suck in other
DocBook documents to mine (or write chapters that are included in
multiple ones.)  Very slick.

> And, yeah, I really do hate <para> / <p> tags.  Christ, would a _little_
> lexical sugar really have hurt all that much...?

There's a point to all that.  If you give a paragraph an id, as with
<para id=asdf>, it can make it easier to refer to later (as in, <link
linkend=asdf>.

-- John