<article id="xacc-dochack">
<artheader>
<title> Hacking GnuCash Documentation </title>
<author>
<firstname>Christopher</firstname>
<surname>Browne</surname>
</author>
</artheader>

<sect1 id="xacc-docbook">

<title> About DocBook </title>

<para> The GnuCash documentation has been changed to use SGML, and, in
particular, the DocBook DTD.  </para>

<PARA> DocBook is a DTD designed for authoring technical documents
such as computer manuals.  A number of tools are growing up to assist
in processing DocBook-based material.

<ITEMIZEDLIST>

<LISTITEM>
<PARA> <ULINK URL="http://docbook.org/tdg/html/docbook.html"> DocBook:
The Definitive Guide (online)</ULINK>

</PARA>
</LISTITEM>

<LISTITEM> <PARA><ULINK URL=
"http://www.oasis-open.org/docbook/documentation/index.html"> DocBook
- Documentation</ULINK></PARA> </LISTITEM>

<LISTITEM>
<PARA><ULINK URL="http://www.oasis-open.org/docbook/">DocBook -
DocBook</ULINK></PARA>
</LISTITEM>

<LISTITEM>
<PARA> <ULINK URL="http://ella.slis.indiana.edu/~jfieber/docbook/doc/over/index.html"> DocBook
Overview </ULINK> </PARA>
</LISTITEM>
<LISTITEM>
<PARA> <ULINK URL="http://ella.slis.indiana.edu/~jfieber/docbook/doc/user/index.html"> DocBook User
Guide </ULINK> </PARA>
</LISTITEM>
<LISTITEM>
<PARA> <ULINK URL="http://ella.slis.indiana.edu/~jfieber/docbook/doc/ref/index.html"> DocBook
Reference Guide </ULINK> </PARA>
</LISTITEM>
<LISTITEM>
<PARA> <ULINK URL="http://ella.slis.indiana.edu/~jfieber/docbook/doc/maint/index.html">DocBook
Customization Guide </ULINK> </PARA>
</LISTITEM>
<LISTITEM ID="MODULARDOCBOOK">
<PARA> <ULINK URL="http://nwalsh.com/docbook/dsssl/index.html"> The
Modular DocBook Stylesheets </ULINK> </PARA>
</LISTITEM>
<LISTITEM>
<PARA><ULINK URL="http://nwalsh.com/docbook/edbsyn/"> The
nwalsh.com Home Page - Extended DocBook Synopses </ULINK>
</PARA>

<PARA> Adds tags for DocBook to support object oriented languages like
Java, C++, and IDL, including such new entities as classes, fields,
methods, exceptions, and so forth.
</PARA>

</LISTITEM>
<LISTITEM>
<PARA> <ULINK URL="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html"> Get
Going With DocBook </ULINK></PARA>
<PARA> This document describes how one might use the DocBook DTD to
write documents, including information on how to use tables, and
insert program listings.  </PARA>
<PARA> Hopefully it will soon document the care and feeding of insertion
of graphics, and more information on ``interesting'' crossreferencing.</PARA>
</LISTITEM>
<LISTITEM>
<PARA><ULINK URL="http://lwn.net/2000/features/DocBook/">Exploring SGML DocBook </ULINK>
</PARA>
</LISTITEM>

<LISTITEM> <PARA><ULINK URL=
"http://www.dfwuug.org/newsletters/2000/newsletter_0003.html"> My
review of DocBook: The Definitive Guide </ULINK> as written for the
DFW Unix User's Group

</PARA>
</LISTITEM>
<LISTITEM>
<PARA><ULINK URL="http://www.sslug.dk/%7epto/docbook.html">Getting started with SGMLTOOLS and DOCBOOK</ULINK></PARA>
</LISTITEM>
</ITEMIZEDLIST> </PARA>

</sect1>

<sect1 id="xacc-docbookuse">
<title>The GnuCash Documentation Set</title>

<para> The GnuCash documentation is managed as a BOOK, composed of a
set of DocBook "ARTICLES." </para>

<PARA> The main document is <filename>gnucash.sgml</filename>, which
really contains only the "sequencing" information on what files are to
be consulted to make up the body of the document, each file
representing one of the ARTICLEs. </PARA>

<para> Note that filenames for the HTML output files are generated in
three ways:</para>

<itemizedlist>

<listitem><para> The ID tag for each ARTICLE defines a
filename;</para></listitem>

<listitem><para> The ID tag for each SECT1 defines a filename, unless
it is the first SECT1 in an ARTICLE;</para></listitem>

<listitem><para> If you create a new ARTICLE or SECT1 without an ID
tag, filenames will be generated with names like
<filename>t1234.html</filename>, <filename>x892.html</filename>, and
such.  They will look quite random. </para>

<PARA> This is a bad thing; make sure you assign an ID tag to the
ARTICLE or SECT1. </para>
</listitem>

</itemizedlist>

<para> Styling is controlled by the DSSSL document,
<filename>mysheet.dsl</filename>, using the conventions documented in
the <link linkend="MODSTYLE"> Modular DocBook Stylesheets
</link></para>

<para> Components that need to be installed in order for the command
<command>jade -ioutput.html -d mysheet.dsl -t sgml
gnucash.sgml</command> to work include:

<itemizedlist>

<listitem><para> <ULINK URL="http://www.jclark.com/jade/">Jade
</ULINK> or <ULINK URL= "http://www.netfolder.com/DSSSL/index.html">
DSSSL/OpenJade </ULINK></para></listitem>

<listitem><para> The DocBook 3.1 DTD, available from <ULINK URL=
"http://docbook.org"> DocBook.org </ULINK></para></listitem>

<listitem><para> Norman Walsh's <ULINK id="MODSTYLE" URL=
"http://nwalsh.com/docbook/dsssl/index.html"> Modular DocBook
Stylesheets </ULINK></para></listitem>

</itemizedlist>
</para>
</sect1>

</article>

<!-- Local variables: -->
<!-- sgml-parent-document: "gnucash.sgml" -->
<!-- End: -->
