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

[Soulliere, Robert]

Hi Steve,

Tha is a good idea but we are actually using this index trick to create an actual index.

See:
http://libdog.mohawkcollege.ca/evergreen_documentation/draft/html/ix01.html to see how it looks.

We also have the index page in github:
http://github.com/rsoulliere/Evergreen-DocBook/blob/master/1.6/appendices/bookindex.xml

and it is included in the root.xml document:
http://github.com/rsoulliere/Evergreen-DocBook/blob/master/1.6/root.xml

Not sure if creating blank index terms  for managing incomplete sections will create confusion given that we are generating a real index.

Thanks for working on the glossary. It is looking great and I added it in the main document just a few minutes ago:
http://libdog.mohawkcollege.ca/evergreen_documentation/draft/html/go01.html


Thanks
Robert




We do not have many terms yet, but based on the outline a real index will be in the document:
http://evergreen-ils.org/dokuwiki/doku.php?id=evergreen-docs:outline
________________________________________
From: open-ils-documentation-bounces at list.georgialibraries.org [open-ils-documentation-bounces at list.georgialibraries.org] On Behalf Of steve sheppard [ssheps at gmail.com]
Sent: September 10, 2010 12:24 PM
To: open-ils-documentation at list.georgialibraries.org
Subject: [OPEN-ILS-DOCUMENTATION] mark up for unfinished parts of our   documents

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 >% ========


This E-mail contains privileged and confidential information intended
only for the individual or entity named in the message.  If the reader
of this message is not the intended recipient, or the agent responsible
to deliver it to the intended recipient, you are hereby notified that
any review, dissemination, distribution or copying of this communication
is prohibited.  If this communication was received in error, please
notify the sender by reply E-mail immediately, and delete and destroy
the original message.