[OpenAFS-Doc] docbook conversion update

[chas williams - CONTRACTOR]

a prelimiary docbook conversion of the userguide and adminguide are now
available. the figures and tables were manually converted so they dont
look right yet. i modified the gnome docbook stylesheet a bit. the pdf
now has bold face where it should and the html might be more palatable.

ftp://ftp.cmf.nrl.navy.mil/pub/chas/openafs/AdminGuide.tar.gz
ftp://ftp.cmf.nrl.navy.mil/pub/chas/openafs/UserGuide.tar.gz

after starting conversion of AdminRef i realized its essentially all the
man pages in a single volume. at one point someone said the man pages
might be converted to pod, so i dont see a need to convert this document.
an alternative to pod though might be to convert the existing html to
docbook's refentry format and generate the adminref and man pages from
a single source.

[Russ Allbery]

Post by chas williams - CONTRACTOR
after starting conversion of AdminRef i realized its essentially all the
man pages in a single volume. at one point someone said the man pages
might be converted to pod, so i dont see a need to convert this document.
an alternative to pod though might be to convert the existing html to
docbook's refentry format and generate the adminref and man pages from
a single source.

I would strongly prefer to use the already-developed tools and work to
convert the AdminRef to POD and maintain the man pages in POD. I find POD
about an order of magnitude easier to edit and maintain than DocBook
refentry. Note that this work is mostly done and I'm just waiting for 1.4
final and some final consensus to commit it to mainline and start working
on it in earnest.

[Esther Filderman]

Post by Russ Allbery
I'm just waiting for 1.4
final and some final consensus to commit it to mainline and start working
on it in earnest.

AkA moose get off your butt and dig into this stuff harder.

will do tomorrow.

p.s. don't you idjits ever sleep? :)

[chas williams - CONTRACTOR]

Post by Russ Allbery
I would strongly prefer to use the already-developed tools and work to
convert the AdminRef to POD and maintain the man pages in POD. I find POD

it doesnt bother me as long as you preserve enough information to convert
back to docbook meaningfully so a full hardcopy of all the man pages can
be printed. this means keeping the index information. pod does have
some support for this with via X<>. it cant handle the primary/secondary
index terms but judicious use of commas would probably be sufficient.

Post by Russ Allbery
about an order of magnitude easier to edit and maintain than DocBook
refentry. Note that this work is mostly done and I'm just waiting for 1.4

refentry looks complicated at first, but its not too awful. pod seems
more procedural, like *roff, instead of being a true markup language.
but for man pages, i dont think that really matters.

[Russ Allbery]

Post by chas williams - CONTRACTOR
it doesnt bother me as long as you preserve enough information to
convert back to docbook meaningfully so a full hardcopy of all the man
pages can be printed. this means keeping the index information. pod
does have some support for this with via X<>. it cant handle the
primary/secondary index terms but judicious use of commas would probably
be sufficient.

I'm personally not horribly interested in this. What matters to me is
having really solid man pages; I don't find that sort of index to be that
useful, or printing out large sheafs of man pages that useful. That being
said, you can certainly get good printed output via nroff, and it
shouldn't be too difficult to do a translation to DocBook.

For the sort of index entries that are actually useful, I doubt you want
to use X<>; indexing the page names will give you 90% of what's actually
of interest for the man pages.

Post by chas williams - CONTRACTOR
refentry looks complicated at first, but its not too awful.

No, refentry really is awful in my opinion; I've used it. XML is not a
good language for humans to work in.

Post by chas williams - CONTRACTOR
pod seems more procedural, like *roff, instead of being a true markup
language. but for man pages, i dont think that really matters.

It's *so* much easier to use.

[chas williams - CONTRACTOR]

Post by Russ Allbery
having really solid man pages; I don't find that sort of index to be that
useful, or printing out large sheafs of man pages that useful. That being

it might be useful for others who are not as wise in the ways of
afs. an index can be helpful in finding the right "word". besides,
i hate to loose information. someone indexed the man pages it would
be nice to keep that work.

Post by Russ Allbery
For the sort of index entries that are actually useful, I doubt you want
to use X<>; indexing the page names will give you 90% of what's actually
of interest for the man pages.

as long as you simply preserve the existing IDX tags i dont see a problem.
i can provide a mapping from IDXNNN to a string. even if you didnt in
your initial conversion, it probably wouldnt be too difficult to go back
through and reinsert them.

[Russ Allbery]

Post by Russ Allbery
having really solid man pages; I don't find that sort of index to be
that useful, or printing out large sheafs of man pages that useful.
That being

it might be useful for others who are not as wise in the ways of afs.
an index can be helpful in finding the right "word". besides, i hate to
loose information. someone indexed the man pages it would be nice to
keep that work.

Yeah, that's a good point. I'd hate to lose work.

Post by Russ Allbery
For the sort of index entries that are actually useful, I doubt you
want to use X<>; indexing the page names will give you 90% of what's
actually of interest for the man pages.

as long as you simply preserve the existing IDX tags i dont see a
problem. i can provide a mapping from IDXNNN to a string. even if you
didnt in your initial conversion, it probably wouldnt be too difficult
to go back through and reinsert them.

Yeah, that shouldn't be too bad.

[chas williams - CONTRACTOR]

this is an updated version of the converted AdminGuide available.

ftp:://ftp.cmf.nrl.navy.mil/pub/chas/openafs/AdminGuide.tar.gz

changes include:

. indexed
. "paper" links now have page numbers
. figures included
. tables are now "correct"

certain things probably need decided and implemented. for instance,
when to use <emphasis> or <replaceable>. for now, its <replaceable>
in program listings and <emphasis> elsewhere. filenames should probably
get wrapped with <filename> and not <emphasis role="bold">.