[ANNOUNCE] xorg-sgml-doctools-1.2

[Gene Heskett]

On Sunday 04 March 2007, David Nusinow wrote:
>Hi Jeremy,
>
>On Sat, Mar 03, 2007 at 04:05:46PM -0600, Jeremy C. Reed wrote:
>> David,
>>
>> Thanks for your work on the xorg docs.
>>
>> Can you explain a little about your changes there?
>
>Sure. The sgml docs that were in xorg-docs-1.3 were formatted using
>linuxdoc, which had been abandoned for docbook in the late 90's. In
>response to ajax's request for help with the 7.2 release notes I tried
> to build the package, but couldn't with any version of the tools in
> Debian for the past ~4 years. So I converted them to docbook sgml to
> allow them to build. I used the docbook2x series of tools to actually
> do the building.
>
>Eamon did a ton of great work reorganizing the docs more coherently and
>improving the build system as well, so the infrastructure is really
> sound now.
>
>> What tools are needed to contribute or use the docs?
>
>You'll need the docbook2x series of tools, located at
>http://docbook2x.sourceforge.net/
>and docbook itself. Other than that, a text editor should be enough.
>There isn't a great sgml or xml editing tool that's free software right
>now, although I hear great things about emacs' modes for them.
>
>> What needs to be done?
>
>A big issue is bug #647. I haven't taken a serious look at how to fix
> this yet, but I want it fixed for the 7.3 katamari. Another thing is
> that the general consensus was to convert the sgml to xml. There was a
> script written to do this, but no one has actually transitioned the
> docs over to xml yet. I may also roll the xorg-sgmldoctools package in
> to xorg-docs, or at least add a .pc file for sgmldoctools.
>
>The most important thing of all though is to write more and better docs,
>and to improve the ones we've already got. The infrastructure is in
> place to do it, we just need people to write. One interesting idea is
> to bundle some useful docs that are on the wiki in to xorg-docs, so
> they can be used without a web browser.
>
>> And is there a wiki page so people can keep track or contribute?
>
>Not yet, and I'm not really sure what would be on such a page. If you
> want to make one though, let me know and I'll be happy to add what I
> can.
>
> - David Nusinow

And I'll submit again, that the 'docbook' format was a solution looking 
for a problem, but the docbook promoters have never realized that it IS 
the problem.  I have all those tools, or did have before I freshly 
installed FC6 about 4 months ago, configured according to the directions 
I was able to wheedle from the mailing lists, and frankly no one seemed 
to know much more than I did about this 'docbook' format of file, or how 
to actually read it.  I have never been able to type the docbook equ of 
a 'man someprogram' and get a readable screen out of it, even when trying 
to give it every argument that made any sense at all on the cli.

I will stop denegrating this docbook flood of nonsense BS when I can 
type 'docbook procmailrc' and read it, till then please give us simple, 
easily read manpages.  Stop hiding the docs for this stuff behind an 
impenetrable curtain of gobbledygook, far worse that trying to read an 
html email as plaintext.

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