Csound Reference Manual (English)
Python Makefile CSS
Latest commit 32488eb Feb 25, 2017 @jpffitch jpffitch minor tidying
Permalink
Failed to load latest commit information.
STKopcodes removed text about SCons and updated text to Csound6 Jun 24, 2015
command Typo Nov 1, 2016
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 branch 'master' of https://github.com/csound/manual Jan 30, 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 Changed version number to 6.00.1, added release notes and activated F… Aug 6, 2013
midi added jack module t midi/top.xml Apr 16, 2016
misc minor tidying Feb 25, 2017
miscopcodes initial tidying Mar 15, 2013
opcodes minor tidying Feb 25, 2017
orch Extended documentation on comments too admit to // and c in scores Oct 19, 2016
oscnetwork Documenting the Ableton Link opcodes. Jan 14, 2017
overview checking Oct 27, 2016
pitch initial Mar 13, 2013
plugin initial Mar 13, 2013
preface Minor fix Nov 4, 2016
score Minor fixes Oct 22, 2016
scoregens Minor fixes Oct 22, 2016
siggen manual pages and examples for emugens and scugens Jan 30, 2017
sigio Websocket manual entry Jun 15, 2015
sigmod manual pages and examples for emugens and scugens Jan 30, 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 adjust interp for third optional arg Nov 26, 2015
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 Use of syntax-highlighting.css for all html type targets Jan 20, 2017
README.md added note about upgrading pygments if older version is found on system Jan 19, 2017
categories.py Documenting the Ableton Link opcodes. Jan 14, 2017
copying.txt Missing files Mar 17, 2013
csd2docbook.py manual pages and examples for emugens and scugens Jan 30, 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 Merge branch 'master' of https://github.com/csound/manual Jan 30, 2017
opcodeparser.py initial tidying Mar 15, 2013
opcodes.xml fixing stupid mistake Aug 7, 2015
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; and xsltproc.

On Linux

To install DocBook and xsltproc, run

sudo apt-get install -y docbook xsltproc

Python, with Pygments, 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.

Visit http://pygments.org/download/ to learn how to install Pygments.

On macOS

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

To install Pygments, enter in Terminal sudo easy_install pygments. If you have and older version of pygments installed, you might get an error message that CsoundDocumentLexer was not found. If so, you can updated your version of pygments using easy_install —upgrade pygments.

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

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.