Add documentation to DEVELOPER and add a summary line

[netatalk.git] / doc / DEVELOPER

diff --git a/doc/DEVELOPER b/doc/DEVELOPER
index 4a1e7de1ce6ac562ed49d931f4394702208c8c31..2ddb69f6fc410e91078436ff7b3ca81406592300 100644 (file)
--- a/doc/DEVELOPER
+++ b/doc/DEVELOPER
@@ -288,3 +288,54 @@ filenames for the usock_file parameter.
 
 - There is no protection against a malicious user connecting to the
 cnid_dbd socket and changing the database.
+
+Documentation
+=============
+Netatalk documentation is in Docbook XML format. In order to build manpages
+and the html documentation from the Docbook docs you need the following:
+
+1. Install `xsltproc`
+
+2. Get the latest Docbook XSL stylesheet distribution from:
+   https://sourceforge.net/project/showfiles.php?group_id=21935
+   Tested docbook-xsl stylesheet version is 1.75.2.
+
+3. Fix indexterm bug in xsl stylesheet:
+   inside the xsl stylesheet distribution in manpages/inline.xsl remove these lines:
+
+        <!-- * indexterm instances produce groff comments like this: -->
+        <!-- * .\" primary: secondary: tertiary -->
+        <xsl:template match="indexterm">
+          <xsl:text>.\" </xsl:text>
+          <xsl:apply-templates/>
+          <xsl:text>&#10;</xsl:text>
+        </xsl:template>
+
+        <xsl:template match="primary">
+          <xsl:value-of select="normalize-space(.)"/>
+        </xsl:template>
+
+        <xsl:template match="secondary|tertiary">
+          <xsl:text>: </xsl:text>
+          <xsl:value-of select="normalize-space(.)"/>
+        </xsl:template>
+
+4. Add the following argument to configure
+   --with-docbook=PATH_TO_XML_STYLESHEET_DIR
+
+5. The manpages and html documentation are now automatically built when running `make html`.
+
+Editing Docbook Sources
+-----------------------
+Free WYSIWYG editor with only one minor drawback is XMLEditor from XMLmind:
+http://www.xmlmind.com/xmleditor/persoedition.html
+
+Drawback: in order to be able to edit any of the  nested xml files, you have to
+"promote" them to valid Docbook files by referencing the Docbook DTD, insert as line 2+3:
+       
+       <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+       "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+These changes will however prevent XMLeditor from opening the master xml file
+manual.xml. Before further processing can be done these changes then have to be
+reverted for any changed file.