[OpenAFS-Doc] docbook conversion of QuickStartUnix

[chas williams - CONTRACTOR]

since there has seen some interest in a docbook conversion, i took a
stab at converting some of the existing .htm documentation.

here is a first pass at QuickStartUnix. its looks pretty good and is
fully indexed. generating the .pdf with the full index is very slow so
you should only do that after making your changes and are producing a
"final" document. if someone has a better toolchain for docbook to
pdf (with index support) i would like to hear about it.

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

critiques on the conversion are welcome. the content is a bit
dated and otherwise goofy (guaranties).

[Russ Allbery]

Post by chas williams - CONTRACTOR
since there has seen some interest in a docbook conversion, i took a
stab at converting some of the existing .htm documentation.
here is a first pass at QuickStartUnix. its looks pretty good and is
fully indexed. generating the .pdf with the full index is very slow so
you should only do that after making your changes and are producing a
"final" document. if someone has a better toolchain for docbook to
pdf (with index support) i would like to hear about it.
ftp://ftp.cmf.nrl.navy.mil/pub/chas/openafs/QuickStartUnix.tar.gz
critiques on the conversion are welcome. the content is a bit
dated and otherwise goofy (guaranties).

I like. There are a few minor problems (I noticed a stray empty bullet,
for instance), but it looks like a generally high-quality conversion and
gets things into a format that would be much easier to work with.

The generated HTML, though, is hideous. I assume that's just a matter of
finding better DocBook to HTML tools?

[chas williams - CONTRACTOR]

Post by Russ Allbery
I like. There are a few minor problems (I noticed a stray empty bullet,
for instance), but it looks like a generally high-quality conversion and
gets things into a format that would be much easier to work with.

the convertor isnt perfect since some of the things you can do in
html arent 'structured'. figures/tables have to be converted
manually and some of the list conversions are just plain wrong (which
is probably what you see).

Post by Russ Allbery
The generated HTML, though, is hideous. I assume that's just a matter of
finding better DocBook to HTML tools?

i would guess its more a style sheet issue. what is your specific
complaint? xmlto might be more to your liking. i couldnt figure
out how to get its pdf output to generate indexes.

try 'xmlto html auqbg000.xml' and open index.html

[Russ Allbery]

Post by chas williams - CONTRACTOR

Post by Russ Allbery
The generated HTML, though, is hideous. I assume that's just a matter
of finding better DocBook to HTML tools?

i would guess its more a style sheet issue. what is your specific
complaint?

Mostly all the newlines in the middle of tags, which is okay in SGML but
which will confuse some browsers.

Post by chas williams - CONTRACTOR
xmlto might be more to your liking. i couldnt figure out how to get its
pdf output to generate indexes.
try 'xmlto html auqbg000.xml' and open index.html

I'll poke at that. Thanks!

[renato arruda]

How did you convert from html to docbook? Did you write your own
parser or used a generic parser for the conversion? Is there any
chance I could look at it to see if i can be of any help?

-Renato

Post by chas williams - CONTRACTOR
since there has seen some interest in a docbook conversion, i took a
stab at converting some of the existing .htm documentation.
here is a first pass at QuickStartUnix. its looks pretty good and is
fully indexed. generating the .pdf with the full index is very slow so
you should only do that after making your changes and are producing a
"final" document. if someone has a better toolchain for docbook to
pdf (with index support) i would like to hear about it.
ftp://ftp.cmf.nrl.navy.mil/pub/chas/openafs/QuickStartUnix.tar.gz
critiques on the conversion are welcome. the content is a bit
dated and otherwise goofy (guaranties).
_______________________________________________
OpenAFS-doc mailing list
https://lists.openafs.org/mailman/listinfo/openafs-doc

[chas williams - CONTRACTOR]

Post by renato arruda
How did you convert from html to docbook? Did you write your own
parser or used a generic parser for the conversion? Is there any
chance I could look at it to see if i can be of any help?

i used this patch to an older version of tidy to do the bulk of
the conversion:

http://sourceforge.net/mailarchive/forum.php?forum_id=1650&style=flat&viewday=1&viewmonth=200207

i had to make a few modifications (modify hN handling, multiple text
nodes, and some list changes) and they arent very pretty. you dont get
to see my brain damaged coding). some assorted perl scripts removed
the headers and footers, extracted and reinserted the index terms.

things that dont have a clear representation in html, like figures and
tables need to be converted manually.

i pretty happy with the existing conversion. only the windows quickstart
document need converted although its more likely its entire content will
need replaced. I suppose i could convert the 3.6 releasenotes as well but
they should be written from scratch for the 1.4 release.

[ted creedon]

The aforementined htmltolatex perl script on my ftp server does all that,
tables, figures, etc.

All you have to do is emit docbook instead of tex. Html2latex parses the
tided up html and stores it in an internal tree structure.

tedc

