1DOCBOOK2MAN-SPEC.PL(1)                                  DOCBOOK2MAN-SPEC.PL(1)
2
3
4

NAME

6       docbook2man-spec.pl - convert DocBook RefEntries to man pages
7

SYNOPSIS

9       sgmlspl docbook2man-spec.pl
10
11
12       nsgmls [ sgml document ]| sgmlspl docbook2man-spec.pl
13
14

DESCRIPTION

16       docbook2man  is  a sgmlspl spec file that produced man pages (using the
17       -man macros) from DocBook RefEntry markup.
18
19       The program reads ESIS produced by nsgmls (or other SGML parsers)  from
20       standard input.  Markup not found in RefEntry is discarded.
21
22       Its  output, the converted man pages, are written to the current direc‐
23       tory.  If RefMeta information is not specified in a RefEntry, then  the
24       man page will be written to standard output.
25
26       The file manpage.links will also be created, which contains any aliases
27       of the manpages generated.  This file is in the format:
28
29       <man page> <alias
30       manpage>
31
32       The manpage.refs file keeps track of XRef references.  Note that if the
33       input document has any forward references, then docbook2man may have to
34       be invoked twice (the first  time  updating  manpage.refs)  to  resolve
35       them.
36

REQUIREMENTS

38       The  SGMLSpm  package  from  CPAN.   This  package includes the sgmlspl
39       script that is also needed.
40

LIMITATIONS

42       Trying docbook2man on non-DocBook or  non-conformant  SGML  results  in
43       undefined behavior. :-)
44
45       This program is a slow, dodgy Perl script.
46
47       This  program does not come close to supporting all the possible markup
48       in DocBook, and may produce wrong output in some cases  with  supported
49       markup.
50

TO DO

52       Obvious stuff:
53
54       · Fix  docbook2man  breakages  found  in the test documents, especially
55         weird.sgml.
56
57       · Add new element handling and fix existing handling.  Be robust.
58
59       · Produce cleanest, readable man output as possible (unlike some  other
60         converters).   Follow  Linux man(7) convention.  As conversion to man
61         pages is usually not done very often, it is better to be  slower/more
62         complicated  than  to produce wrong output.  Also if someone wants to
63         give up using DocBook for whatever  reason,  the  last-converted  man
64         pages can then be maintained manually.
65
66       · Make  it  faster.  I  think most of the speed problems so far is with
67         parsing ESIS.  Rewrite SGMLS.pm with C and/or get input directly from
68         SP.
69
70       · Support  other  (human)  languages.   But  what  to do with non-ASCII
71         charsets?  SGMLSpm doesn't report them and roff does not  grok  them.
72         [Comment:  text  after enclosed lists (and SS blocks) will break doc‐
73         book2man] If we do this, more people can use DocBook.
74

76       Copyright (C) 1998-1999 Steve Cheng <steve@ggi-project.org>
77
78       This program is free software; you can redistribute it and/or modify it
79       under  the  terms of the GNU General Public License as published by the
80       Free Software Foundation; either version 2, or  (at  your  option)  any
81       later version.
82
83       You should have received a copy of the GNU General Public License along
84       with this program; see the file COPYING.  If not, please write  to  the
85       Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
86
87
88
89                               11 February 2004         DOCBOOK2MAN-SPEC.PL(1)
Impressum