Re: debiandoc vs. docbook
At (time_t)1032566308 Martin Wheeler wrote:
> On Fri, 20 Sep 2002, John R. Daily wrote:
> > I disagree strongly.
> <sigh> I _did_ say this is the stuff of flame-wars.
Yeah, after sending the note I regretted diverting from the real
topic, but I do feel that if the break is going to be made,
better to make the full leap than to make allowances for what is
only moderately easier and will cause yet another migration down
the road and will lessen the positive impact of this change.
> > * XML has not replaced SGML.
> > For environments without legacy SGML, it has.
> And for environments _with_ legacy SGML, you've got a phenomenal amount of
> inertia to overcome.
> (I'm talking practicality here, not theory. I remember in 1992 a major
> publisher I was sending text to refusing to accept it on magnetic disk. >o|
> Norm's soapbox speech is entirely correct -- but try selling that attitude to
> the editorial team of an SGML-only publishing house.
> My point is, that documentation writers are not necessarily geared to the
> debian development environment. Some will be just writers; used to their
> revenue-earning environment, and not wanting, or knowing how, to go any
> further. (For several years myself I did no more than just mark up text; I
> never bothered to process it in any way.) To assume that documentation is
> being written by (or, more accurately, post-edited by) programmers only, is
> just plain wrong. Some of us are professional writers, and don't actually
> want to change our authoring setup all that much. (Some may not even be able
> I think what we need here actually is accurate information about the technica
> setup used by, and degree of technical knowledge of, the average debian
> documenter. (I would expect to find a huge range.)
I don't disagree with any of the above, but what is the practical
difference to an author? Using </p> to finish a paragraph? Even
a March thread which proposed creating version 2 of DebianDoc
suggested normalizing it by (gasp) requiring </p>.
Seriously, this is a major conceptual gap to me. What is the
fundamental distinction between SGML and XML that makes the
latter more challenging?
> > If we're replacing
> > DebianDoc, then Debian will not have legacy SGML; adding more
> > legacy SGML to the equation doesn't make sense.
> Aarrggl. Sorry; you've _completely_ lost me here.
> What part of debiandoc.dtd isn't SGML?
My point is that if we use an automatic conversion tool
(normalize the SGML, XSLT to transform), then converting
everything to DocBook/XML is no more difficult than converting to
DocBook/SGML. At that point, we would be SGML-free, and
introducing more SGML documentation would be counter-productive.
> > * "full-blown XML database-driven environment"
> > Can you elaborate on this? Just because XML works well in a
> > database-driven environment doesn't mean that to author
> > documentation in XML requires anything related to databases.
> Never said it did. But consider the environment where you're writing in
> several different languages, or for minimally different implementations of th
> same basic product for your day-to-day work. Just because marking up
> documentation in XML actually requires no more than emacs + psgml + a
> locatable DTD doesn't mean that some writers aren't working in a totally
> different setup, with totally different block text manipulation methods.
> And *that* is what is perceived by them as an 'XML' environemt.
This still comes back to my own ignorance of SGML: what is the
difference between well-structured SGML and XML? Why can't the
existing tools in use by SGML authors generate XML? What is this
vast chasm that seems to lie in wait?