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

