Subject: Re: Current Projects?
To: None <>
From: Klaus Heinz <>
List: netbsd-docs
Date: 03/18/2002 14:06:05
Hi Brian A. Seklecki, you wrote:

> I was hoping someone might be tossing around the idea of converting
> everything from pure HTML/Mk files > SGML/DocBook or even better,
> XML/DocBook.  As cheesy as that sounds, there's some exciting stuff going

I am indeed thinking along the lines of XML/DocBook, but have not
talked about it, yet (ok, except one time on IRC).

=46rom what I have read so far, I am inclined to use the Apache tools
(Xerces/Xalan). They are available in C/C++ versions in pkgsrc which
should allow people to use them on every port, in contrast to their
Java counterparts or other programs based on Java.

The packages available in pkgsrc are a bit outdated, but I and at least
one other person work on updating them to the current versions.

> There are a lot of advantages to using DocBook, too many to mention now,
> but by far the biggest among the list are: portable output formats
> (flat text, HTML, pdf, rtf, etc.), and use of stylesheets / schemas to
> handle costmetic formatting, allowing the project to focus more on
> document content.

My reason for investigating this falls into the 'cosmetic formatting'
category. Keeping translated pages of the web site in sync with the
changes _not_ related to content should be simpler than repeating
the change for every language.

The disadvantage would be for content contributors to have to learn
the new markup language, instead of the well known HTML. As this
affects almost every developer, I cannot say whether such a large
change to the process of creating web documents would be acceptable.

XML is often associated with 'dynamic' web sites, i.e. creating web
pages on the fly (SSI, PHP, JSP, whatnot...).
I propose _not_ to do this with Apart from other
reasons (security, software stability, performance requirements)
it could be difficult for the mirrors to provide such a configuration.

We should rather continue the practice of editing source files
and using 'make' to produce the final output, like we do with
the .list files now.

If you know your way around XML and/or DocBook (more than I can say
about me, at this time :-), you're certainly welcome to help.

I have not looked very closely at DocBook, yet. It seems to be a rather
complete solution for documentation needs. For the purpose of using
it for the web site, we would have to choose an appropriate subset.

The requirements for the stylesheets would be (at least) the ability
to reproduce the web site as it is now. I don't know what would be
simpler, adapting/overloading the available stylesheets for DocBook
XML or rolling our own, but I hope for the former.