WRITING

The Interchange Development Group
http://www.icdevgroup.org

ICDEVGROUP Documentation Set
http://git.icdevgroup.org/?p=xmldocs.git;a=summary

Documentation writing/authoring QuickStart.


INTRODUCTION

- The new documentation system (XMLDOCS) is based on DocBook XML
  (http://www.docbok.org/, http://www.sagehill.net/), and includes a
  custom processing layer to extend the DocBook set of elements and perform
  other tuning to our specific needs.

- To naturally understand why XMLDOCS looks the way it looks, and how the
  design decision were made, let's quote the ultimate goals of XMLDOCS:

  1) Use custom scripts to auto-generate *every possible bit* of documentation
     that can be autogenerated.
  2) At places where no autogeneration is possible, keep the ammount of
     manual documentation work required at an absolute minimum.

  The first point effectively makes the documentation base follow Interchange
  source code development effort in a timely manner with no user intervention.
  The second point makes writing documentation so easy and convenient that it
  becomes a natural part of the development, without any annoying or time-
  consuming overhead.


BASICS

We use DocBook XML tools to transform our DocBook XML documentation sources
into a number of output formats. When the appropriate DocBook processor is
invoked[1], the XML source files must already be put together and wait ready
to be processed.

As we've said that our goal is to autogenerate as much XML as possible, it's
obvious that we do not keep the XML sources in Git. (That would be pretty
inflexible, make larger changes very inconvenient, and require daily fixes and
updates to the Git repo.)

Instead of the above, what we keep in Git are a number of documentation
snippets (only those parts that need to be written manually). We first rely on
the bin/stattree script to extract information from Interchange sources[2],
then on bin/*-autogen scripts to combine templates, mentioned stattree
information and our snippets into complete, valid XML sources.


The system separates documentation contents into 5 major groups:

 1 guides: prose-based documents that explain concepts and are intended to
 . be read from top to bottom.
 . Autogeneration of contents is obviously of little use here, so we directly
 . keep .xml sources in Git.
 . At (many) places where the external contents need to be included, we use
   xi:include, native DocBook feature.

 2 howto collection: direct answers to direct questions; relatively short
 . documents that contain working examples and supporting technical explanation.
 . In the past, those were small snippets in howtos/* which were put together
 . by bin/generic-autogen script, but in the meantime we moved directly to
 . guides/howtos.xml, as howtos started looking much like regular guides.

 3 reference pages: short, completely on-topic and focused pages documenting
 . all types of symbols. (Symbols are "units" seen in Interchange source - 
 . tags, filters, pragmas, global/catalog variables, Perl functions, ...).
 . Enormous ammount of autogeneration and templating is possible here, and
 . we keep snippets in Git (format is, again, XML with all kinds of headers
   and containers already included in templates so you can just focus on text).

 4 glossary: prose-based collection of glossary items.
 . Some templating is possible here, so we keep individual glossary snippets
 . (in XML format, minus standard headings which are included in the templates)
 . in Git, while they are put together in a single glossary.xml file by the
   bin/generic-autogen script.

 5 whatsnew file: there's a bin/whatsnew-update script that takes care of
 . automatic whatsnew file updates.
 . The .xml file is directly kept in Git, while bin/whatsnew-update knows
 . how to update it; you only need to check-in the updated whatsnew file to Git.
 . More information on this can be found in bin/whatsnew-update and
   whatsnew/whatsnew.xml.

[ 1]: We use xsltproc, a C-based implementation of the XSL processor.
      It is much faster than any of the two alternatives, which are both
      written in Java. Unfortunately, due to the nature of DocBook, processing
      is still visually slow.

[ 2]: Read about the intention and structure of the sources/ directory in the
      README file.


WRITING

Not to waste words, and to give practical examples, best see the existing
documentation for reference on how to write new or update existing material.

You also need to look at docbook/*.ent files, they contain XML entities
that you are encouraged to use instead of writing common symbols, words and
phrases manually over and over. For example, instead of ever mentioning
"Interchange", simply write "⁣". That entity would expand to a proper
name ("Interchange") and also provide a link to the website.

What follows are pieces from one obsolete xmldocs intro document. Some of
this was already said, but we better repeat than omit it:




*** OLD INFO / Usable for more clarification ***

GENERATING FINAL OUTPUT

bin/refs-autogen is used to generate the reference pages
(containing many individual refentries). bin/generic-autogen is used for
the glossary.
The whole autogeneration story comes from the observation that enormous
piece of the final XML source can be produced automatically, with insertions
and templating. So, every chunk you write still has to be XML-conformant
(of course), but you no longer have to write all those repetitive blocks
of XML.

The documentation writing procedure is not always the same, it depends
on the actual part of the content you want to write/update.
The procedure could be the same in theory, but in practice it is mostly
symbol type-dependent, so that more of XML can be autogenerated.


* Modifying Guides

To modify an existing guide, simply edit
guides/name.xml.

To start a new guide, create a new guides/name.xml file. For a quickstart,
copy the exact structure as you see in the existing iccattut guide. The
iccattut guide will always reflect the current standard.

To make the new guide build as part of the global make procedure, open the
Makefile and simply add the guide .xml name under the GUIDES = section.

To build a guide manually, invoke "make OUTPUT/name.format", where 'format'
represents typical filename extensions (such as .html or .ps). If you leave
".format" unspecified, the chunked HTML version will be built
and, of course, saved to OUTPUT/name/.


* Modifying Symbols (pragmas, globvars, *tags, globconfs, catconfs, filters)

To modify an existing symbol, simply edit refs/* or refs/*/* (depending on
whether the symbol documentation was saved in one-file or multi-file format).
Multi-file format was used in the beginning, and although is still normally
supported, it seems to be less convenient, and should not be used.

To document a new symbol using one-file format, run 'bin/editem name'.
This will create skeleton file (refs/name) and load it in your editor.
Before you get the grip, carefully read the embedded comments in the file
that will guide you through (Delete the comments as you go).

After you've added a symbol, you need to regenerate the refs/*.xml files
which it affected. This should happen as part of the standard Make dependency
resolution, but if you need to invoke unconditional manual regeneration, 
use 'make clean-refs refxmls'.

Note that the refentries can be built in manpage format as well. To generate
the manpages, run 'make OUTPUT/group.man', where group is one of
pragmas, globvars, usertags, systemtags, uitags etc. The output manpages
will be placed to a common manpage directory, OUTPUT/man/.


* Modifying Glossary

To modify an existing item, simply edit the appropriate glossary/* file.

To add a new glossary entry, create the glossary/name file
(copy the structure from say, glossary/ITL).

To generate the glossary XML source manually, run 'make glossary/glossary.xml'.
To build the glossary, run make OUTPUT/glossary.format.



Davor Ocelic, docelic@icdevgroup.org