1 files changed, 100 insertions, 0 deletions
diff --git a/doc/man/docbook2man-spec.pl.1 b/doc/man/docbook2man-spec.pl.1
new file mode 100644
index 0000000..014c942
--- /dev/null
+++ b/doc/man/docbook2man-spec.pl.1
@@ -0,0 +1,100 @@
+.\" 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" "11 February 2004" "" ""
+
+.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.