1 files changed, 171 insertions, 0 deletions
diff --git a/doc/refentry/docbook2texi-spec.pl.sgml b/doc/refentry/docbook2texi-spec.pl.sgml
new file mode 100644
index 0000000..e79d8df
--- /dev/null
+++ b/doc/refentry/docbook2texi-spec.pl.sgml
@@ -0,0 +1,171 @@
+<RefEntry id="docbook2texi">
+
+<RefMeta>
+<RefEntryTitle>docbook2texi-spec.pl</RefEntryTitle>
+<ManVolNum>1</ManVolNum>
+</RefMeta>
+
+<RefNameDiv>
+<RefName>docbook2texi-spec.pl</RefName>
+<RefPurpose>convert DocBook <SGMLTag>Book</sgmltag>s
+to <Application>Texinfo</application> documents</RefPurpose>
+</RefNameDiv>
+
+<RefSynopsisDiv>
+<CmdSynopsis>
+<Command>sgmlspl</command>
+<Arg choice=req>docbook2man-spec.pl</arg>
+</CmdSynopsis>
+
+<!-- docbook2man-spec.pl BREAKAGE HERE! -->
+
+<CmdSynopsis>
+<Command>nsgmls</command>
+<Arg><Replaceable>sgml document</replaceable></Arg>
+<Command>| sgmlspl</command>
+<Arg choice=req>docbook2texi-spec.pl</arg>
+<Arg><Replaceable>basename</replaceable></Arg>
+</CmdSynopsis>
+</RefSynopsisDiv>
+
+<RefSect1>
+<Title>Description</Title>
+
+<Para>
+<Application>docbook2texi</application> is a sgmlspl spec file that produces
+GNU Texinfo documents from DocBook documents.  
+</Para>
+
+<Para>
+The program reads ESIS produced by nsgmls (or other SGML parsers) from
+standard input.  Currently the document element must be <SGMLTag>Book</sgmltag>,
+otherwise the results are undefined.
+</Para>
+
+<Para>
+Its output, the converted Texinfo document, is written to standard
+output.
+</Para>
+
+<Para>
+The file <Filename><Replaceable>basename.refs</replaceable></Filename> will also
+be created, which contains all the nodes in the document and their immediate
+'child' nodes.  As node processing always require forward references,
+<Application>docbook2texi</application> must be run twice for each document: the
+first time to build the references, and the second to actually generate a valid
+document.
+</Para>
+
+</RefSect1>
+
+<RefSect1>
+<Title>Requirements</Title>
+
+<SimpleList>
+<Member>
+The SGMLSpm package from CPAN.  This package includes the sgmlspl script
+that is also needed.
+</Member>
+</SimpleList>
+
+</RefSect1>
+
+
+<RefSect1>
+<Title>Limitations</Title>
+
+<Para>
+Trying <Application>docbook2man</application> on non-DocBook or non-conformant
+SGML results in undefined behavior. :-)
+</Para>
+
+<Para>
+This program is a slow, dodgy Perl script.
+</Para>
+
+<Para>
+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.
+</Para>
+
+</RefSect1>
+
+<RefSect1>
+<Title>To do</Title>
+
+<ItemizedList>
+
+<ListItem><Para>
+How the hell do you represent a backslash (<Literal>\</literal>) in Texinfo!!@?
+I've tried <Literal>\\</literal> but TeX complains about it.
+</Para>
+</ListItem>
+
+<ListItem><Para>
+Fix breakages found in the test documents.
+</Para>
+</ListItem>
+
+<ListItem><Para>
+Add new element handling and fix existing handling.  
+Be robust.  
+</Para></ListItem>
+
+<ListItem>
+<Para>Make it faster. I think most of the speed problems so far is with parsing
+ESIS.  Rewrite <Filename>SGMLS.pm</filename> with C and/or get input directly
+from <Application>SP</application>.
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+There are some dependencies on elements occurring when they are actually
+optional (according to the DTD).  We need to fix that (preferably) or 
+prominently state the requirements.
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+Allow other more common document elements.
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+Separate out node referencing to a separate script.  Not only would it
+make it faster/easier to maintain because it's separate from the main
+code, but also I would like it to evolve into an automatic DocBook
+<SGMLTag>ToC</sgmltag> generator.
+</Para>
+</ListItem>
+
+</ItemizedList>
+</RefSect1>
+
+<RefSect1>
+<Title>Copyright</Title>
+
+<Para>
+Copyright (C) 1998-1999 Steve Cheng <Email>steve@ggi-project.org</email>
+</Para>
+
+<Para>
+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.
+</Para>
+
+<Para>
+You should have received a copy of the GNU General Public License along with
+this program; see the file <Filename>COPYING</filename>.  If not, please write
+to the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
+</Para>
+
+</RefSect1>
+
+</RefEntry>
+