| blob | 0a0bdd5d24722f83591092353208ddf11e1842be |
1 title:: SCDoc Syntax
2 summary:: SCDoc markup language syntax
3 categories:: HelpSystem
4 related:: Guides/WritingHelp, Classes/SCDoc, Classes/SCDocHTMLRenderer
6 section:: Introduction
8 This document specifies the syntax and link::#Grammar:: of the link::Classes/SCDoc:: markup language, used in SuperCollider for writing documents with semantic annotations, in a manner which does not target a specific layout or output format.
10 A guide to writing help can be found here: link::Guides/WritingHelp::.
12 section:: Specification
13 SCDoc documents consists of tags and text.
15 Tags consists of single words ending with teletype::\:::: (double-colon). They are case-insensitive, so teletype::TITLE\::::, teletype::Title\:::: and teletype::title\:::: all mean the same thing.
16 Some tags take the remaining text on the same line, while others enclose the following text until a single end-tag (double-colon teletype::\::::). Some of these can be nested, while others are modal and ignores any tag until the end-tag.
18 Untagged text becomes plain prose. Paragraphs are separated by one or more empty lines.
20 A document has a header section and a body. The header has only header tags, and these tags are not allowed in the document body.
22 subsection:: Header tags
23 All header tags take the remaining line of text as input. There is no end-tag other than a newline.
25 definitionlist::
26 ## keyword:: title\::
27 teletype:: TITLE\:: :: name
28 || Title of document. Must equal classname for class reference docs. Example:
29 teletype::
30 title:: SCDoc
31 ::
33 ## keyword:: class\::
34 teletype:: CLASS\:: :: name
35 || Deprecated, use TITLE instead.
37 ## keyword:: categories\::
38 teletype:: CATEGORIES\:: :: list
39 || A comma-separated list of document categories. Mainly used by the link::Browse:: page.
41 Categories can be hierarchical, where levels are denoted with teletype::>::.
42 Example:
43 teletype::
44 categories:: External Control>OSC, Scheduling>Clocks
45 ::
47 ## keyword:: related\::
48 teletype:: RELATED\:: :: link(s)
49 || A comma-separated list of related docs. Example:
50 teletype::
51 related:: Classes/SCDoc, Reference/SCDocSyntax
52 ::
54 ## keyword:: summary\::
55 teletype:: SUMMARY\:: :: text
56 || A short summary of this document. Example:
57 teletype::
58 summary:: SCDoc markup language syntax
59 ::
61 ## keyword:: redirect\::
62 teletype:: REDIRECT\:: :: name
63 || For class redirect systems, specify the name of the instance variable holding the implementing class.
64 Example:
65 teletype::
66 redirect:: implClass
67 ::
68 ::
70 subsection:: Section tags
71 A document is divided in sections and subsections. The section body consists of everything following the section tag until there is another section tag with the same or higher level.
73 All kinds of sections automatically creates a link anchor with the same name as the section. Methods also creates an anchor, with the methodname prefixed with teletype::*:: for class methods and teletype::-:: for instance methods.
75 Structural tags at the same level in the hierarchy may be functionally equivalent, but treated differently for rendering or querying purposes. For example teletype::examples\:::: is equivalent to teletype::section\:::: but imply particular formatting or specially identify the examples section for customised uses like concatenating all examples for classes with a given parent class.
77 All structural tags has children elements, for example the items in a list or the subsections and prose in a section.
79 Level 1 (highest):
80 definitionlist::
81 ## keyword:: section\::
82 teletype:: SECTION\:: :: name
83 || A named section. The name should be plain text and can not contain any tags. Example:
84 teletype::
85 section:: Introduction
86 ::
87 ## keyword:: description\::
88 teletype:: DESCRIPTION\:: ::
89 ## keyword:: classmethods\::
90 teletype:: CLASSMETHODS\:: ::
91 ## keyword:: instancemethods\::
92 teletype:: INSTANCEMETHODS\:: ::
93 ## keyword:: examples\::
94 teletype:: EXAMPLES\:: ::
95 || These tags starts standard sections of a class reference. CLASSMETHODS and INSTANCEMETHODS have special meaning, in that they specify if a documented method is a classmethod or instancemethod.
96 ::
98 Level 2:
99 definitionlist::
100 ## keyword:: subsection\::
101 teletype:: SUBSECTION\:: :: name
102 || A named subsection. The name should be plain text and can not contain any tags. Example:
103 teletype::
104 subsection:: Some more info
105 ::
106 ::
108 subsection:: Method tags
109 These are level 3 subsections:
110 definitionlist::
111 ## keyword:: method\::
112 teletype:: METHOD\:: :: methodname(s) [argstring]
113 || Document one or more methods, given as a comma-separated list of methodnames.
115 note::
116 If multiple methods are documented as a group, the methods must have the same argument name signature for existing arguments. For example, grouping the following methods would be ok:
117 teletype::
118 foo (a, b)
119 bar (a, b, c)
120 zoo (a)
121 ::
122 But not:
123 teletype::
124 foo (a, x)
125 bar (a, b, c)
126 zoo (y)
127 ::
128 ::
130 Following the method tag should come a short description of the method, and optional description of the arguments and return value. See the link::#tags allowed inside a method:: section below.
132 SCDoc regards getter and setter methods as read/write interfaces for a single emphasis::property::. This means that you should not write the trailing underscore for setters. Instead, document it as a single property without the underscore, as if there was only a getter, and describe the property that can be set/gotten.
134 The METHOD tag is normally used inside CLASSMETHODS and INSTANCEMETHODS, but can also be used outside of these sections. In those cases, it documents a generic interface not bound to a specific class, and the arguments and default values should then be given in the optional strong::argstring::
136 For real methods, the argstring is not allowed, instead the argument names and default values will be auto-filled in.
138 ## keyword:: private\::
139 teletype:: PRIVATE\:: :: methodname(s)
140 || This tag behaves like a section but does not have a section body. It marks one or more methods as private, so that it does not show up under the auto-generated emphasis::Undocumented Methods:: sections.
141 ## keyword:: copymethod\::
142 teletype:: COPYMETHOD\:: :: classname methodname
143 || This tag behaves like a section but does not have a section body. Copy a method documentation from a class reference and insert it here as if the method was documented in this document. The methodname must be prefixed with teletype::*:: for classmethods and teletype::-:: for instancemethods. Example:
144 teletype::
145 copymethod:: SinOsc *ar
146 ::
147 ::
149 anchor::tags allowed inside a method::
150 Inside a method section, the following optional tags are allowed, in the order given below.
151 These tags are level 4 subsections.
152 definitionlist::
153 ## keyword:: argument\::
154 teletype:: ARGUMENT\:: :: [argname]
155 || One for each argument. The argument section body should contain a description of the given argument.
156 The strong::argname:: is optional, and will be auto-filled in if not given. If given, it must match the real name of the argument at this position.
158 If the method has varargs, the argname for the varargs (if given) should be prefixed with three dots and a space (teletype::"... "::)
159 ## keyword:: returns\::
160 teletype:: RETURNS\:: ::
161 || This section should contain a description of the return value, especially the type.
162 ## keyword:: discussion\::
163 teletype:: DISCUSSION\:: ::
164 || This optional section can contain a more detailed discussion and code examples related to this method.
165 ::
167 Example:
168 teletype::
169 method:: ar, kr
170 This is a nice method, try it out!
171 argument:: freq
172 The frequency of this thing as a floating point value.
173 argument:: amp
174 The amplitude, be careful. Goes to 11.
175 returns::
176 An UGen.
177 ::
179 subsection:: Modal tags
180 These tags enclose a text and ends with a single teletype::\:::: (double-colon) end-tag.
181 The enclosed text can not contain any other tags.
183 definitionlist::
184 ## keyword:: strong\::
185 teletype:: STRONG\:: ::
186 || Render text in bold font.
187 ## keyword:: emphasis\::
188 teletype:: EMPHASIS\:: ::
189 || Render text in emphasized font, typically italics.
190 ## keyword:: soft\::
191 teletype:: SOFT\:: ::
192 || Render text in a soft shade.
193 ## keyword:: link\::
194 teletype:: LINK\:: ::
195 || Create a link to another document. The text should be the document key, which is the path relative the Help folder and without extension, like teletype::Classes/SinOsc:: or teletype::Reference/SCDocSyntax::
197 Optionally, the path can be followed by teletype::#anchor:: to jump to a specific place in the document, and teletype::#label:: to specify another label for the link.
199 All kinds of sections automatically creates an anchor with the same name as the section. Methods also creates an anchor, with the methodname prefixed with teletype::*:: for class methods and teletype::-:: for instance methods.
201 The path can be empty for linking to an anchor inside the current document, and the anchor can be empty to only specify the link label. Example:
202 teletype::
203 See section link::#Introduction:: in this document.
204 Take a look at link::Classes/SCDoc#*indexAllDocuments::
205 Try link::Search#scdoc#Searching for SCDoc::,
206 or perhaps link::Classes/SinOsc##go make some music::
207 ::
209 URL's are automagically turned into links, but can be explicitly created with this tag, if one wants to use another link label.
211 ## keyword:: anchor\::
212 teletype:: ANCHOR\:: ::
213 || Manually create an anchor at this position in the document.
214 ## keyword:: image\::
215 teletype:: IMAGE\:: ::
216 || Insert image, the text should be the relative path to the image. Example:
217 teletype::
218 image::foo.png::
219 ::
220 ::
222 The following tags (CODE, TELETYPE and MATH) can be written in two forms, either inline or block.
223 strong::Inline:: form has the end-tag on the same line, and need any enclosed double-colons that should be part of the text to be escaped with backslash (teletype:: \ ::).
224 strong::Block:: form has the tag and end-tag on lines by themselves, and can take multi-line text. In block form, only a single end-tag on its own line counts and any end-tags inside the text should not be escaped (except if it's on a single line). Example:
225 teletype::
226 code:: inline form ::
228 code::
229 block form :: <- needs no escaping
230 can span multiple lines
231 \::
232 ::
234 definitionlist::
235 ## keyword:: code\::
236 teletype:: CODE\:: ::
237 || Render syntax-colored SuperCollider code.
238 ## keyword:: teletype\::
239 teletype:: TELETYPE\:: ::
240 || Render monospace text.
241 ## keyword:: math\::
242 teletype:: MATH\:: ::
243 || Render mathematics given in TeX syntax. Example:
244 teletype::
245 This is inline math::2\pi:: and below is block display math:
246 math::
247 1\over\sqrt{x^\pi}
248 \::
249 ::
250 Renders:
252 This is inline math::2\pi:: and below is block display math:
253 math::
254 1\over\sqrt{x^\pi}
255 ::
256 ::
258 subsection:: Lists and tables
259 List items, table rows and definition terms are denoted with teletype::##:: (double-hash).
260 Table cells and definition descriptions are denoted with teletype::||:: (double-bar).
261 Lists and tables can be nested, and ends with the end-tag.
262 definitionlist::
263 ## keyword:: table\::
264 teletype:: TABLE\:: ::
265 || Create a table. Example:
266 teletype::
267 table::
268 ## a 1 || a 2 || a 3
269 ## b 1 || b 2 || b 3
270 ## c 1 || c 2 || c 3
271 \::
272 ::
273 Renders:
274 table::
275 ## a 1 || a 2 || a 3
276 ## b 1 || b 2 || b 3
277 ## c 1 || c 2 || c 3
278 ::
280 ## keyword:: definitionlist\::
281 teletype:: DEFINITIONLIST\:: ::
282 || A definition list item consists of one or more terms prefixed with teletype::##:: followed by a description prefixed with teletype::||::. Example:
283 teletype::
284 definitionlist::
285 ## foo
286 ## bar
287 || Common dummy-variable names.
288 ## SuperCollider
289 || A very nice computer software.
290 \::
291 ::
292 ## keyword:: list\::
293 teletype:: LIST\:: ::
294 || Create a simple bulleted list. Items are prefixed with teletype::##::
295 ## keyword:: numberedlist\::
296 teletype:: NUMBEREDLIST\:: ::
297 || Create a numbered list. Items are prefixed with teletype::##::
298 ## keyword:: tree\::
299 teletype:: TREE\:: ::
300 || Create a tree structure. Typically nested with more TREE tags. Items are prefixed with teletype::##::
301 ::
303 subsection:: Notes and warnings
304 These can have other tags in them, and ends with the end-tag.
305 definitionlist::
306 ## keyword:: note\::
307 teletype:: NOTE\:: ::
308 || Create a NOTE box with important content.
309 note:: like this ::
310 ## keyword:: warning\::
311 teletype:: WARNING\:: ::
312 || Create a WARNING box with very important content.
313 warning:: like this ::
314 ## keyword:: footnote\::
315 teletype:: FOOTNOTE\:: ::
316 || Create a footnote which will be rendered at the end of the document.
317 At the position of the FOOTNOTE tag, the footnote number will be rendered with a link to the footnote.
318 Example:
319 teletype::
320 Hello I'm a geek footnote::
321 According to http://en.wikipedia.org/wiki/Geek the word geek is a slang term, with different
322 meanings ranging from "a computer expert or enthusiast" to "a carnival performer who performs
323 sensationally morbid or disgusting acts"
324 \::
325 ::
326 The result looks like this:
327 Hello I'm a geek footnote::
328 According to http://en.wikipedia.org/wiki/Geek the word geek is a slang term, with different meanings ranging from "a computer expert or enthusiast" to "a carnival performer who performs sensationally morbid or disgusting acts"
329 ::
331 ::
333 subsection:: Other tags
334 definitionlist::
335 ## keyword:: keyword\::
336 teletype:: KEYWORD\:: :: keyword(s)
337 || Specify one or more searchable keywords for this document.
338 An anchor named the keyword prefixed with teletype::kw_:: will be created at the position of this tag.
339 ## keyword:: classtree\::
340 teletype:: CLASSTREE\:: :: classname
341 || Render a class tree of subclasses starting from the given class.
342 ::
344 section:: Grammar
345 The following is an exact specification of the grammar:
346 teletype::
347 start ::= document
348 document ::= START_FULL dochead optsections
349 | START_PARTIAL sections
350 | START_METADATA dochead optsections
351 dochead ::= { headline } headline
352 headline ::= ( headtag words2 | "CATEGORIES::" commalist | "RELATED::"
353 commalist ) eol
354 headtag ::= "CLASS::"
355 | "TITLE::"
356 | "SUMMARY::"
357 | "REDIRECT::"
358 sectiontag ::= "CLASSMETHODS::"
359 | "INSTANCEMETHODS::"
360 | "DESCRIPTION::"
361 | "EXAMPLES::"
362 optsections ::= [ sections ]
363 sections ::= sections section
364 | section
365 | subsubsections
366 section ::= ( "SECTION::" words2 eol | sectiontag ) optsubsections
367 optsubsections ::= [ subsections ]
368 subsections ::= subsections subsection
369 | subsection
370 | subsubsections
371 subsection ::= "SUBSECTION::" words2 eol optsubsubsections
372 optsubsubsections ::= [ subsubsections ]
373 subsubsections ::= subsubsections subsubsection
374 | subsubsection
375 | body
376 subsubsection ::= "METHOD::" methnames optMETHODARGS eol methodbody
377 | "COPYMETHOD::" words eol
378 | "PRIVATE::" commalist eol
379 optMETHODARGS ::= [ METHODARGS ]
380 methnames ::= { METHODNAME COMMA } METHODNAME
381 methodbody ::= optbody optargs optreturns optdiscussion
382 optbody ::= [ body ]
383 optargs ::= [ args ]
384 args ::= { arg } arg
385 arg ::= "ARGUMENT::" ( words eol optbody | eol body )
386 optreturns ::= [ "RETURNS::" body ]
387 optdiscussion ::= [ "DISCUSSION::" body ]
388 body ::= blockA
389 | blockB
390 blockA ::= [ blockB | blockA ] bodyelem
391 blockB ::= [ blockA ] prose
392 bodyelem ::= rangetag body "::"
393 | listtag listbody "::"
394 | "TABLE::" tablebody "::"
395 | "DEFINITIONLIST::" deflistbody "::"
396 | blocktag wordsnl "::"
397 | "CLASSTREE::" words eol
398 | "KEYWORD::" commalist eol
399 | EMPTYLINES
400 | "IMAGE::" words2 "::"
401 prose ::= { proseelem } proseelem
402 proseelem ::= anyword
403 | URL
404 | inlinetag words "::"
405 | "FOOTNOTE::" body "::"
406 | NEWLINE
407 inlinetag ::= "LINK::"
408 | "STRONG::"
409 | "SOFT::"
410 | "EMPHASIS::"
411 | "CODE::"
412 | "TELETYPE::"
413 | "MATH::"
414 | "ANCHOR::"
415 blocktag ::= CODEBLOCK
416 | TELETYPEBLOCK
417 | MATHBLOCK
418 listtag ::= "LIST::"
419 | "TREE::"
420 | "NUMBEREDLIST::"
421 rangetag ::= "WARNING::"
422 | "NOTE::"
423 listbody ::= { "##" body } "##" body
424 tablerow ::= "##" tablecells
425 tablebody ::= { tablerow } tablerow
426 tablecells ::= { optbody "||" } optbody
427 defterms ::= { "##" body } "##" body
428 deflistrow ::= defterms "||" optbody
429 deflistbody ::= { deflistrow } deflistrow
430 anywordurl ::= anyword
431 | URL
432 anyword ::= TEXT
433 | COMMA
434 words ::= { anyword } anyword
435 words2 ::= { anywordurl } anywordurl
436 eol ::= NEWLINE
437 | EMPTYLINES
438 anywordnl ::= anyword
439 | eol
440 wordsnl ::= { anywordnl } anywordnl
441 nocommawords ::= nocommawords TEXT
442 | nocommawords URL
443 | TEXT
444 | URL
445 commalist ::= { nocommawords COMMA } nocommawords
446 ::