100 lines
3.4 KiB
Groff
100 lines
3.4 KiB
Groff
|
.\" This manpage has been automatically generated by docbook2man
|
||
|
|
.\" from a DocBook document. This tool can be found at:
|
||
|
|
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/>
|
||
|
|
.\" Please send any bug reports, improvements, comments, patches,
|
||
|
|
.\" etc. to Steve Cheng <steve@ggi-project.org>.
|
||
|
|
.TH "DOCBOOK2MAN-SPEC.PL" "1" "27 June 2002" "" ""
|
||
|
|
.SH NAME
|
||
|
|
docbook2man-spec.pl \- convert DocBook RefEntries to man pages
|
||
|
|
.SH SYNOPSIS
|
||
|
|
|
||
|
|
\fBsgmlspl\fR \fBdocbook2man-spec.pl\fR
|
||
|
|
|
||
|
|
|
||
|
|
\fBnsgmls\fR [ \fB\fIsgml document\fB\fR ]\fB| sgmlspl\fR \fBdocbook2man-spec.pl\fR
|
||
|
|
|
||
|
|
.SH "DESCRIPTION"
|
||
|
|
.PP
|
||
|
|
\fBdocbook2man\fR is a sgmlspl spec file that produced man
|
||
|
|
pages (using the -man macros) from DocBook RefEntry markup.
|
||
|
|
.PP
|
||
|
|
The program reads ESIS produced by nsgmls (or other SGML parsers) from
|
||
|
|
standard input. Markup not found in RefEntry is discarded.
|
||
|
|
.PP
|
||
|
|
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.
|
||
|
|
.PP
|
||
|
|
The file \fImanpage.links\fR will also be created, which contains
|
||
|
|
any aliases of the manpages generated. This file is in the format:
|
||
|
|
|
||
|
|
.nf
|
||
|
|
\fI<man page>\fR \fI<alias
|
||
|
|
manpage>\fR
|
||
|
|
.fi
|
||
|
|
.PP
|
||
|
|
The \fImanpage.refs\fR file keeps track of
|
||
|
|
XRef references. Note that if the input document has any
|
||
|
|
forward references, then \fBdocbook2man\fR may have to be
|
||
|
|
invoked twice (the first time updating \fImanpage.refs\fR) to
|
||
|
|
resolve them.
|
||
|
|
.SH "REQUIREMENTS"
|
||
|
|
|
||
|
|
The SGMLSpm package from CPAN. This package includes the sgmlspl script
|
||
|
|
that is also needed.
|
||
|
|
.SH "LIMITATIONS"
|
||
|
|
.PP
|
||
|
|
Trying \fBdocbook2man\fR on non-DocBook or non-conformant
|
||
|
|
SGML results in undefined behavior. :-)
|
||
|
|
.PP
|
||
|
|
This program is a slow, dodgy Perl script.
|
||
|
|
.PP
|
||
|
|
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.
|
||
|
|
.SH "TO DO"
|
||
|
|
.PP
|
||
|
|
Obvious stuff:
|
||
|
|
.TP 0.2i
|
||
|
|
\(bu
|
||
|
|
Fix \fBdocbook2man\fR breakages found in
|
||
|
|
the test documents, especially
|
||
|
|
\fIweird.sgml\fR.
|
||
|
|
.TP 0.2i
|
||
|
|
\(bu
|
||
|
|
Add new element handling and fix existing handling.
|
||
|
|
Be robust.
|
||
|
|
.TP 0.2i
|
||
|
|
\(bu
|
||
|
|
Produce cleanest, readable man output as possible (unlike some
|
||
|
|
other converters). Follow Linux
|
||
|
|
\fBman\fR(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.
|
||
|
|
.TP 0.2i
|
||
|
|
\(bu
|
||
|
|
Make it faster. I think most of the speed problems so far is with parsing
|
||
|
|
ESIS. Rewrite \fISGMLS.pm\fR with C and/or get input directly
|
||
|
|
from \fBSP\fR.
|
||
|
|
.TP 0.2i
|
||
|
|
\(bu
|
||
|
|
Support other (human) languages. But what to do with non-ASCII charsets?
|
||
|
|
SGMLSpm doesn't report them and \fBroff\fR does not grok them.
|
||
|
|
[Comment: text after enclosed lists (and SS blocks) will break docbook2man]
|
||
|
|
If we do this, more people can use DocBook.
|
||
|
|
.SH "COPYRIGHT"
|
||
|
|
.PP
|
||
|
|
Copyright (C) 1998-1999 Steve Cheng <steve@ggi-project.org>
|
||
|
|
.PP
|
||
|
|
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.
|
||
|
|
.PP
|
||
|
|
You should have received a copy of the GNU General Public License along with
|
||
|
|
this program; see the file \fICOPYING\fR. If not, please write
|
||
|
|
to the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
|