[ANNOUNCE] xorg-sgml-doctools-1.2

[Russell Shaw]

Gene Heskett wrote:
> 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.

DO NOT buy the O'Reilly Docbook book. It is the worst piece of crap to
come from O'Reilly. Most of their other books aren't this bad.

http://www.faqs.org/docs/artu/ch18s05.html

http://www.faqs.org/docs/artu/documentationchapter.html
http://www.faqs.org/docs/artu/index.html