Re: debiandoc vs. docbook
(Thanks to whatever process or person refreshed the web posting of the
debian-doc archives.)
My sense is that there is agreement (in comments received so far) that we
should move toward docbook. The fact that BSD, LDP, and GNOME are all using
docbook is most compelling.
IMHO Docbook-XML (not docbook-SGML) is the only practical target, since
increasing the list of SGML->XML conversions that will be required would
exacerbate the challange rather than ease it.
That said, it is true that the tool-chain for rendering docbook-XML in some
other format (specifically, typeset output) is not what one would like.
jade + docbook dsssl stylesheets => dvi, postscript, or pdf
But jade is no longer being maintained, and development of openjade appears
to have slowed considerably, if not halted altogether.
I therefore do not believe that jade is a useful solution at this point.
passivetex + tei (not docbook) document + tei (not docbook) stylesheets
=> postscript.
I haven't seen the stylesheets that allow passivetex to work on docbook-based
documents, only those that work with tei-based documents.
fop + docbook XSLT stylesheets => pdf
But fop is only a partial implementation of XSL, which is (understatement)
strained by the docbook XSLT stylesheets. I have frequently experienced
crashes with fop, and have often had the experience that fop is out of date
with respect to docbook stylesheets. As a result of both, I don't depend on
fop; I'm just grateful when it works. The stylesheets written for the GNOME
user's guide might be a good alternative in this case.
Any XSLT processor + docbook XSLT stylesheets => HTML and
HTML + htmldoc => indexed HTML, postscript, or pdf
Haven't tried this yet.
The point is made that we need to demonstrate the feasibility of a robust
debiandoc to docbook converter before proceeding. I have downloaded
Phillipe Batailler's debiandoc2docbook script, but don't yet quite understand
what problem Osamu is alluding to with regard to internal entities:
the man page for sgml2xml doesn't seem to mention any limitation in this
area.
The need for a best practices guide with regard to docbook is the most
challenging part of a transition to docbook, IMHO. While debiandoc has the
disadvantage that it doesn't provide much freedom of expression, docbook
arguably provides too much -- so much so, that renderings into various
formats, and translations from docbook into the next document-technology-
du-jour may be greatly hindered if we don't agree on a uniform way to use
this very large language. The GNOME and BSD guides are good starting points;
I would be surprised if some best practices are not evolving in the LDP as
well, but I don't know of any document about this though. I would guess
that a debian-docbook-BPG would be a continually-evolving area, something
like debian-policy itself, and we'll at least need to do a few translations
before we can even begin to draft such a guide.
Though I'd agree we need a converter and a BPG, I don't know what the
rationale is for choosing, a priori, to use a subset of the docbook
elements. More details?
The requirements for new stylesheets and for automatic processing scripts
should (I think) wait until we have some positive experience with the
translator script and we have the beginnings of a BPG.
It looks like there's a lot of work ahead to make a transition to docbook,
but plenty of reason to do so. As we make progress defining what needs to
be done, we should probably identify specific teams for subtasks.
Concrete suggestions for anyone who's interested:
try to use debiandoc2docbook on your favorite manual; report successes,
problems, ambiguities.
work with Phillipe on the problem of entity expansion in the sgml2xml
translation
jumpstart the development of a BPG by merging the most relevant bits of
the BSD and GNOME guides
make other suggestions about next steps
let everyone know what you're doing
Again, please note key word: suggestions. Please do contradict the above
where you see fit.
Cheers,
Susan
Reply to: