Bored to tears! [Was: Requiring use of DocBook; LinuxDoc]

[Jeff Waugh <jdub@aphid.net>]

> Actually, Greg, I think you're the one washing hogs here.  DocBook has 321
> tags divided into 25 classes. Here's the content model for just one of
> them, the <para> tag:


8<   BS Snip   8<

This is my first post on the topic because I've been happy to ignore the
tripe you've been dishing out. Still on this? It's like a broken recor-
broken recor- broken recor- broken recor- broken recor-

Listing the allowable elements within the <para> tag does *not* prove
DocBook a complicated mess. Try listing the allowable elements under a <p>
tag in HTML. There's still a fair few, and HTML is bloody easy to come to
grips with.

Obviously, HTML is a very generalised DTD, and doesn't need the specifics
that DocBook provides. DocBook is a DTD for writing documentation, usually
technical. Documentation isn't a dance in the woods, it's a very precise
art, and DocBook requires this detail to even be in the running as a
documentation DTD.

You're not writing childrens' books when you're using DocBook, Gary. YOU'RE
WRITING DOCUMENTATION. Documentation is hard. Documentation is detailed
work.


> Do you know which they are and what they mean?


/me pulls out his cluestick

Gary, the LDP's needs for documentation are fairly simple. The understanding
required to write a good HOWTO can be spoonfed in a straightforward document
about writing for the LDP (which, surprise, surprise, already exists).

DocBook scales up well, and the potential for automated systems based on it
are huge. Specifics are good. It would be a massive backwards step to allow
new documents to be written in the older formats - future growth requires a
DTD as powerful as DocBook.


> More particularly, can you edit a <para> and get it right the first time?


<para>Oh, for God's sake.</para>

<para>Writing <productname>DocBook</productname> is a
<emphasis>lucid</emphasis> experience; it flows. The <sgmltag>para</sgmltag>
tag happens to be one of the basic elements in which just about everything
resides, and yet you've used it as an example of complication. You can put a
lot of things in a bucket, but a bucket is not a complicated tool. This is
essentially what the <sgmltag>para</sgmltag> tag is.</para>

<para>Really, in your average LDP document, how much harder is it than
this?</para>


> Can you use the legal tags correctly?


I'm not stupid, Gary. Neither are other interested documenters. Please don't
insult my intelligence by presuming DocBook to be too hard for me.


> Do you know what they do?


See, there's this fantastic book that you can keep by your side and refer to
whenever you're not quite sure of something, or for those sudden moments of
insanity when you think there may be a better solution for what you're doing.

There's also a website with exactly the same content (by jove!) which you
can keep open in your browser as you document. There's even a downloadable
version.

If you're stuck on Windows, you can even get an HTML Help version, which is
almost too simple to use.

And Gary, if you reckon that an unfortunate symptom of DocBook's complexity
is the need to refer to DTDG, then you'll be surprising most people who ever
learned anything in their lives. You want to program that VCR? Read the
manual. You want to learn the GTK+ API? Read the website. You want to write
documentation in the DocBook format? Read the book.

There is a common name for all of these references, and we call it
"documentation". If you're part of a documentation project, and you think
reading documentation is too hard - you're doing something wrong.


> I don't think anybody can use the full scope of DocBook even with
> assistance.


I'm sorry to hear that Gary. I'm sure the engineers using Docbook at
Mitsubishi, Compaq, and numerous other places are pretty sorry to hear that.
I'm also sure that everyone partaking in the recent explosion of interest
surrounding DocBook are sorry to hear that.

There is a simple summary of DocBook for writing LDP documents. This is
sufficient knowledge to begin with. DocBook isn't hard at all, when you
understand the need for the specific tags. Collaborative projects such as
the LDP can only help exponentially in the process of learning it, because
as you write, you receive comments and patches informing you of things you
didn't know before. This is good. This is a wonderful way to learn.


<RabbitInOurHeadlights>Gary, DocBook is a damn fine format for the project.
It's not hard when you read the appropriate documentation, and there's no
reason to spoil our productivity by using older, less useful formats. I
think you may want to find a new direction in which to enhance the project.
Putting your energy into the various helper documents would probably be a
good thing.</RabbitInOurHeadlights>


*SO* bored of this bollocks.

- Jeff


-- jdub@aphid.net ------------------------------------- jdub@linux.org.au --

   w: http://www.slug.org.au/
   i: 16341281 (jdub!)
   q: "In addition to these ample facilities, there exists a powerful
       configuration tool called gcc." - Elliot Hughes, author of lwm


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org