On Thursday 11 January 2001 12:55, psr scratched this in the dirt:
> * Docs are submitted in some form of simple markup language (Docbook seems
> like a good idea to me, as, if I understand correctly, it places lots of
> emphasis on the structure, and very little on the layout, which makes it
> easy for other people to customise the look and feel for thier own use in
> any format, be it web based or otherwise) - Again, since this is an XML
> application (am I right here?) we appear to be on the cutting edge.
You are correct; DocBook has both SGML and HTML variants. As a matter of
fact, if you design your DocBook SGML document correctly (principally, adhere
to all lowercase tagging), you can simply substitute a new DTD declaration to
make it XML, and vice-versa.
It''s a very flexible system, and superb documentation can be created with
the use of only a half-dozen different tags. If you want to get fancier with
ensuring you declare what type of text any given chunk is, you can use all
200+ tags.
The learning curve for DocBook XML, for anybody with HTML tagging
experience, is very very shallow. If you've never tagged anything before,
it's still fairly trivial. The steep part of the learning curve is getting
your SGML/XML editing environment set up -- and nobody's provided a popular,
easy tool for that yet : (
Emphasis on structure is my principal focus in this group -- that we know
that a chapter heading is a chapter heading, and not simply an H2 tag, that
table of contents can be arranged automatically and easily with low
maintenance, and that the documents be easily exportable to various formats
beyond HTML (ergo: printed bound, plain text, RTF, etc.) The only thing I've
seen that allows this kind of flexibility and low-end entry point is DocBook
XML/SGML.
As has been mentioned in previous threads, however, there are some barriers
to entry there, and a massive history of documents yet to be converted. I've
volunteered for the conversion duty, and have seen at least one other poster
who has as well (as soon as I finish my Bugzilla Guide, that is!)
> * These docs are converted into XHTML by a script, with a standard Style
> Sheet. [snip]
> DocBook ... files are tarballed and squirreled away in a download section
> somewhere, along with postscript, pdf, text etc. etc. versions.
Exactly the point of my first posting to the group. I plan on eventually
submitting The Bugzilla Guide for print and sale -- I can publish it cheaply
enough, and already know several people interested in buying a copy. Not
that I'd make any money on it, really, that is not my intention. The
widespread use and ubiquity of Bugzilla is my principle goal, and making
documentation available in printed form helps that goal along.
> I'm not trying to stir up arguments here, I really do just want to know
> what is wrong with any of the above. Since I am working on something
> slightly simillar for my own website, I really do have an interest in the
> problems in using XHTML.
Well, I believe I can sum up the argument fairly well (correct me if I'm
wrong)
1. "Anti-DocBook": How can people easily use a validating XML editor to
submit their documents? There aren't many, and those available are
considered hard-to-use or proprietary/commercial.
"Pro-DocBook": volunteers (such as myself) agree to tag submitted content
to DocBook XML, and ask submitters to send it to us in whatever format is
agreeable to them. Perhaps we could request the help of the Linux
Documentation Project folks in doing this, since they have a longer history
of doing so successfully.
2. "Anti-DocBook": Converting the existing (some say 10,000 pages) HTML
documentation to XHTML or HTML4.01 is trivial. Converting to DocBook is not.
"Pro-DocBook": You're right on that one. However, we could eventually get
through it.
3. "Anti-DocBook": Archiving documentation in DocBook and then running
background jobs against stylesheets to compile them to HTML and publish them
seems redundant when everyone is used to submitting documents in HTML anyway.
"Pro-DocBook": DocBook allows you to trivially compile to alternate
formats, such as PDF, TXT, RTF, etc. The point is not the web site -- printed
HTML is ugly. The point is to have documentation on the website and
available in other formats as well.
There are several great arguments in favor of DocBook as well... I'm out of
time to summarize then here.
It would be really great to see somebody compile all the plusses and minusses
of each system:
XHTML vs HTML4.01 vs DocBook XML/SGML vs Custom XML
and
File System +web server (ergo Apache) vs Database (ergo: Zope) for back-end
(unrelated to the formats question -- you can store and process all the above
formats on either type. I think some people have confused the issue.
Document format has nothing to do with filesystem or database layout.)
If I got anything wrong, correct me!
--
Matthew P. Barnson
Manager, Systems Administration
Excite@Home
