<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>