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  RefEn­
       try is discarded.

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

       The file manpage.links will also be  created,  which  con­
       tains 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 refer­
       ences, 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,


       · 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  compli­
         cated  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 manu­
         ally.

       · 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-pro­
       ject.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.


Man(1) output converted with man2html