docbook2man-spec.pl

DOCBOOK2MAN-SPEC.PL(1)                                  DOCBOOK2MAN-SPEC.PL(1)



NAME
       docbook2man-spec.pl - convert DocBook RefEntries to man pages

SYNOPSIS
       sgmlspl docbook2man-spec.pl


       nsgmls [ sgml document ]| sgmlspl docbook2man-spec.pl


DESCRIPTION
       docbook2man is a sgmlspl spec file that produced man pages (using the
       -man macros) from DocBook RefEntry markup.

       The program reads ESIS produced by nsgmls (or other SGML parsers) from
       standard input.  Markup not found in RefEntry is discarded.

       Its output, the converted man pages, are written to the current
       directory.  If RefMeta information is not specified in a RefEntry, then
       the man page will be written to standard output.

       The file manpage.links will also be created, which contains any aliases
       of the manpages generated.  This file is in the format:

       <man page> <alias
       manpage>

       The manpage.refs file keeps track of XRef references.  Note that if the
       input document has any forward references, then docbook2man may have to
       be invoked twice (the first time updating manpage.refs) to resolve
       them.

REQUIREMENTS
       The SGMLSpm package from CPAN.  This package includes the sgmlspl
       script that is also needed.

LIMITATIONS
       Trying docbook2man on non-DocBook or non-conformant SGML results in
       undefined behavior. :-)

       This program is a slow, dodgy Perl script.

       This program does not come close to supporting all the possible markup
       in DocBook, and may produce wrong output in some cases with supported
       markup.

TO DO
       Obvious stuff:

       · Fix docbook2man breakages found in the test documents, especially
         weird.sgml.

       · Add new element handling and fix existing handling.  Be robust.

       · Produce cleanest, readable man output as possible (unlike some other
         converters).  Follow Linux man(7) convention.  As conversion to man
         pages is usually not done very often, it is better to be slower/more
         complicated than to produce wrong output.  Also if someone wants to
         give up using DocBook for whatever reason, the last-converted man
         pages can then be maintained manually.

       · Make it faster. I think most of the speed problems so far is with
         parsing ESIS.  Rewrite SGMLS.pm with C and/or get input directly from
         SP.

       · Support other (human) languages.  But what to do with non-ASCII
         charsets?  SGMLSpm doesn't report them and roff does not grok them.
         [Comment: text after enclosed lists (and SS blocks) will break
         docbook2man] If we do this, more people can use DocBook.

COPYRIGHT
       Copyright (C) 1998-1999 Steve Cheng <steve@ggi-project.org>

       This program is free software; you can redistribute it and/or modify it
       under the terms of the GNU General Public License as published by the
       Free Software Foundation; either version 2, or (at your option) any
       later version.

       You should have received a copy of the GNU General Public License along
       with this program; see the file COPYING.  If not, please write to the
       Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.



                               11 February 2004         DOCBOOK2MAN-SPEC.PL(1)