[vox-tech] DocBook

[Micah Cowan]

On Thu, Jan 17, 2002 at 03:33:33PM -0800, Peter Jay Salzman wrote:
> begin Micah Cowan <micah@cowanbox.com> 
> > MOn Thu, Jan 17, 2002 at 01:31:04PM -0800, speck@blkmtn.org wrote:
> > > On Thu, 17 January 2002, Micah Cowan wrote:
> > 
> > In conclusion:  If you are already a TeX- or LaTeX-guru, you probably
> > have little reason to switch to DocBook (except that you need to write
> > in DocBook format to write LDP HOWTOs, as Pete discovered).  I picked
> > it because it suits my particular needs, and YMMV, as always.
>  
> heh.  i consider myself a docbook "layperson".  i know enough to use it
> effectively, but not enough to really understand all the terminology and
> "bit's and pieces" of docbook.
> 
> as a layperson, i definitely defer to micah who seems to have attained
> guru status in this area.

Not even remotely.  After I've done some serious XSLT and XSL-FO
study, then maybe call me that.

> from my own POV, here are some comments for
> other laypeople:
> 
> 1. docbook hurts the fingers.  whereas latex users can talk about
> 
>    \url{http://slashdot.org}, {\bf vmlinuz} and {\it important stuff\/},
> 
>    docbook users talk about:
> 
>    <systemitem role="url">http://slashdot.org</systemitem>,
>    <filename>vmlinuz</filename> and <emphasis>important stuff</emphasis>

Maybe vi-users get their fingers hurt, but psgml-mode Emacs-users
have a plethora of key-sequences which make the job much more
palatable.  Tag-name autocompletion, automatically end-tag, etc.  My
favorite feature is that if you tell psgml where to get the DTD from,
whenever you tell it to insert an element it automatically adds any
attributes or elements that you need to fill in.  For instance, if I
type "C-c C-e section RET" (to use emacspeak), I'll get:

  <section>
    <title></title>

    <!-- one of para, simpara, figure, ........ the full list of
    possible elements placed here -->
  </section>

With my cursor at the title element, ready for me to type in a title.
If I type "C-c C-e link"

Then I'll get a query for the value of the mandatory "linkend"
attribute, and then:

  <link linkend="foobar"></link>

Saves a lot of typing.

>    god forbid you write a paper about something like
>    <application>dosemu</application>, and you have two choices:
> 
>    <enumeratedlist>
>    <listitem><para>Carpal tunnel syndrome.</para></listitem>
>    <listitem><para>Make good use of <application>vi</application>
>       macros.</para></listitem>
>    </enumeratedlist>
> 
>    compare with:
> 
>    \begin{enumerate}
> 	\item Carpal tunnel syndrome.
>    \item Make good use of {\bf vi} macros.
>    \end{enumerate}

Might want to look into Blatte, which was actually written by a new
coworker of mine (works in my group).  It's basically a programmable
shorthand language which is converted to HTML.  Easy enough to adapt
to SGML or XML in general, I should think.

>    it may look like a small difference now, but write a 10 page
>    document, and you're talking about a significantly higher typing to
>    content ratio.

With the Emacs functionality I described, it's not a problem.
Especially since if I have text I'm constantly using, I can write an
entity to save myself typing:

  <!ENTITY foo-class "<link linkend='my-foo-class'><classname>Foo::Bar</classname></link>">

 And then I can just use &foo-class; instead of all that stuff.

> 2. for the average latex user, docbook is a loss of control of format.
> 
>    for me, the HYPER use of content based markup is a double edged
>    sword.  i know you can modify stylesheets.  but danged if i know how!
>    it doesn't look easy.  with latex, i can control the location of
>    every single dot of my document.  and sometimes latex isn't happy
>    about the choices i make,  like under/overfull hboxes and vboxes,
>    pictures that don't "float" well, i can ALWAYS force the issue.

No real argument here.  Of course, an extremely well-designed DTD
could give you this same power, but DocBook doesn't have the same
level of detailed power control.

> ok, that being said, my recommendation is: if you have a choice of latex
> or docbook, definitely pick docbook, hand's down.  micah's reasons for
> using it are much more persuasive than my reasons for not using it.
> and the fact of the matter is, i do use docbook, grudgingly.

I'm surprised at your conclusion.  What reasons were those?  From my
perspective, I didn't think that any of the reasons I offered were
very strong advantages over LaTeX.  And the loss of direct control is
usually a very big deal to me (somehow not big enough in this case, I
guess).

Micah