"James K. Lowden" <jklowden@schemamania.org> wrote:
> Mike M. Volokhov wrote:
> > But before all, I'd like to know your opinions on this topic. It
> > would be really silly to sent the wide proposal without getting
> > buy-in from you, NetBSD documentoraptors, first.
> 
> I have not contributed one page of NetBSD documentation, but I've
> maintained the FreeTDS User Guide in SGML DocBook with Jade for years.  I
> consider it a solved problem.  I don't prepare printed output, but I've
> always thought that was pretty much a matter of installing and setting up
> jade-tex.  
> 
> Is SGML too old-fashioned, or Jade too heavyweight, or both?  

Let's look deeper into problem. We're providing documentation and
other information to all interested parties, including developers
and end users. This can (and is) done in the following forms:

	- web-site
	- documents for offline browsing
	- documents for printing (including books)
	- other forms (not addressed here): verbal, prezos, ads...

Can you use Jade as solution for the first three? Yes, but it has
not been adopted for this yet. Moreover, it will possible never
be. Just like many other existent tools and even frameworks.

In order to accept this you should think about web-site as not
about pile of files available via HTTP, and about printable books
as not about pile of pages which you can send to printer. Or, "if
you made a bullet from shit, it will be the shit." (I'm talking
about result, not the tools here.)

> I'm interested in participating.  IMHO if the BSDs decided to use one
> documentation toolchain, we could develop the expertise we need to
> exploit, say, stylesheets and to maintain any more-or-less abandoned
> tools.  

Yes, common framework will give us many additional advantages.
Just remember how CARP chapter was moved into NetBSD Guide from
FreeBSD Handbook; I wonder was it so easy if FreeBSD had used,
say, LaTeX for their documentation. Also, NetBSD AFAIK a single
project who can move almost every web page from site into Guide
and vice versa with minimal effort. Besides compatibility, we can
gain more manpower and wider knowledgebase (see my original
letter); this is a very important part from maintenancing POV.

So, if you are interested, please stay online :-)

--
Mishka.