[ANNOUNCE] xorg-sgml-doctools-1.2

[Russell Shaw]

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

Apart from googling for things like "docbook howto", "docbook tutorial",
and reading manuals on the docbook web site, the other place to find useful
info is in the tarball itself. It isn't necessary to download the docbook
sources to get these, because they're typically packaged separately or as
man pages.

The thing you really need to know is the packaging commands for your system,
which can be used to find *any* documentation. On Debian, if you know a
command, find where it is:

whereis docbook2man

   docbook2man: /usr/bin/docbook2man
                /usr/X11R6/bin/docbook2man
                /usr/bin/X11/docbook2man
                /usr/share/man/man1/docbook2man.1.gz


Find out what package name it came from:

dpkg -S docbook2man

   docbook-utils: /usr/share/doc/docbook-utils/html/docbook2man.html
   docbook-utils: /usr/share/man/man1/docbook2man.1.gz
   docbook-utils: /usr/share/man/man1/docbook2man-spec.pl.1.gz
   docbook-utils: /usr/bin/docbook2man
   docbook-utils: /usr/share/perl5/sgmlspl-specs/docbook2man-spec.pl


List the files within the package:

dpkg -L docbook-utils

   ..
   /usr/share/man
   /usr/share/man/man1
   /usr/share/man/man1/docbook2texi-spec.pl.1.gz
   /usr/share/man/man1/sgmldiff.1.gz
   /usr/share/man/man1/jw.1.gz
   /usr/share/man/man1/docbook2man-spec.pl.1.gz
   /usr/share/man/man7
   /usr/share/man/man7/backend-spec.7.gz
   /usr/share/man/man7/frontend-spec.7.gz
   /usr/share/doc
   /usr/share/doc/docbook-utils
   /usr/share/doc/docbook-utils/html
   /usr/share/doc/docbook-utils/html/api.html
   /usr/share/doc/docbook-utils/html/backend-spec.html
   /usr/share/doc/docbook-utils/html/docbook2man.html
   /usr/share/doc/docbook-utils/html/docbook2texi.html
   /usr/share/doc/docbook-utils/html/fdl.html
   /usr/share/doc/docbook-utils/html/frontend-spec.html
   /usr/share/doc/docbook-utils/html/helpers.html
   /usr/share/doc/docbook-utils/html/index.html
   /usr/share/doc/docbook-utils/html/introduction.html
   /usr/share/doc/docbook-utils/html/intro-jw.html
   /usr/share/doc/docbook-utils/html/intro-sgmldiff.html
   /usr/share/doc/docbook-utils/html/jw.html
   /usr/share/doc/docbook-utils/html/sgmldiff.html
   /usr/share/doc/docbook-utils/README
   /usr/share/doc/docbook-utils/TODO
   /usr/share/doc/docbook-utils/README.Debian
   /usr/share/doc/docbook-utils/TODO.Debian
   /usr/share/doc/docbook-utils/copyright
   /usr/share/doc/docbook-utils/changelog.gz
   /usr/share/doc/docbook-utils/changelog.Debian.gz
   ..
   /usr/bin
   /usr/bin/jw
   /usr/bin/sgmldiff
   /usr/bin/docbook2dvi
   /usr/bin/docbook2html
   /usr/bin/docbook2man
   /usr/bin/docbook2pdf
   /usr/bin/docbook2ps
   /usr/bin/docbook2rtf
   /usr/bin/docbook2tex
   /usr/bin/docbook2texi
   /usr/bin/docbook2txt
   /usr/bin/db2html
   /usr/share/man/man1/docbook2txt.1.gz
   /usr/share/man/man1/docbook2dvi.1.gz
   /usr/share/man/man1/docbook2html.1.gz
   /usr/share/man/man1/docbook2man.1.gz
   /usr/share/man/man1/docbook2pdf.1.gz
   /usr/share/man/man1/docbook2rtf.1.gz
   /usr/share/man/man1/db2pdf.1.gz
   /usr/share/man/man1/docbook2tex.1.gz
   /usr/share/man/man1/docbook2ps.1.gz
   /usr/share/man/man1/db2rtf.1.gz
   /usr/share/man/man1/db2ps.1.gz
   /usr/share/man/man1/db2html.1.gz
   /usr/share/man/man1/db2dvi.1.gz
   /usr/share/man/man1/docbook2texi.1.gz
   /usr/bin/db2pdf
   /usr/bin/db2rtf
   /usr/bin/db2ps
   /usr/bin/db2dvi


As you can see, docbook is an intermediate format that can generate dvi, html, man, pdf, ps, rtf, 
tex, texi, and txt(ascii) output, and much documentation is shown in the above list of files.

-- 
Russell Shaw, B.Eng, M.Eng(Research)