Building The Manual

This page is about Building a local copy of the manual which we maintain in a wiki

ToDo-2 There is probably text on Create Local Manual to plunder for this page

Background

 

• Many dialogs in Audacity have help buttons that link into the manual.
• We use a wiki for our manual and provide a local copy with windows installers and with Mac .dmgs.
• If the local copy isn't present, audacity opens the corresponding page on the internet.

 

Copying the Manual Locally

 Audacity's manual is maintained in a wiki, https://alphamanual.audacityteam.org/man/Main_Page.

 We have a Python3 script that crawls pages reachable from the front page, and converts them 
 to a form suitable for local use.
   cd scripts/mw2html_audacity
   bash wiki2htm.sh

 Or on windows (make sure to have python3 on your path):
   cd scripts/mw2html_audacity
   wiki2htm.bat

 This script mutates the manual slightly.  For example it removes 'Alpha' and 'Development' from 
 the title.

Snapshot of Manual

At release time we take a snapshot of the manual using the script and upload it to our server.

This update/upload used to be done by our sys admin.
Now instead we copy the files into a git repo, https://github.com/audacity/audacity-manual

A script on our server checks at regular intervals, and if there has been an update, it 
deploys the new changes.

Occasionally we make small corrections direct in the git repo by hand.  More usually we 
simply overwrite the contents, using the snapshot, and commit that. 

Updating the Wiki

The source for our manual, in turn, is maintained using MediaWiki software (written in php). We have templates and some media wiki extensions installed to make the job easier.

• Template:All-Menus is a big auto-generated switch statement that offers image mapped versions of the menus all in one place.

For details of how auto-generated pages are generated see: Magicke Spells

Variations

These variations are completely optional, and not part of a normal full release.

LaTeX and Pdf Versions

• See https://github.com/JamesCrook/TeamTools for code for extracting a pdf version.

Narrow/Mobile Versions

• A narrow version of the MediaWiki html can be obtained using modified css.
• An example is present at https://wit.audacityteam.org
• The code used in creating that is at https://github.com/JamesCrook/TeamTools

Translated Versions

We have partial translations of the manual, none complete enough yet to distribute.

• We ask translators to focus on the FAQ, as these have the most value for the work involved.
  • A complete FAQ translation could be released as a pdf.
• The Tour Guide is also a good page for translation.

For Developers