[OpenAFS-Doc] State of the documentation presentation?

[chas williams - CONTRACTOR]

In message <87lk4z5tgy.fsf@windlord.stanford.edu>,Russ Allbery writes:
>My personal feeling on the latter is that one of the biggest barriers to
>entry on DocBook (and one of the reasons why the POD pages have gotten
>much more attention) is that DocBook is ginormous and horribly
>intimidating.  I have no idea what tags to use for common things when
>writing in DocBook, and the manuals and references leave me drowning in
>too much information.

it seems intimidating at first, but docbook is much easier than it looks.
once i got the hang of the basic conversion from .html to docbook
using tidy, it was pretty easy to edit things.   a few things needed
to be hand converted, like notes/cautions, which initially where
converted to single item tables as i recall.

the online version of the docbook manual is pretty handy.  that is
all i needed once i got going.

>I would really like to see someone write up a simple DocBook style guide
>that duplicates just enough of the DocBook manual to say "here's the basic
>structure, here are the tags we actually use, use the following inline
>markup tags for the following things, and don't use anything else not
>mentioned in this guide."  Even a starting point would be great.

i could do this next weekend if no one objects.  given that i did the
conversion i suppose it would make the most sense (and i should ahve
done this at the time).  probably the most broken part is the syntax
highlighting.  it needs to be consistent and i didnt get everything
consistent.  for instance using variable instead of emphasis.  these
generally both render the same, but they might not.  some things are
probably not using the most efficient table either.

>Then, once we have that, we need to take a comprehensive pass through the
>existing manuals and bring them in line with that style guide.  The result
>will be something that we can actually update and maintain without being
>lost in the necessary tag conventions.

easier said that done of course.