Editing Software Development Platforms (section)

===asciidoc===

asciidoc is used for the faim manual.

The source code can be obtained from

http://sourceforge.net/projects/asciidoc/

It can be installed with

 tar xvzf asciidoc-8.6.8.tar.gz
 cd asciidoc-8.6.8
 ./configure --prefix=/opt/asciidoc-8.6.8
 make
 sudo make install

You'll need some docbook style sheets.  Download Docbook XML 4.5 from http://www.docbook.org/xml/4.5/ and unpack it inside /usr/local/share/xml/docbook/4.5.
Download the latest Docbook XSL version from http://sourceforge.net/projects/docbook/files/docbook-xsl/ and unpack it. The name should be of the form docbook-xsl-1.nn.n.tar.bz2. Put the results in /usr/local/share/xsl/docbook, thus effectively removing the version number from the directory name (for simplicity).

Now you'll need to create the file /etc/xml/catalog and populate it like this:

<source lang=xml>
<?xml version="1.0"?>
<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">

<!-- ===== BEGIN docbook-xml entries ===== -->

<!--  docbook-xml V4.x  --> 
  <delegatePublic 
     publicIdStartString="-//OASIS//DTD DocBook XML"
     catalog="/usr/local/share/xml/docbook/4.5/catalog.xml"/> 

  <delegateSystem 
     systemIdStartString="http://www.oasis-open.org/docbook/xml/4" 
     catalog="/usr/local/share/xml/docbook/4.5/catalog.xml"/> 

<!-- ===== END docbook-xml entries ===== --> 

<!-- ===== BEGIN docbook-xsl entries ===== --> 

  <delegateURI 
     uriStartString="http://docbook.sourceforge.net/release/xsl/"
     catalog="/usr/local/share/xsl/docbook/catalog.xml"/> 

  <delegateURI 
     uriStartString="http://docbook.sf.net/release/xsl/"
     catalog="/usr/local/share/xsl/docbook/catalog.xml"/> 

<!-- ===== END docbook-xsl entries ===== -->

</catalog>
</source>

Here is the [[#Scripts_to_Set_Environment_Variables|setenv.sh]] script.

----
<source lang=bash>
#!/bin/bash
 
source /Users/Shared/install/dblatex-0.3.2/setenv.sh
source /Users/Shared/install/source-highlight-3.1.7/setenv.sh
 
remove_path PATH '/.*/asciidoc(-[^/]+)?/bin/?'
 
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 
export ASCIIDOC_DIR="${SCRIPT_DIR}"
add_path PATH "${ASCIIDOC_DIR}/bin"
</source>
----

I like to make one change, which is to change the indexterm macro so that secondary and tertiary entries are not automatically also promoted to primary index terms.  To do this, edit the file etc/asciidoc/docbook45.conf , find the section on indexterm, and comment out the lines that do that.