Building The Manual
From Audacity Wiki
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
Contents
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 Python2.7 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: 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.
Error creating thumbnail: Unable to save thumbnail to destination
|
For details of how auto-generated pages are generated see: |
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.