doc/refentry/docbook2man-spec.pl.sgml

   1 <RefEntry id="docbook2man">
   2
   3 <RefMeta>
   4 <RefEntryTitle>docbook2man-spec.pl</RefEntryTitle>
   5 <ManVolNum>1</ManVolNum>
   6 </RefMeta>
   7
   8 <RefNameDiv>
   9 <RefName>docbook2man-spec.pl</RefName>
  10 <RefPurpose>convert DocBook RefEntries to man pages</RefPurpose>
  11 </RefNameDiv>
  12
  13 <RefSynopsisDiv>
  14 <CmdSynopsis>
  15 <Command>sgmlspl</command>
  16 <Arg choice=req>docbook2man-spec.pl</arg>
  17 </CmdSynopsis>
  18
  19 <!-- docbook2man-spec.pl BREAKAGE HERE! -->
  20
  21 <CmdSynopsis>
  22 <Command>nsgmls</command>
  23 <Arg><Replaceable>sgml document</replaceable></Arg>
  24 <Command>| sgmlspl</command>
  25 <Arg choice=req>docbook2man-spec.pl</arg>
  26 </CmdSynopsis>
  27 </RefSynopsisDiv>
  28
  29 <RefSect1>
  30 <Title>Description</Title>
  31
  32 <Para>
  33 <Application>docbook2man</application> is a sgmlspl spec file that produced man
  34 pages (using the -man macros) from DocBook RefEntry markup.
  35 </Para>
  36
  37 <Para>
  38 The program reads ESIS produced by nsgmls (or other SGML parsers) from
  39 standard input.  Markup not found in RefEntry is discarded.
  40 </Para>
  41
  42 <Para>
  43 Its output, the converted man pages, are written to the current directory.  If
  44 <SGMLTag>RefMeta</sgmltag> information is not specified in a
  45 <SGMLTag>RefEntry</sgmltag>, then the man page will be written to standard
  46 output.
  47 </Para>
  48
  49 <Para>
  50 The file <Filename>manpage.links</filename> will also be created, which contains
  51 any aliases of the manpages generated.  This file is in the format:
  52
  53 <Synopsis>
  54 <Token><Replaceable>man page</replaceable></Token> <Token><Replaceable>alias
  55 manpage</replaceable></Token>
  56 </Synopsis>
  57 </Para>
  58
  59 <Para>
  60 The <Filename>manpage.refs</filename> file keeps track of
  61 <SGMLTag>XRef</sgmltag> references.  Note that if the input document has any
  62 forward references, then <Application>docbook2man</application> may have to be
  63 invoked twice (the first time updating <Filename>manpage.refs</filename>) to
  64 resolve them.
  65 </Para>
  66
  67 </RefSect1>
  68
  69 <RefSect1>
  70 <Title>Requirements</Title>
  71
  72 <SimpleList>
  73 <Member>
  74 The SGMLSpm package from CPAN.  This package includes the sgmlspl script
  75 that is also needed.
  76 </Member>
  77 </SimpleList>
  78
  79 </RefSect1>
  80
  81
  82 <RefSect1>
  83 <Title>Limitations</Title>
  84
  85 <Para>
  86 Trying <Application>docbook2man</application> on non-DocBook or non-conformant
  87 SGML results in undefined behavior. :-)
  88 </Para>
  89
  90 <Para>
  91 This program is a slow, dodgy Perl script.
  92 </Para>
  93
  94 <Para>
  95 This program does not come close to supporting all the possible markup
  96 in DocBook, and may produce wrong output in some cases with supported
  97 markup.
  98 </Para>
  99
 100 </RefSect1>
 101
 102 <RefSect1>
 103 <Title>To do</Title>
 104
 105 <Para>
 106 Obvious stuff:
 107
 108 <ItemizedList>
 109
 110 <ListItem><Para> Fix <Application>docbook2man</application> breakages found in
 111 the test documents, especially
 112 <Filename>weird.sgml</filename>.</Para></ListItem>
 113
 114 <ListItem><Para>
 115 Add new element handling and fix existing handling.
 116 Be robust.
 117 </Para></ListItem>
 118
 119 <ListItem><Para> Produce cleanest, readable man output as possible (unlike some
 120 other converters).  Follow Linux
 121 <CiteRefEntry><RefEntryTitle>man</refentrytitle><ManVolNum>7</manvolnum></CiteRefEntry>
 122 convention.  As conversion to man pages is usually not done very often, it is
 123 better to be slower/more complicated than to produce wrong output.  Also if
 124 someone wants to give up using DocBook for whatever reason, the last-converted
 125 man pages can then be maintained manually.  </Para></ListItem>
 126
 127 <ListItem>
 128 <Para>Make it faster. I think most of the speed problems so far is with parsing
 129 ESIS.  Rewrite <Filename>SGMLS.pm</filename> with C and/or get input directly
 130 from <Application>SP</application>.
 131 </Para>
 132 </ListItem>
 133
 134 <ListItem>
 135 <Para>Support other (human) languages.  But what to do with non-ASCII charsets?
 136 SGMLSpm doesn't report them and <Application>roff</application> does not grok them.
 137 </Para></ListItem>
 138
 139 </ItemizedList>
 140
 141 <Comment>text after enclosed lists (and SS blocks) will break docbook2man</Comment>
 142 If we do this, more people can use DocBook.
 143 </Para>
 144
 145 </RefSect1>
 146
 147 <RefSect1>
 148 <Title>Copyright</Title>
 149
 150 <Para>
 151 Copyright (C) 1998-1999 Steve Cheng <Email>steve@ggi-project.org</email>
 152 </Para>
 153
 154 <Para>
 155 This program is free software; you can redistribute it and/or modify it
 156 under the terms of the GNU General Public License as published by the
 157 Free Software Foundation; either version 2, or (at your option) any
 158 later version.
 159 </Para>
 160
 161 <Para>
 162 You should have received a copy of the GNU General Public License along with
 163 this program; see the file <Filename>COPYING</filename>.  If not, please write
 164 to the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 165 </Para>
 166
 167 </RefSect1>
 168 </RefEntry>
 169