Csound Reference Manual (English)
Python Makefile CSS
Switch branches/tags
Latest commit 319fe6e Nov 18, 2017 @fggp fggp Minor fix
Permalink
Failed to load latest commit information.
STKopcodes removed text about SCons and updated text to Csound6 Jun 24, 2015
command Minor fix Nov 12, 2017
control Added refs to while opcode Nov 6, 2014
csbeats initial Mar 13, 2013
cscore Missing files Mar 17, 2013
csound5 Added pages for inletv and outletv. May 1, 2016
deprecated work on loscilx page, and minir on sndloop Apr 21, 2015
examples Merge pull request #123 from ostinato/master Nov 17, 2017
experimental Added Note Releases and changed version number to 6.03 May 1, 2014
imageopcodes initial Mar 13, 2013
images trying to fix GENquadbezier Sep 29, 2016
math documenting a case known not to work Apr 23, 2017
midi added jack module t midi/top.xml Apr 16, 2016
misc Minor fix Nov 18, 2017
miscopcodes initial tidying Mar 15, 2013
opcodes Minor fix Nov 18, 2017
orch UDP server documentation Oct 16, 2017
oscnetwork Release Notes for 6.10 Sep 16, 2017
overview udp server Nov 9, 2017
pitch initial Mar 13, 2013
plugin initial Mar 13, 2013
preface Minor fixes Nov 17, 2017
score score d opcode Apr 15, 2017
scoregens GEN 53 man page and example Sep 7, 2017
siggen manual pages and examples for emugens and scugens Jan 30, 2017
sigio Websocket manual entry Jun 15, 2015
sigmod rename k35* May 10, 2017
spectral minor correction (link) Jun 24, 2015
strings Note on escaped sequences in multiline strings Nov 8, 2016
table initial Mar 13, 2013
utility Added ref to src_conv Sep 24, 2017
vectorial transformed emphasis tag to link Apr 18, 2015
xsl Make styles and colors match current online manual Jan 17, 2017
zak initial Mar 13, 2013
.gitignore manual pages and examples for emugens and scugens Jan 30, 2017
.travis.yml Try to install Pygments on Travis CI Jan 15, 2017
Makefile Release Notes for 6.10 Sep 16, 2017
README.md Rearrange information about Pygments requirement Aug 6, 2017
appveyor.yml Add appveyor.yml Aug 28, 2017
categories.py Documenting the Ableton Link opcodes. Jan 14, 2017
copying.txt Missing files Mar 17, 2013
csd2docbook.py Fixed bug in examples processing -- did not work on Windows. May 15, 2017
csound.css initial tidying Mar 15, 2013
makeframes.py Quick and dirty fix for frames manual Oct 3, 2013
manpages.xml dependencies May 1, 2016
manual.xml Update manual.xml Nov 17, 2017
opcodeparser.py initial tidying Mar 15, 2013
opcodes.xml Minor fixes Nov 17, 2017
quickref.py initial tidying Mar 15, 2013
syntax-highlighting.css Make styles and colors match current online manual Jan 17, 2017

README.md

The Csound Canonical Reference Manual

Build status

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.

General Requirements

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

On Linux

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'

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 in a Terminal.

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

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

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⟩

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.

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.