Man Linux: Main Page and Category List

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.

                                 05 June 2008