-----Original Message-----
From: openafs-doc-***@openafs.org [mailto:openafs-doc-***@openafs.org]
On Behalf Of chas williams - CONTRACTOR
Sent: Tuesday, August 30, 2005 7:21 AM
To: renato arruda
Cc: openafs-***@openafs.org
Subject: Re: [OpenAFS-Doc] docbook conversion of QuickStartUnix

How did you convert from html to docbook? Did you write your own parser
or used a generic parser for the conversion? Is there any chance I
could look at it to see if i can be of any help?

i used this patch to an older version of tidy to do the bulk of the
conversion:

http://sourceforge.net/mailarchive/forum.php?forum_id=1650&style=flat&viewda
y=1&viewmonth=200207

i had to make a few modifications (modify hN handling, multiple text nodes,
and some list changes) and they arent very pretty. you dont get to see my
brain damaged coding). some assorted perl scripts removed the headers and
footers, extracted and reinserted the index terms.

things that dont have a clear representation in html, like figures and
tables need to be converted manually.

i pretty happy with the existing conversion. only the windows quickstart
document need converted although its more likely its entire content will
need replaced. I suppose i could convert the 3.6 releasenotes as well but
they should be written from scratch for the 1.4 release.

[Esther Filderman]

Post by ted creedon
The aforementined htmltolatex perl script on my ftp server does all that,
tables, figures, etc.
All you have to do is emit docbook instead of tex. Html2latex parses the
tided up html and stores it in an internal tree structure.

That's nice, except we're not storing things in Latex format, we're
storing things in DocBook format.

[chas williams - CONTRACTOR]

Post by ted creedon
The aforementined htmltolatex perl script on my ftp server does all that,
tables, figures, etc.

it was something like 3 tables. it didnt even require my two working
brain cells. the figures (gifs of a text display no less) seem
to be missing completely.

[ted creedon]

Its parsed and stored as XML internally, you don't need to emit as Latex you
can emit as docbook.

tedc
-----Original Message-----
From: openafs-doc-***@openafs.org [mailto:openafs-doc-***@openafs.org]
On Behalf Of Esther Filderman
Sent: Tuesday, August 30, 2005 8:35 AM
To: openafs-***@openafs.org
Subject: Re: [OpenAFS-Doc] docbook conversion of QuickStartUnix

Post by ted creedon
The aforementined htmltolatex perl script on my ftp server does all
that, tables, figures, etc.
All you have to do is emit docbook instead of tex. Html2latex parses
the tided up html and stores it in an internal tree structure.

That's nice, except we're not storing things in Latex format, we're storing
things in DocBook format.

[ted creedon]

Wait until you try the admin reference and guide. They're full of tables.

tedc

-----Original Message-----
From: openafs-doc-***@openafs.org [mailto:openafs-doc-***@openafs.org]
On Behalf Of chas williams - CONTRACTOR
Sent: Tuesday, August 30, 2005 8:45 AM
To: ted creedon
Cc: 'renato arruda'; openafs-***@openafs.org
Subject: Re: [OpenAFS-Doc] docbook conversion of QuickStartUnix

In message <***@smtpauth.easystreet.com>,"ted creedon"
wri

Post by ted creedon
The aforementined htmltolatex perl script on my ftp server does all
that, tables, figures, etc.

it was something like 3 tables. it didnt even require my two working brain
cells. the figures (gifs of a text display no less) seem to be missing
completely.

[chas williams - CONTRACTOR]

Post by ted creedon
Wait until you try the admin reference and guide. They're full of tables.

the admin reference is going to be pod apparently. a manual can
be generated from the pod.

i converted the adminguide already. four tables and nine figures.
not very difficult.

[ted creedon]

#grep /TD *.htm|wc -l
#1321

tedc

-----Original Message-----
From: chas williams - CONTRACTOR [mailto:***@cmf.nrl.navy.mil]
Sent: Tuesday, August 30, 2005 10:10 AM
To: ted creedon
Cc: 'renato arruda'; openafs-***@openafs.org
Subject: Re: [OpenAFS-Doc] docbook conversion of QuickStartUnix

In message <***@smtpauth.easystreet.com>,"ted creedon"
wr

Post by ted creedon
Wait until you try the admin reference and guide. They're full of tables.

the admin reference is going to be pod apparently. a manual can be
generated from the pod.

i converted the adminguide already. four tables and nine figures.
not very difficult.

[chas williams - CONTRACTOR]

Post by ted creedon
#grep /TD *.htm|wc -l
#1321

uhhh... yeah? TD = table data, not a table. there are four "formal"
tables and around 20 "informal" tables (docbook speak).

[chas williams - CONTRACTOR]

new versions of AdminGuide, QuickStartUnix and UserGuide now
available.

ftp://ftp.cmf.nrl.navy.mil/pub/chas/openafs

like AdminGuide, QuickStartUnix and UserGuide now have proper
paper links and most of the major problem eliminated (like
empty bullets).