[ANNOUNCE] xorg-sgml-doctools-1.2

[David Nusinow]

On Sun, Mar 04, 2007 at 05:15:41PM -0500, Gene Heskett wrote:
> On Sunday 04 March 2007, Daniel Stone wrote:
> >On Sun, Mar 04, 2007 at 04:15:13PM -0500, Gene Heskett wrote:
> >> On Sunday 04 March 2007, Daniel Stone wrote:
> >> >I can see you're not trying to be obnoxious, but are you honestly
> >> >arguing for manpages instead of DocBook as the raw format, on the
> >> >grounds of 'hard to remember syntax'?
> >>
> >> Yes Daniel.  Any format that takes 3 or more command line arguments,
> >> and at least 2 separate incantations of disparate utilities just to do
> >> the equ of a 'man name' is going to be extremely counterintuitive.
> >> Particularly for a newbie, and I've been running linux since rh5.1
> >> days.
> >
> >Okay, and you're missing the point.  DocBook is _not_ the final format.
> >It is used to generate HTML, PDF, roff, etc.  You write documentation in
> >DocBook, and users type man whatever.
> 
> That has never worked here.  Example:
> [root at coyote ~]# man docbook-utils
> No manual entry for docbook-utils

...

> So where IS the bridge that will teach the user how to use it?

The user just runs ./configure && make when docbook and docbook2x are
installed on the system. It's really easy. You *do* know what package we're
actually talking about, right? It seems that you're just casting about
randomly in search of docbook information[0] instead of actually trying to
do anything with it.

Even more to the point is that the user will just have this package
installed on their system like any other. They don't have to build it.
Debian users already have this right now.  They don't ever see any of the
original sgml source files, the same way they don't see any of the original
C sources for other parts of Xorg. They just get the html, text, pdfs, and
ps files.

> >So, I don't see any problem at all.
> 
> Obviously you are privy to the secret incantations to make it work.  I 
> would like to join that club but my attempts to carve a working key have 
> so far, been both very frustrating, and an utter failure.

We've cleverly hidden the secret incantaions in the build system for
xorg-docs[1] and in the docbook2x documentation[2]. 

I'm rapidly losing patience for this. If you want to rant about the
horrible work that we've done on the docs, at least try to do it from a
position that doesn't stem from complete ignorance.

 - David Nusinow

[0] http://www.docbook.org/
[1] http://gitweb.freedesktop.org/?p=xorg/doc/xorg-docs.git;a=summary
[2] http://fuckinggoogleit.com/