The Csound Canonical Reference Manual
To install DocBook and xsltproc, run
sudo apt-get install -y docbook xsltproc
Python is preinstalled on most Linux distributions. If you don’t have Python, visit https://docs.python.org/2/using/unix.html to learn how to install Python or build it from source.
To install Pygments v2.1 or later, run
sudo pip install 'pygments>=2.1'
or, if you don’t have pip,
sudo easy_install 'pygments>=2.1'
To install Pygments v2.1 or later, enter in Terminal
sudo easy_install 'pygments>=2.1'
Python and xsltproc are preinstalled on macOS.
To install Python, visit https://www.python.org/downloads/windows/ and download and run an installer for the latest release of Python 2.7. Make sure you add python.exe to your Windows Path when you install Python.
Visit http://pygments.org/download/ to learn how to install Pygments.
make ⟨target⟩ to build a
⟨target⟩. For example, to build a collection of
HTML webpages, run
If DocBook is installed in a nonstandard way, you may see this error: “The
XSL_BASE_PATH variable must be set to the XSL stylesheets installation
directory.” To tell
make where to find DocBook, run
make XSL_BASE_PATH=path/to/docbook/stylesheets ⟨target⟩
If you see an error message that
CsoundDocumentLexer isn’t found when you try
to build a
⟨target⟩, then you’re probably using Pygments v2.0.2 or earlier,
and you need Pygments v2.1 or later.
make html (or just
make) to create a folder named html containing a
collection of HTML files.
To install FOP on Linux, run
sudo apt-get install -y fop
To install FOP on macOS using Homebrew, run
brew install fop
make pdf to create a PDF file suitable for printing on letter
make pdfA4 to create a PDF file suitable for printing on A4
Compiled HTML Help
You can only build Compiled HTML Help on Windows. In addition to the general requirements, building Compiled HTML Help requires HTML Help Workshop. To install HTML Help Workshop, visit https://go.microsoft.com/fwlink/?LinkId=14188 to download htmlhelp.exe, and then double-click htmlhelp.exe.
make htmlhelp to create a Compiled HTML Help (.chm) file.
Editing the Manual
DocBook is XML. When you write XML, remember to close tags. This is valid XML:
Adding an Opcode Entry
In general, an entry for a new opcode named
newopcodename will be an XML
file named newopcodename.xml containing
<refentry id="newopcodename"> <!-- More mark-up… --> </refentry>
To incorporate a new entry into the manual:
Add the entry as an entity in manual.xml. For example, if you put newopcodename.xml in the opcodes folder, add this entity to manual.xml:
<!ENTITY opcodesnewopcodename SYSTEM "opcodes/newopcodename.xml">
Use the entity to add your opcode entry to opcodes/top.xml. Opcode entries are arranged alphabetically, so just find where your opcode should be in the list and add:
Link to your opcode entry from an appropriate section of the manual. For example, if
newopcodenameshould be included with realtime spectral processing opcodes, add a
linkelement to spectral/realtime.xml, like this:
Repeat this step for each section in which you think your opcode should be included.
Optionally, use a
refentryinfoelement so your opcode will be properly categorized in the Quick Reference. Use one of the categories in categories.py. (If you omit a
refentryinfoelement, your opcode will be categorized as Miscellaneous.)
There are several targets that prepare files for release. Remember to update Csound’s version number in manual.xml and the Makefile so that files are generated with that number. It’s also a good idea to update the What's new… section for each release.