Maintaining Documentation

Stable branch and development branch

We continously maintain documentation for the stable version, and for the development version. Basically, we maintain the descriptions in the development documentation to reflect SVN HEAD. Thus these documents are never really stable, but always a work in progress.

When we make a stable release, we take a snapshot of the current development documentation. This is the stable documentation. It should only be updated if there are factual errors, or if we make a new minor release of the stable software. Otherwise documentation is updated in the development branch.

The stable documentation snapshot is also made available as PDF files.

The documentation is maintained in separate wikipages per chapter, and combined by Include-macros on the main manual wiki-page. Illustrations are attached to the subpages.

Making a snapshot

Making a snapshot of the development documentation is a somewhat elaborate procedure. Here are the necessary steps.

  1. Mark on all the main stable manual pages that the manuals are being updated. Simply replace all text with something like "This manual is being updated. Please check back in an hour."
  2. For all XXX_Manual_devel/YYY wikipages (you can find them in the Title Index)
    1. view them as raw text
    2. copy the entire text
    3. paste it in the wikipage XXX_Manual/YYY (create it if necessary)
    4. replace all links to ZZZ_Manual_devel with Manual_devel
    5. download all attachments from XXX_Manual_devel/YYY
    6. upload all attachments to XXX_Manual_devel/YYY
  3. For all main XXX_Manual_devel pages
    1. view them as raw text
    2. copy the entire text
    3. paste it in the wikipage XXX_Manual/YYY (create it if necessary)
    4. replace all links to ZZZ_Manual_devel with ZZZ_Manual
    5. replace the text in the top saying that this is the development manual with text saying it is the stable manual.
  4. Sanity test
    1. Check that no part of the stable manual points to the development manual (this can be done by clicking the title link while viewing the development manual. That will find all pages linking to the development manual)
    2. Check there are no missing attachments. This can be done by searching for the word "attachment" in the manual pages

Making PDF files from stable documentation

This is done by printing to a PDF-file.

To make illustrations the approximate right size, we have experienced that printing from firefox 3 gives good results. Headers and footers should be removed in the page setup.