The Csound Canonical Reference Manual

The Csound Reference Manual is written using DocBook v4. To learn about DocBook, visit docbook.org.

If you find problems or have suggestions, open an issue, or fork this repository and make a pull request.

Specific Instructions for the Csound Manual

The instructions in the following sections pertain to DocBook generally, not to the Csound manual in particular. To build the Csound manual from source, you will need to adapt the general instructions. Specifically, after making sure that you have installed the necessary tooling and dependencies (as discussed in the following sections), you will need to get the source files for the Csound manual and then run make to generate a version of the manual from those source files. The source files include a Makefile that you may need to adapt to your configuration.

If you have installed Csound in ~/csound/csound and would like to (1) install the Csound manual source in ~/csound/manual and (2) build an html version in ~/csound/manual/html, do the following:

$ cd ~/csound
$ git clone https://github.com/csound/manual.git manual
$ cd manual
$ make html # This assumes that the Makefile will work. If it doesn't, you wll need to edit it and re-run this line.

Note: if you are on Ubuntu, the Makefile will probably not work, because it calls Python with python and not python3. You will need to either (1) edit the Makefile so that you call python3 (the executable name for Python on Ubuntu) or (2) install something like python-is-python3, a convenience package for Debian and Ubuntu that creates a symlink from python to python3.

If you followed the above instructions, you will be able to open the manual locally in any web browser with a link like file:///home/(username)/csound/manual/html/index.html.

General Instructions for Docbook and Related Programs

In addition to other requirements specific to what you’re building, you need DocBook; Python, with Pygments v2.3 or later; and xsltproc.

On Linux

To install DocBook, the required stylesheets, and xsltproc on a Debian-based system (including Ubuntu), run

sudo apt-get install -y docbook docbook-xsl xsltproc

Python is preinstalled on most Linux distributions. If you don’t have Python, visit https://www.python.org/downloads/ to find instructions for installing Python or building it from source.

To install Pygments v2.3 or later, run

sudo pip install 'pygments>=2.3'

or, if you don’t have pip,

sudo easy_install 'pygments>=2.3'

On macOS

The easiest way to install DocBook is probably through Homebrew. To install Homebrew, follow the instructions at https://brew.sh. Then, enter brew install docbook docbook-xsl in a Terminal.

To install Pygments v2.3 or later, enter in Terminal

sudo easy_install 'pygments>=2.3'

Python and xsltproc are preinstalled on macOS.

On Windows

The easiest way to install DocBook is probably through Cygwin. To install Cygwin, visit https://www.cygwin.com and download and run an installer for the latest release of Cygwin.

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.

Building

Run make ⟨target⟩ to build a ⟨target⟩. For example, to build a collection of HTML webpages, run make html.

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 XSL stylesheets, run

make XSL_BASE_PATH=path/to/docbook/stylesheets ⟨target⟩

instead of make ⟨target⟩. For example, on macOS run

make XSL_BASE_PATH="$(brew --prefix docbook-xsl)/docbook-xsl" ⟨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.3 or later.

HTML

Run make html (or just make) to create a folder named html containing a collection of HTML files.

PDF

In addition to the general requirements, building PDF files requires Apache FOP. You may also need to download and install a Java Runtime Environment.

To install FOP on Linux, run

sudo apt-get install -y fop

To install FOP on macOS using Homebrew, run

brew install fop

Run make pdf to create a PDF file suitable for printing on letter paper.

Run make pdfA4 to create a PDF file suitable for printing on A4 paper.

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.

Run 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:

<para>text</para>

This isn’t:

<para>text</ERROR>

DocBook v4 has a document type definition (DTD) that describes valid DocBook elements and attributes. See DocBook: The Definitive Guide to learn more.

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>

One way to get started documenting your opcode is to use an existing entry as a template. All opcode entries are in the opcodes folder. You can also use opcodes/templates.xml as a starting point.

To incorporate a new entry into the manual:

1. 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">

2. 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:

   &opcodesnewopcodename;

3. Link to your opcode entry from an appropriate section of the manual. For example, if newopcodename should be included with realtime spectral processing opcodes, add a link element to spectral/realtime.xml, like this:

   <link linkend="newopcodename"><citetitle>newopcodename</citetitle></link>

   Repeat this step for each section in which you think your opcode should be included.

4. Optionally, use a refentryinfo element so your opcode will be properly categorized in the Quick Reference. Use one of the categories in categories.py. (If you omit a refentryinfo element, your opcode will be categorized as Miscellaneous.)

5. If possible, add a link element to your opcode in the appropriate section of the Opcodes Overview.

For Maintainers

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.