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 promote current development documentation to be the stable documentation. It should then only be updated if there are factual errors, or if we make a new minor release of the stable software. We then copy all documentation to the development branch, where all other documentation updates should be maintained.

The previous stable documentation made available as a snapshot in 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.

Copying documentation to a new branch:

  1. Find page names

    • Go to the wiki

    • Enter the old version number (e.g. 3.10) in the search field, click 'Titles'
    • Copy all the page names into an open text editor
  2. Package data

    • Make sure you have the Firefox Add-on 'Tamper Data'

    • Go to Documentation

    • From the 'More Actions:'-dropdown, select 'Package Pages'
    • Under 'List of page names - separated by a comma' enter a few page names.
      • Unfortunately, the input field has a max-length that avoids inputting them all.
      • To get around this:

        • Turn on Tamper Data by selecting 'Tools'->'Tamper Data'

        • Click 'Start Tamper'
        • Then click the 'Package pages' button on the web page
        • Remove the checkbox for 'Continue tampering', then click 'Tamper'
        • Replace the value for 'pagelist' with the entire list of pages
          • Note that the list needs to be URL-encoded, including the commas.

          • You can use an online tool for this, for instance this one

        • Click OK
    • A zip-file is now attached to the page, click 'Attachments'
    • Click 'get' and save it to disk
    • Click 'del' to delete it from the page
  3. Update package
    • Unzip the package
    • Edit the file MOIN_PACKAGE

    • Query/Replace "Created by the PackagePages action." with "Generated documentation branch for 3.12" (replace 3.12 with the new version number)

    • Query/Replace "3.10" with "3.12" (replace with old and new version numbers)
    • In all the pages named with numbers, replace 3.10 with 3.12
      • You can automate this with Linux tools.
      • First make sure all references to 3.10 can be replaced with 3.12.

        • $ grep -h -r -o ........."3\.10" .|sort -u

        • This lists all occurences of 3.10 with 9 characters of context.
          • Review everything that isn't a manual
      • Then replace 3.10 with 3.12

        • $ sed -i -e "s/3\.10/3.12/g" *

      • If anything from the review above indicated that it should not be replaced, manually change it back.
    • Zip the package again
  4. Install the package

    • Go to Documentation

    • Click 'Attachments'
    • Add the new package
    • Click 'install' (requires that you are moin moin superuser. To become superuser add yourself to the wikiconfig.py file)
  5. Copy all attachments (this is the annoying manual part)

    • Go to the title index

    • For all pages in the 3.10 manuals with a paper click next to them, do the following:
      • Click the paperclick
      • Save all attachments to disk

      • Edit the URL line in your browser to the new version (e.g. 3.10->3.12)

      • Upload all the saved attachments
  6. Update the text on manuals in progress
    • For all manuals in the 3.10-scope, remove the text about the manuals being in progress
    • For all manuals in the 3.12-scope, update the reference to stable manuals to point to the 3.10 manuals
  7. Take a snapshot at the old stable manual (e.g. 3.8)
  8. Update the manual front page

    • Go to Documentation

    • Update stable manuals to point to 3.10. Update unstable manuals to point to 3.12
  9. Update redirect pages

Maintaining Documentation (last edited 2010-11-23 17:59:43 by SoerenCarlsen)