1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
|
# The Csound Canonical Reference Manual
[](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
<para>text</para>
```
This isn’t:
```xml
<para>text</ERROR>
```
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
<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](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
<!ENTITY opcodesnewopcodename SYSTEM "opcodes/newopcodename.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
<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](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.
|
