[ANNOUNCE] xorg-sgml-doctools-1.2

Gene Heskett gene.heskett at verizon.net
Sun Mar 4 15:05:50 PST 2007


On Sunday 04 March 2007, David Nusinow wrote:
>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.

Correct.  The only package I routinely build from scratch and install, 
usually at intervals of less than a week, is amanda.  Its make output 
doesn't reach out and tell you that to make its manpages, the info comes 
from a subdir of xml stuffs by the same name using docbook tools to do 
it, but it obviously does exactly that once the build tree is examined.  
So you are correct, amanda's manpages were apparently generated by 
docbook2man.

>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.

Not having seen the docs, and been aware that they were the output of 
docbook at the same time, I am certainly not in a position to criticize 
them.

> - David Nusinow
>
>[0] http://www.docbook.org/

I'll get this O'Reilly book the next time I'm in town, the bookstore is 
about 30 miles away.  In a mall whose parking lot has 3x the normal 
amount of fender benders per acre than most places that resemble it.

>[1] http://gitweb.freedesktop.org/?p=xorg/doc/xorg-docs.git;a=summary
Bookmarked, thanks.

>[2] http://fuckinggoogleit.com/
:-) I probably have that coming.  Thanks for your patience David and 
friends, I might have a foot in the door now.

-- 
Cheers, Gene
"There are four boxes to be used in defense of liberty:
 soap, ballot, jury, and ammo. Please use in that order."
-Ed Howdershelt (Author)
Yahoo.com and AOL/TW attorneys please note, additions to the above
message by Gene Heskett are:
Copyright 2007 by Maurice Eugene Heskett, all rights reserved.



More information about the xorg mailing list