Re: [Groff] Re: Simplifying groff documentation

[Michael(tm) Smith]

Zvezdan Petkovic <address@hidden>, 2006-12-23 15:06 -0500:

> 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.
>
> 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.

I personally think it's a pretty bad idea to attempt to do any
extensive editing of DocBook (or most other forms of XML) in Vim.
I know there are people who do it, but I guess their pain
threshhold is a lot higher than mine.

I say that as someone who uses Vim exclusively for all my text
editing. Except for editing XML. (I do use Vim for doing touch-up
changes to XML documents, but not for any serious editing).

> 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.

If you've not completely sworn off Emacs, you might want to try
nxml-mode for Emacs -- it's packaged for some distros and
downloable from here:

  http://www.thaiopensource.com/nxml-mode/

It's the one thing I actually use Emacs for.

The difference between using that and using Vim to edit an XML
document is that nxml reads the actual DTD (actually, a RELAX NG
schema) for whatever document instance you're editing. So it can
give you context-sensitive completion for element and attribute
names -- and always flags, in real time, any parts of your
document that are not valid according to the schema you're using.

> 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.

There are many other people that have tried it and run into the
same frustrations. Using a good editing application like nxml
helps a lot, but even then, for a lot of people, authoring their
source in DocBook is far from being their preferred means writing
up documentation. Though I like it just fine myself.

I'm not sure what could be done to make it easier. Any XML
vocabulary that gives you way to mark up a wide range of content
semantically rather than just presentationally is going to have
the same degree of complexity -- roughly the same number of
element and attribute names.

I know there are some mechanisms that allow you to use plain text
with simple Wiki-like markup, and generate DocBook output from
that.  But the level of semantic markup they provide is really
limited.

  --Mike