Re: debiandoc vs. docbook

["John R. Daily" <john@geekhavoc.com>]

At (time_t)1032593108 Osamu Aoki wrote:

> On Fri, Sep 20, 2002 at 05:12:42PM -0500, John R. Daily wrote:
> > <email><mailbox>john</mailbox><domain>geekhavoc.com</domain></email>
> 
> I hope this is a joke.  Unless harvesting data or making XML parser
> simple are the objective, it is too verbose.

My .sig wasn't intended to be part of my message, but...

This actually highlights what I perceive to be one of the
strengths of DocBook.

In this particular example, yes, a processor can distinguish the
components.  In general documentation, though, the individual
pieces of, say, a command with arguments are not so easily
distinguishable.

With DocBook, the author can select his or her own level of
detail.  For example, let's assume a document is providing an
example of the use of find and egrep.  The below are all valid,
providing the author and contributors the option of starting
simple and increasing the precision over time.

(This also highlights the fact that to make the transition
successful we should document common patterns.)

<screen>
  <userinput>find /usr/include -name '*.h' | egrep -i
  gid_t</userinput>
</screen>

Or:

<informalexample>
  <screen>
    <userinput>find /usr/include -name '*.h' | egrep -i
    gid_t</userinput>
  </screen>
</informalexample>

Or as complex as:

<informalexample>
  <screen>
    <userinput><command>find</command>
  <parameter><replaceable>/usr/include</replaceable></parameter>
  <option>-name</option>
  <parameter><replaceable>'*.h'</replaceable></parameter> |
  <command>egrep</command> <option>-i</option>
  <parameter><replaceable>gid_t</replaceable></parameter></userinput>
  </screen>
</informalexample>


The author is welcome to stick with the first markup; someone may
well come along and extend it later.

-John