# The Csound Canonical Reference Manual
[![Build status](https://travis-ci.org/csound/manual.svg?branch=master)](https://travis-ci.org/csound/manual)
The Csound Reference Manual is written using
[DocBook](http://tdg.docbook.org/tdg/4.5/docbook.html) v4. To learn about
DocBook, visit [docbook.org](http://docbook.org).
If you find problems or have suggestions, [open an
issue](https://github.com/csound/manual/issues), or [fork this repository and
make a pull request](https://guides.github.com/activities/forking/).
## General Requirements
In addition to other requirements specific to what you’re building, you need
DocBook; [Python](https://www.python.org), with [Pygments](http://pygments.org)
v2.1 or later; and [xsltproc](http://xmlsoft.org/XSLT/xsltproc2.html).
### On Linux
To install DocBook and xsltproc, run
```sh
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
```sh
sudo pip install 'pygments>=2.1'
```
or, if you don’t have [pip](https://pip.pypa.io/),
```sh
sudo easy_install 'pygments>=2.1'
```
### On macOS
The easiest way to install DocBook is probably through
[Homebrew](https://brew.sh). To install Homebrew, follow the instructions at
https://brew.sh. Then, enter `brew install docbook` in a Terminal, followed by `brew install dockbook-xsl`, to install the DocBook XSL stylesheets.
To install Pygments v2.1 or later, enter in Terminal
```sh
sudo easy_install 'pygments>=2.1'
```
Python and xsltproc are preinstalled on macOS.
### On Windows
The easiest way to install DocBook is probably through
[Cygwin](https://www.cygwin.com). 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
```sh
make XSL_BASE_PATH=path/to/docbook/stylesheets ⟨target⟩
```
instead of `make ⟨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](#general-requirements).
### 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](#general-requirements), building PDF
files requires [Apache FOP](https://xmlgraphics.apache.org/fop/). You may also
need to download and install a [Java Runtime
Environment](http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html).
To install FOP on Linux, run
```sh
sudo apt-get install -y fop
```
To install FOP on macOS using [Homebrew](https://brew.sh), run
```sh
brew install fop
```
Run `make pdf` to create a PDF file suitable for printing on [letter
paper](https://en.wikipedia.org/wiki/Letter_(paper_size)).
Run `make pdfA4` to create a PDF file suitable for printing on [A4
paper](https://en.wikipedia.org/wiki/ISO_216#A_series).
### Compiled HTML Help
You can only build [Compiled HTML
Help](https://en.wikipedia.org/wiki/Microsoft_Compiled_HTML_Help) on Windows. In
addition to the [general requirements](#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](https://en.wikipedia.org/wiki/XML). When you write XML,
remember to close tags. This is valid XML:
```xml
text
```
This isn’t:
```xml
text
```
DocBook v4 has a [document type definition
(DTD)](http://docbook.org/xml/4.5/) that describes valid DocBook elements and
attributes. See [_DocBook: The Definitive
Guide_](http://tdg.docbook.org/tdg/4.5/docbook.html) 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
```xml
```
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](opcodes). You can also
use [opcodes/templates.xml](opcodes/template.xml) as a starting point.
To incorporate a new entry into the manual:
1. Add the entry as an entity in [manual.xml](manual.xml). For example, if you
put newopcodename.xml in the opcodes folder, add this entity to manual.xml:
```xml
```
2. Use the entity to add your opcode entry to
[opcodes/top.xml](opcodes/top.xml). Opcode entries are arranged alphabetically,
so just find where your opcode should be in the list and add:
```xml
&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](http://tdg.docbook.org/tdg/4.5/link.html) to
[spectral/realtime.xml](spectral/realtime.xml), like this:
```xml
newopcodename
```
Repeat this step for each section in which you think your opcode should be
included.
4. Optionally, use a [`refentryinfo`
element](https://github.com/csound/manual/search?q=refentryinfo+path%3Aopcodes+filename%3Atemplate.xml)
so your opcode will be properly categorized in the [Quick
Reference](https://csound.github.io/docs/manual/MiscQuickref.html). Use one of
the categories in [categories.py](categories.py). (If you omit a `refentryinfo`
element, your opcode will be categorized as
[Miscellaneous](https://github.com/csound/manual/search?q=Miscellaneous+filename%3Acategories.py).)
5. If possible, add a [`link` element](http://tdg.docbook.org/tdg/4.5/link.html)
to your opcode in the appropriate section of the [Opcodes
Overview](https://csound.github.io/docs/manual/PartOpcodesOverview.html).
## For Maintainers
There are several targets that prepare files for release. Remember to update
Csound’s version number in
[manual.xml](https://github.com/csound/manual/search?q=csoundversion+filename%3Amanual.xml)
and the
[Makefile](https://github.com/csound/manual/search?q=VERSION+filename%3AMakefile)
so that files are generated with that number. It’s also a good idea to update
the [What's new…](preface/whatsnew.xml) section for each release.