All formal documents are maintained in Docbook SGML and located in the
- doc/source/*doc/source/* directory. You will need
Formal documents are built with the Makefile targets of
- make dokmake dok, or alternately
- make redhat-dokmake redhat-dok. If you have problems,
try both. The build process uses the document SGML sources in
- doc/source/*/*doc/source/*/* to update all text files in
- doc/text/doc/text/ and to update all HTML
- documents in doc/webserver/doc/webserver/.
First, build the docs by running First, build the docs by running make
- dok (or alternately (or alternately make
- redhat-dok). For PDF docs, do ). For PDF docs, do make
- dok-pdf.
Run Run make webservermake webserver which copies all
- files from doc/webserverdoc/webserver to the
sourceforge webserver via scp.
3.1. Quickstart to Docbook and SGML
3.1. Quickstart to Docbook and SGML
If you are not familiar with SGML, it is a markup language similar to HTML. Actually, not a mark up language per se, but a language used to define @@ -329,10 +333,10 @@ CLASS="QUOTE" CLASS="QUOTE" >"closed". If not, you - will likely generate errors. Example: <title>My - Title</title>. They are also case-insensitive, but we strongly suggest using all lower case. This keeps compatibility with [Docbook] "sections" for the most part. Sections - will be processed into HTML headers (e.g. h1h1 for - sect1sect1). The Docbook stylesheets will use these to also generate the Table of Contents for each doc. Our - TOC's are set to a depth of three. Meaning sect1sect1, - sect2, and sect2, and sect3sect3 will have TOC - entries, but sect4sect4 will not. Each section requires - a <title><title> element, and at least one - <para><para>. There is a limit of five section levels in Docbook, but generally three should be sufficient for our purposes.
<literallayout></literallayout>, like - <pre><pre>, more or less. <screen></screen>, screen output, implies - <literallayout><literallayout>. <ulink url="example.com"></ulink>, like - HTML <a><a> tag.It will be easier if everyone follows a similar writing style. This just makes it easier to read what someone else has written if it @@ -659,9 +665,9 @@ CLASS="QUOTE" CLASS="APPLICATION" >aspell can check SGML with the - -H-H option. (ispell
"internal entities". These are like variables in programming. Well, sort of. For instance, we have the - p-versionp-version entity that contains the current text entities are defined like:
<!entity supported SYSTEM "supported.sgml"><!entity supported SYSTEM "supported.sgml">
supported.sgml is available for inclusion anywhere in the doc. To make this happen, just reference the now defined - entity: &supported;&supported; (starts with an ampersand and ends with a semi-colon), and the contents will be dumped into the finished doc at that point. @@ -787,7 +795,7 @@ CLASS="APPLICATION" > version string, e.g. "3.1.1""3.0.3".