[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

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

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


Reply to: