<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>docbook2man-spec.pl</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="DocBook Utils"
HREF="index.html"><LINK
REL="UP"
TITLE="Helper programs"
HREF="helpers.html"><LINK
REL="PREVIOUS"
TITLE="Helper programs"
HREF="helpers.html"><LINK
REL="NEXT"
TITLE="docbook2texi-spec.pl"
HREF="docbook2texi.html"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>DocBook Utils</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="helpers.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="docbook2texi.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="DOCBOOK2MAN"
></A
>docbook2man-spec.pl</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN660"
></A
><H2
>Name</H2
>docbook2man-spec.pl -- convert DocBook RefEntries to man pages</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN663"
></A
><H2
>Synopsis</H2
><P
><B
CLASS="COMMAND"
>sgmlspl</B
> {docbook2man-spec.pl}</P
><P
><B
CLASS="COMMAND"
>nsgmls</B
> [<TT
CLASS="REPLACEABLE"
><I
>sgml document</I
></TT
>]<BR><B
CLASS="COMMAND"
>| sgmlspl</B
> {docbook2man-spec.pl}</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN673"
></A
><H2
>Description</H2
><P
><SPAN
CLASS="APPLICATION"
>docbook2man</SPAN
> is a sgmlspl spec file that produced man
pages (using the -man macros) from DocBook RefEntry markup.</P
><P
>The program reads ESIS produced by nsgmls (or other SGML parsers) from
standard input. Markup not found in RefEntry is discarded.</P
><P
>Its output, the converted man pages, are written to the current directory. If
<CODE
CLASS="SGMLTAG"
>RefMeta</CODE
> information is not specified in a
<CODE
CLASS="SGMLTAG"
>RefEntry</CODE
>, then the man page will be written to standard
output.</P
><P
>The file <TT
CLASS="FILENAME"
>manpage.links</TT
> will also be created, which contains
any aliases of the manpages generated. This file is in the format:
<PRE
CLASS="SYNOPSIS"
><SPAN
CLASS="TOKEN"
><TT
CLASS="REPLACEABLE"
><I
>man page</I
></TT
></SPAN
> <SPAN
CLASS="TOKEN"
><TT
CLASS="REPLACEABLE"
><I
>alias
manpage</I
></TT
></SPAN
></PRE
></P
><P
>The <TT
CLASS="FILENAME"
>manpage.refs</TT
> file keeps track of
<CODE
CLASS="SGMLTAG"
>XRef</CODE
> references. Note that if the input document has any
forward references, then <SPAN
CLASS="APPLICATION"
>docbook2man</SPAN
> may have to be
invoked twice (the first time updating <TT
CLASS="FILENAME"
>manpage.refs</TT
>) to
resolve them.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN693"
></A
><H2
>Requirements</H2
><P
></P
><TABLE
BORDER="0"
><TBODY
><TR
><TD
>The SGMLSpm package from CPAN. This package includes the sgmlspl script
that is also needed.</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN697"
></A
><H2
>Limitations</H2
><P
>Trying <SPAN
CLASS="APPLICATION"
>docbook2man</SPAN
> on non-DocBook or non-conformant
SGML results in undefined behavior. :-)</P
><P
>This program is a slow, dodgy Perl script.</P
><P
>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.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN703"
></A
><H2
>To do</H2
><P
>Obvious stuff:
<P
></P
><UL
><LI
><P
> Fix <SPAN
CLASS="APPLICATION"
>docbook2man</SPAN
> breakages found in
the test documents, especially
<TT
CLASS="FILENAME"
>weird.sgml</TT
>.</P
></LI
><LI
><P
>Add new element handling and fix existing handling.
Be robust. </P
></LI
><LI
><P
> Produce cleanest, readable man output as possible (unlike some
other converters). Follow Linux
<SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>man</SPAN
>(7)</SPAN
>
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. </P
></LI
><LI
><P
>Make it faster. I think most of the speed problems so far is with parsing
ESIS. Rewrite <TT
CLASS="FILENAME"
>SGMLS.pm</TT
> with C and/or get input directly
from <SPAN
CLASS="APPLICATION"
>SP</SPAN
>.</P
></LI
><LI
><P
>Support other (human) languages. But what to do with non-ASCII charsets?
SGMLSpm doesn't report them and <SPAN
CLASS="APPLICATION"
>roff</SPAN
> does not grok them.</P
></LI
></UL
>
If we do this, more people can use DocBook.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN726"
></A
><H2
>Copyright</H2
><P
>Copyright (C) 1998-1999 Steve Cheng <CODE
CLASS="EMAIL"
><<A
HREF="mailto:steve@ggi-project.org"
>steve@ggi-project.org</A
>></CODE
></P
><P
>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.</P
><P
>You should have received a copy of the GNU General Public License along with
this program; see the file <TT
CLASS="FILENAME"
>COPYING</TT
>. If not, please write
to the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.</P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="helpers.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="docbook2texi.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Helper programs</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="helpers.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>docbook2texi-spec.pl</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
