[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Gnu-arch-users] Re: documentation as info
From: |
John Goerzen |
Subject: |
[Gnu-arch-users] Re: documentation as info |
Date: |
Tue, 16 Sep 2003 22:09:09 -0500 |
User-agent: |
Gnus/5.1002 (Gnus v5.10.2) XEmacs/21.4 (Rational FORTRAN, linux) |
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
- Re: [Gnu-arch-users] Re: documentation as info, (continued)
- Re: [Gnu-arch-users] Re: documentation as info, Tom Lord, 2003/09/16
- [Gnu-arch-users] Re: documentation as info, Miles Bader, 2003/09/16
- Re: [Gnu-arch-users] Re: documentation as info, Tupshin Harper, 2003/09/16
- Re: [Gnu-arch-users] Re: documentation as info, Colin Walters, 2003/09/16
- Re: [Gnu-arch-users] Re: documentation as info, Tupshin Harper, 2003/09/17
- Re: [Gnu-arch-users] Re: documentation as info, Tom Lord, 2003/09/17
- Re: [Gnu-arch-users] Re: documentation as info, Colin Walters, 2003/09/17
- [OT] XML foo (was Re: [Gnu-arch-users] Re: documentation as info), Tom Lord, 2003/09/17
- Re: [Gnu-arch-users] Re: documentation as info, David Brown, 2003/09/17
- [OT] Re: [Gnu-arch-users] Re: documentation as info, Tom Lord, 2003/09/17
- [Gnu-arch-users] Re: documentation as info,
John Goerzen <=
- Re: [Gnu-arch-users] Re: documentation as info, Tom Lord, 2003/09/16
- [Gnu-arch-users] Re: documentation as info, Mark A. Flacy, 2003/09/17
- Re: [Gnu-arch-users] Re: documentation as info, MJ Ray, 2003/09/17
- Re: [Gnu-arch-users] Re: documentation as info, Bruce Stephens, 2003/09/17
- Re: [Gnu-arch-users] Re: documentation as info, Miles Bader, 2003/09/17
- Re: [Gnu-arch-users] Re: documentation as info, Colin Walters, 2003/09/16
- Re: [Gnu-arch-users] Re: documentation as info, Tom Lord, 2003/09/16
- Re: [Gnu-arch-users] Re: documentation as info, Robert Collins, 2003/09/16
- Re: [Gnu-arch-users] Re: documentation as info, Tupshin Harper, 2003/09/16
- Re: [Gnu-arch-users] Re: documentation as info, Colin Walters, 2003/09/16