[OPEN-ILS-DOCUMENTATION] mark up for unfinished parts of our documents

[steve sheppard]

All,
In the doclist back on "Wed Aug 11 13:09:39 EDT 2010" there was discussion
of marking up a document to call attention to bits that are unfinished, need
further review, or need to be expanded. Requirements were:
1. Easy to see what gaps still exist;
2. Info is available outside the document;
3. Info is in quick-outline form for fast reference.

You can accomplish this by sprinkling modified <indexterm/> tags in your
document, just as if you were adding items to be indexed normally.

Steps follow:
1. Append an empty Index section to the end of the XML document;
2. Add <indexterm/><primary/><secondary/> tags to the unfinished bits within
the document
   (the clever bit:   note the "secondary" tag to force all tagged items
into one section of the index);
3. Run the document through our usual "xsltproc/fo" tool chain.

The new Index will be populated with a special section listing all the
unfinished bits tagged within the document.

The indexed info is in one place, can be quickly reviewed, and is
essentially available outside the document. And, if you click on the page
number for a tag in the Index, the link immediately transports you to the
tagged bit in the document.
It works well for me and is how I keep track of the unfinished bits in my
own documents.

Our tool chain builds both PDF and HTML files; I tested and found the Index
links work in both. The HTML file + Index can be added to our wiki, so
everyone can review the unfinished bits.

Following is a short XML example document; try running it through your tool
chain.

Cheers!
--steve

======== %< SNIP-SNIP >% ========  ======== %< SNIP-SNIP >% ========
======== %< SNIP-SNIP >% ========
<?xml version="1.0" encoding="UTF-8"?>
<chapter xml:id="ServersideInstallation"
     xmlns="http://docbook.org/ns/docbook"
     xmlns:xi="http://www.w3.org/2001/XInclude"
     xmlns:xl="http://www.w3.org/1999/xlink">

<section xml:id="serversideinstallation-localization">
    <title>(OPTIONAL) Configuration for Other Languages</title>
    <para>This section describes how translations such as Canadian French
(fr-CA) are handled.</para>
    <indexterm><primary>REVIEW THIS STUFF</primary><secondary>ADD SECTION ON
LANGUAGE LOCALIZATION</secondary></indexterm>
</section>

<section xml:id="serversideinstallation-sushi">
    <title>Configuring Sushi</title>
    <para>This section describes sushi prep</para>
    <indexterm><primary>REVIEW THIS STUFF</primary><secondary>ADD SECTION ON
PREPARING SUSHI</secondary></indexterm>
</section>
<index/>
</chapter>
======== %< SNIP-SNIP >% ========  ======== %< SNIP-SNIP >% ========
======== %< SNIP-SNIP >% ========
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20100910/147ecc4e/attachment.htm 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: example.xml
Type: text/xml
Size: 830 bytes
Desc: not available
Url : http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20100910/147ecc4e/attachment.bin