Re: [Groff] Re: Simplifying groff documentation

[Zvezdan Petkovic]

On Sat, Dec 23, 2006 at 12:25:01AM -0500, Eric S. Raymond wrote:
> I *am* "skilled hands" in that sense, having done successful
> full-length technical books in all three markups.  Speaking from
> that experience, I rate groff better than TeX but inferior to a good
> DocBook toolchain (with the exception that TeX wins over both if you have
> to do really intensive mathematical typesetting).

I would classify myself as "skilled hands" too and I agree with your
assessment of *roff and TeX (I used both extensively).  However, I did
write a 10 page technical document (34 with the appendices that simply
include the files) in DocBook-XML.  I have turned away in disgust and
never looked back.  This paragraph can be representative of what I
thought was wrong:

      Use either <command>cp -a</command> or
      <command>cp -Rdp</command> when copying, to preserve as much of
      the original attributes of an application.
      Then in <filename>rootfs/sbin</filename> make a
      <emphasis>hard</emphasis> link from <command>mke2fs</command> to
      both <command>mkfs.ext2</command> and
      <command>mkfs.ext3</command>.

Also the syntax required to just include the files for appendix was
incredibly convoluted.

  <appendix id="kernelcfg">
    <title><filename>.config</filename> &mdash; kernel configuration
      file</title>

    <para>
      <programlisting><inlinegraphic
        fileref="config/kernel.config"
        format="linespecific"/></programlisting>
    </para>
  </appendix>

I can be classified as "skilled hands" with both Vim and Emacs.
I've made my own Vim filetype plugin to insert DocBook keywords easier.
Emacs (which I used to use for more than a decade) already has a DocBook
support.  Yet, I did not see them as an effective toolchain for a
writer.  I can't possibly imagine what could be an effective toolchain.

One still has to select for each of these words whether they are
command, filename, emphasis, acronym (over 100 possibilities in
DocBook).  The selection must be done through some sort of menu
(remembering all 100+ possibilities couldn't be called comfortable I
guess).  And that is slow, very slow.  It's also distracting from the
writing.  If I don't want to be distracted I could postpone the tagging
for later.  I'm afraid that then, I could simply omit a tag where I
should have put it.

I really wanted to start using DocBook more and invested some effort to
make it happen.  In the end I concluded that it's more of a trouble than
it's worth.  So I use groff or (La)TeX and produce PDF.

You mention above a good DocBook toolchain.
Can you give us some detail?
What do you use to produce DocBook-XML documents effectively?
If you consider that this is off topic for the groff list, you can reply
off the list.  I'm really interested in giving DocBook another chance.

        ZP