# 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.