discuss: part of the review?
Subject:
Re: part of the review?
From:
David Lawyer ####@####.####
Date:
3 Aug 2001 08:21:02 -0000
Message-Id: <20010803010839.A9664@lafn.org>
On Sat, Jul 14, 2001 at 11:22:50PM -0700, Poet/Joshua Drake wrote:
> Hello,
>
> We are never going to get anywhere with this David. It is purely opinion.
> On one hand, we have the opinion of major publishers and documentation
> projects that using DocBook is a good choice.
Sorry for taking over 2 weeks to reply, but during this time I've
changed my views a little, partly as a result of attending the
"summit" in San Diego. While much of the summit concerned sgml->xml,
here's the last line of a summary writeup (written by Norman Walsh
enclosed in <p> tags):
<p>Need something simpler than DocBook; perhaps LinuxDoc can become
that</p> I wonder where that idea came from :-)
At any rate I think that some more tags are needed in LinuxDoc for the
header part. This isn't much of a burden to use since stuff in the
header is usually only written once (and the tags are used nowhere
else). In addition, the presentation-type tags in LinuxDoc (such as
italics) need to be somehow changed to content-tags that
machine-translate unambiguously into docbook.
I see docbook as the standard for Linux documentation (but not
necessarily the standard for submitting a doc or for editing it). I
see two roles for LinuxDoc: 1. A simple format to use that will
convert cleanly into DocBook. 2. A simple stand-alone markup language
for a multitude of uses. So in one role LinuxDoc is a a pre-source or
a primary source. After machine conversion of LinuxDoc, DocBook
becomes the secondary source. Some people write directly in Docbook.
I hope that you're aware that one factor pushing DocBook is that it
can provide all the info needed to print a doc. Yet due to the rapid
obsolescence of docs, printing is (in most cases) not the best form of
distribution. So if it were not for printing, I don't think that
docbook would be needed. With good search engines there's less need
for content tags since such search engines can usually find what
you're looking for better than the tags can.
>
> On the other, we have your opinion. Which is valid in its own right.
> However, and I mean no disrespect, it appears to me that you have possibly
> got set in your ways and are afraid (maybe the wrong word), unwilling? to
> take the 2 hours it would take to understand basic DocBook.
>
> Or, on the other hand, you may understand DocBook but you feel that the
> people who write for the LDP shouldn't have too. I am of a different
> opinion. If these people are smart enough to run Linux, and they have the
> time and willingness to document parts of it. They should have the time to
> learn DocBook.
I haven't spent any time learning docbook except to look over one of
my docs which was converted into it. I have also looked at a docbook
template. If one knows linuxdoc, there isn't much to learn except for
all the new tags and the nesting. There are apparently complex rules
for this, but I don't know them. So I claim that even if one is
eventually going to learn docbook, most all of what learns in linuxdoc
is still applicable. I hope to spend some more time on docbook.
I could easily start using docbook but I suspect it would require a
few percent additional time to maintain my docs. How could one
measure this extra time? I would have to worry about paragraph tags
and would also need to continue to separate paragraphs by blank lines
to make them look good. I often spit a paragraph into 2 pargraphs and
this would be messy in docbook. There would be more macro definitions
to learn in vi.
Of course authors can learn docbook and use it. But is it worthwhile?
Most people (of the type we need) are quite busy and will not do
something that's not worthwhile. If they were going to do a lot of
writing, then it might be worthwhile to learn docbook. But suppose
they do very little writing. Suppose they have have an idea for a
short doc of say 200 lines. To learn docbook and use it might make
the task of writing it over twice as difficult. Then maintaining it
will take a little longer too. There are a large number of people
that would be willing to write a short doc as compared to the few that
are willing a take on longer ones (or multiple docs).
Suppose docbook imposes an overhead cost of 3% as compared to
linuxdoc. Since there are (or will be) many thousands of docs (not
just LDP's) it may take almost a million person-hours per year in
writing and maintaining them, and learning the tools. 3% of this is
30k hours. At say $20/hr (even though they're unpaid) that's a cost
of $600,000. Wouldn't it be better to use that 30k hours (or the
$600k they could earn by the time saved by not using docbook) to
improve the documentation? This may be overstated since not everyone
would write in LinuxDoc, but you get the idea.
> They can use Simplified DocBook if they like, and they don't need to use
> all the tags. At Command Prompt, we only use maybe 30 of the tags.
I've already pointed out the problems here: nested tags (more tags),
end tags (more tags), longer tags, and required paragraph tags
(still more tags). The nesting scheme of docbook is unfortunately not
eliminated.
Show me a markup language simpler than LinuxDoc and I might support
using it. Well, there's SimpleDoc (supposedly replaces sdf) and pod.
Debian has sdf (Simple Document Format). Pod doesn't seem to support
a table of contents and has style (presentation) tags like "italics".
sdf has macro definitions, if statements, etc. It looks too complex
and it's "tags" are denoted by a variety of symbols. SimpleDoc gives
few returns on a search engine and may be even more complex. A
proposal for it says it should be a superset of xml (but I don't know
if this happened). Anybody know about these? So from what I've seen
so far, I'll stick with LinuxDoc and hope it gets improved.
David Lawyer
