464 lines
17 KiB
Text
464 lines
17 KiB
Text
|
title:: SCDoc Syntax
|
||
|
|
summary:: SCDoc markup language syntax
|
||
|
|
categories:: HelpSystem
|
||
|
|
related:: Guides/WritingHelp, Classes/SCDoc, Classes/SCDocHTMLRenderer
|
||
|
|
|
||
|
|
section:: Introduction
|
||
|
|
|
||
|
|
This document specifies the syntax and link::#Grammar:: of the link::Classes/SCDoc:: markup language.
|
||
|
|
code::SCDoc Markup:: is used in SuperCollider mainly for helpfiles.
|
||
|
|
It is a syntax that features semantic a semantic level specific to the requirements of SuperCollider.
|
||
|
|
|
||
|
|
note::A guide to writing help can be found at link::Guides/WritingHelp::.::
|
||
|
|
|
||
|
|
section:: Specification
|
||
|
|
|
||
|
|
A document is split into a header section and a body. The header contains only header tags, which are not allowed in the document body.
|
||
|
|
|
||
|
|
SCDoc documents consist of EMPHASIS::tags:: and EMPHASIS::text::.
|
||
|
|
|
||
|
|
|
||
|
|
list::
|
||
|
|
## Tags consists of single words ending with teletype::\:::: (double-colon).
|
||
|
|
## Untagged text becomes plain prose.
|
||
|
|
## Paragraphs are separated by one or more empty lines.
|
||
|
|
## Tags are case-insensitive: teletype::TITLE\::::, teletype::Title\:::: and teletype::title\:::: are interepreted equally.
|
||
|
|
## Some tags take the remaining text on the same line as their argument
|
||
|
|
## Some tags enclose the following text until a single end-tag (double-colon teletype::\::::).
|
||
|
|
## Some enclosing tags can be nested, while others are modal and ignore any tag until an end-tag.
|
||
|
|
::
|
||
|
|
|
||
|
|
|
||
|
|
subsection:: Header tags
|
||
|
|
Header tags take the remaining text in their definition line as their argument.
|
||
|
|
They expect no end-tag.
|
||
|
|
|
||
|
|
definitionlist::
|
||
|
|
## keyword:: title\::
|
||
|
|
teletype:: TITLE\:: :: name
|
||
|
|
|| Title of the document. For class reference documents, this must be the same as the classname.
|
||
|
|
|
||
|
|
teletype::
|
||
|
|
title:: SCDoc
|
||
|
|
::
|
||
|
|
|
||
|
|
## keyword:: categories\::
|
||
|
|
teletype:: CATEGORIES\:: :: list
|
||
|
|
|| A comma-separated list of document categories. Mainly used by the link::Browse:: page.
|
||
|
|
|
||
|
|
Categories can be hierarchical, where levels are denoted with teletype::>::.
|
||
|
|
|
||
|
|
teletype::
|
||
|
|
categories:: External Control>OSC, Scheduling>Clocks
|
||
|
|
::
|
||
|
|
|
||
|
|
## keyword:: related\::
|
||
|
|
teletype:: RELATED\:: :: link(s)
|
||
|
|
|| A comma-separated list of related docs.
|
||
|
|
|
||
|
|
teletype::
|
||
|
|
related:: Classes/SCDoc, Reference/SCDocSyntax
|
||
|
|
::
|
||
|
|
|
||
|
|
## keyword:: summary\::
|
||
|
|
teletype:: SUMMARY\:: :: text
|
||
|
|
|| A short summary of this document.
|
||
|
|
|
||
|
|
teletype::
|
||
|
|
summary:: SCDoc markup language syntax
|
||
|
|
::
|
||
|
|
|
||
|
|
## keyword:: redirect\::
|
||
|
|
teletype:: REDIRECT\:: :: name
|
||
|
|
|| For class redirect systems, specify the name of the instance variable holding the implementing class.
|
||
|
|
Example:
|
||
|
|
teletype::
|
||
|
|
redirect:: implClass
|
||
|
|
::
|
||
|
|
|
||
|
|
## keyword:: class\::
|
||
|
|
teletype:: CLASS\:: :: name
|
||
|
|
|| Deprecated, use TITLE instead.
|
||
|
|
::
|
||
|
|
|
||
|
|
subsection:: Section tags
|
||
|
|
A document can be divided into sections and subsections. Section bodies consist of everything that follows its section tag until another section tag of same or higher level.
|
||
|
|
|
||
|
|
Sections have a link anchor with the same name as the section.
|
||
|
|
note::Method tags also create such anchors. The methodname then is prefixed with teletype::*:: (class methods) or teletype::-:: (instance methods).::
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
Structural tags can have child elements, for example the items in a list or the subsections and prose in a section.
|
||
|
|
|
||
|
|
Level 1 (highest):
|
||
|
|
definitionlist::
|
||
|
|
## keyword:: section\::
|
||
|
|
teletype:: SECTION\:: :: name
|
||
|
|
|| A named section. The name should be plain text and can not contain any tags.
|
||
|
|
|
||
|
|
teletype::
|
||
|
|
section:: Introduction
|
||
|
|
::
|
||
|
|
## keyword:: description\::
|
||
|
|
teletype:: DESCRIPTION\:: ::
|
||
|
|
## keyword:: classmethods\::
|
||
|
|
teletype:: CLASSMETHODS\:: ::
|
||
|
|
## keyword:: instancemethods\::
|
||
|
|
teletype:: INSTANCEMETHODS\:: ::
|
||
|
|
## keyword:: examples\::
|
||
|
|
teletype:: EXAMPLES\:: ::
|
||
|
|
|| 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.
|
||
|
|
::
|
||
|
|
|
||
|
|
Level 2:
|
||
|
|
definitionlist::
|
||
|
|
## keyword:: subsection\::
|
||
|
|
teletype:: SUBSECTION\:: :: name
|
||
|
|
|| A named subsection. The name should be plain text and can not contain any tags. Example:
|
||
|
|
teletype::
|
||
|
|
subsection:: Some more info
|
||
|
|
::
|
||
|
|
::
|
||
|
|
|
||
|
|
subsection:: Method tags
|
||
|
|
These are level 3 subsections:
|
||
|
|
definitionlist::
|
||
|
|
## keyword:: method\::
|
||
|
|
teletype:: METHOD\:: :: methodname(s) [argstring]
|
||
|
|
|| Document one or more methods, given as a comma-separated list of methodnames.
|
||
|
|
|
||
|
|
note::
|
||
|
|
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:
|
||
|
|
teletype::
|
||
|
|
foo (a, b)
|
||
|
|
bar (a, b, c)
|
||
|
|
zoo (a)
|
||
|
|
::
|
||
|
|
But not:
|
||
|
|
teletype::
|
||
|
|
foo (a, x)
|
||
|
|
bar (a, b, c)
|
||
|
|
zoo (y)
|
||
|
|
::
|
||
|
|
::
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
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::
|
||
|
|
|
||
|
|
For real methods, the argstring is not allowed, instead the argument names and default values will be auto-filled in.
|
||
|
|
|
||
|
|
## keyword:: private\::
|
||
|
|
teletype:: PRIVATE\:: :: methodname(s)
|
||
|
|
|| 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. Expects a comma-separated list of methodnames.
|
||
|
|
## keyword:: copymethod\::
|
||
|
|
teletype:: COPYMETHOD\:: :: classname methodname
|
||
|
|
|| 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.
|
||
|
|
|
||
|
|
teletype::
|
||
|
|
copymethod:: SinOsc *ar
|
||
|
|
::
|
||
|
|
::
|
||
|
|
|
||
|
|
anchor::tags allowed inside a method::
|
||
|
|
Inside a method section, the following optional tags are allowed, in the order given below.
|
||
|
|
These tags are level 4 subsections.
|
||
|
|
definitionlist::
|
||
|
|
## keyword:: argument\::
|
||
|
|
teletype:: ARGUMENT\:: :: [argname]
|
||
|
|
|| One for each argument. The argument section body should contain a description of the given argument.
|
||
|
|
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.
|
||
|
|
|
||
|
|
If the method has varargs, the argname for the varargs (if given) should be prefixed with three dots and a space (teletype::"... "::)
|
||
|
|
## keyword:: returns\::
|
||
|
|
teletype:: RETURNS\:: ::
|
||
|
|
|| This section should contain a description of the return value, especially the type.
|
||
|
|
## keyword:: discussion\::
|
||
|
|
teletype:: DISCUSSION\:: ::
|
||
|
|
|| This optional section can contain a more detailed discussion and code examples related to this method.
|
||
|
|
::
|
||
|
|
|
||
|
|
|
||
|
|
teletype::
|
||
|
|
method:: ar, kr
|
||
|
|
This is a nice method, try it out!
|
||
|
|
argument:: freq
|
||
|
|
The frequency of this thing as a floating point value.
|
||
|
|
argument:: amp
|
||
|
|
The amplitude, be careful. Goes to 11.
|
||
|
|
returns::
|
||
|
|
An UGen.
|
||
|
|
::
|
||
|
|
|
||
|
|
subsection:: Modal tags
|
||
|
|
These tags enclose a text and ends with a single teletype::\:::: (double-colon) end-tag.
|
||
|
|
The enclosed text can not contain any other tags.
|
||
|
|
|
||
|
|
definitionlist::
|
||
|
|
## keyword:: strong\::
|
||
|
|
teletype:: STRONG\:: ::
|
||
|
|
|| Render text in bold font.
|
||
|
|
## keyword:: emphasis\::
|
||
|
|
teletype:: EMPHASIS\:: ::
|
||
|
|
|| Render text in emphasized font, typically italics.
|
||
|
|
## keyword:: soft\::
|
||
|
|
teletype:: SOFT\:: ::
|
||
|
|
|| Render text in a soft shade.
|
||
|
|
## keyword:: link\::
|
||
|
|
teletype:: LINK\:: ::
|
||
|
|
|| 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::
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
teletype::
|
||
|
|
See section link::#Introduction:: in this document.
|
||
|
|
Take a look at link::Classes/SCDoc#*indexAllDocuments::
|
||
|
|
Try link::Search#scdoc#Searching for SCDoc::,
|
||
|
|
or perhaps link::Classes/SinOsc##go make some music::
|
||
|
|
::
|
||
|
|
|
||
|
|
URL's are automagically turned into links, but can be explicitly created with this tag, if one wants to use another link label.
|
||
|
|
|
||
|
|
## keyword:: anchor\::
|
||
|
|
teletype:: ANCHOR\:: ::
|
||
|
|
|| Manually create an anchor at this position in the document.
|
||
|
|
## keyword:: image\::
|
||
|
|
teletype:: IMAGE\:: ::
|
||
|
|
|| Insert image, the text should be the relative path to the image.
|
||
|
|
|
||
|
|
teletype::
|
||
|
|
image::foo.png::
|
||
|
|
::
|
||
|
|
Optionally an image caption can be given:
|
||
|
|
teletype::
|
||
|
|
image::foo.png#Figure 1::
|
||
|
|
::
|
||
|
|
|
||
|
|
And, the image can be clickable and link to another page:
|
||
|
|
teletype::
|
||
|
|
image::foo.png#click this image#Classes/SinOsc::
|
||
|
|
::
|
||
|
|
|
||
|
|
Just leave the caption empty if you want a link but no caption.
|
||
|
|
|
||
|
|
::
|
||
|
|
|
||
|
|
The following tags (CODE and TELETYPE) can be written in two forms, either inline or block.
|
||
|
|
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:: \ ::).
|
||
|
|
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).
|
||
|
|
|
||
|
|
teletype::
|
||
|
|
code:: inline form ::
|
||
|
|
|
||
|
|
code::
|
||
|
|
block form :: <- needs no escaping
|
||
|
|
can span multiple lines
|
||
|
|
\::
|
||
|
|
::
|
||
|
|
|
||
|
|
definitionlist::
|
||
|
|
## keyword:: code\::
|
||
|
|
teletype:: CODE\:: ::
|
||
|
|
|| Render syntax-colored SuperCollider code.
|
||
|
|
## keyword:: teletype\::
|
||
|
|
teletype:: TELETYPE\:: ::
|
||
|
|
|| Render monospace text.
|
||
|
|
::
|
||
|
|
|
||
|
|
subsection:: Lists and tables
|
||
|
|
List items, table rows and definition terms are denoted with teletype::##:: (double-hash).
|
||
|
|
Table cells and definition descriptions are denoted with teletype::||:: (double-bar).
|
||
|
|
Lists and tables can be nested, and ends with the end-tag.
|
||
|
|
definitionlist::
|
||
|
|
## keyword:: table\::
|
||
|
|
teletype:: TABLE\:: ::
|
||
|
|
|| Create a table. Example:
|
||
|
|
teletype::
|
||
|
|
table::
|
||
|
|
## a 1 || a 2 || a 3
|
||
|
|
## b 1 || b 2 || b 3
|
||
|
|
## c 1 || c 2 || c 3
|
||
|
|
\::
|
||
|
|
::
|
||
|
|
Renders:
|
||
|
|
table::
|
||
|
|
## a 1 || a 2 || a 3
|
||
|
|
## b 1 || b 2 || b 3
|
||
|
|
## c 1 || c 2 || c 3
|
||
|
|
::
|
||
|
|
|
||
|
|
## keyword:: definitionlist\::
|
||
|
|
teletype:: DEFINITIONLIST\:: ::
|
||
|
|
|| A definition list item consists of one or more terms prefixed with teletype::##:: followed by a description prefixed with teletype::||::. Example:
|
||
|
|
teletype::
|
||
|
|
definitionlist::
|
||
|
|
## foo
|
||
|
|
## bar
|
||
|
|
|| Common dummy-variable names.
|
||
|
|
## SuperCollider
|
||
|
|
|| A very nice computer software.
|
||
|
|
\::
|
||
|
|
::
|
||
|
|
## keyword:: list\::
|
||
|
|
teletype:: LIST\:: ::
|
||
|
|
|| Create a simple bulleted list. Items are prefixed with teletype::##::
|
||
|
|
## keyword:: numberedlist\::
|
||
|
|
teletype:: NUMBEREDLIST\:: ::
|
||
|
|
|| Create a numbered list. Items are prefixed with teletype::##::
|
||
|
|
## keyword:: tree\::
|
||
|
|
teletype:: TREE\:: ::
|
||
|
|
|| Create a tree structure. Typically nested with more TREE tags. Items are prefixed with teletype::##::
|
||
|
|
::
|
||
|
|
|
||
|
|
subsection:: Notes and warnings
|
||
|
|
These can have other tags in them, and ends with the end-tag.
|
||
|
|
definitionlist::
|
||
|
|
## keyword:: note\::
|
||
|
|
teletype:: NOTE\:: ::
|
||
|
|
|| Create a NOTE box with important content.
|
||
|
|
note:: like this ::
|
||
|
|
## keyword:: warning\::
|
||
|
|
teletype:: WARNING\:: ::
|
||
|
|
|| Create a WARNING box with very important content.
|
||
|
|
warning:: like this ::
|
||
|
|
## keyword:: footnote\::
|
||
|
|
teletype:: FOOTNOTE\:: ::
|
||
|
|
|| Create a footnote which will be rendered at the end of the document.
|
||
|
|
At the position of the FOOTNOTE tag, the footnote number will be rendered with a link to the footnote.
|
||
|
|
Example:
|
||
|
|
teletype::
|
||
|
|
Hello I'm a geek footnote::
|
||
|
|
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"
|
||
|
|
\::
|
||
|
|
::
|
||
|
|
The result looks like this:
|
||
|
|
Hello I'm a geek footnote::
|
||
|
|
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"
|
||
|
|
::
|
||
|
|
|
||
|
|
::
|
||
|
|
|
||
|
|
subsection:: Other tags
|
||
|
|
definitionlist::
|
||
|
|
## keyword:: keyword\::
|
||
|
|
teletype:: KEYWORD\:: :: keyword(s)
|
||
|
|
|| Specify one or more searchable keywords for this document.
|
||
|
|
An anchor named the keyword prefixed with teletype::kw_:: will be created at the position of this tag.
|
||
|
|
## keyword:: classtree\::
|
||
|
|
teletype:: CLASSTREE\:: :: classname
|
||
|
|
|| Render a class tree of subclasses starting from the given class.
|
||
|
|
::
|
||
|
|
|
||
|
|
section:: Grammar
|
||
|
|
The following is an exact specification of the grammar:
|
||
|
|
teletype::
|
||
|
|
start ::= document
|
||
|
|
document ::= START_FULL dochead optsections
|
||
|
|
| START_PARTIAL sections
|
||
|
|
| START_METADATA dochead optsections
|
||
|
|
dochead ::= { headline } headline
|
||
|
|
headline ::= ( headtag words2 | "CATEGORIES::" commalist | "RELATED::"
|
||
|
|
commalist ) eol
|
||
|
|
headtag ::= "CLASS::"
|
||
|
|
| "TITLE::"
|
||
|
|
| "SUMMARY::"
|
||
|
|
| "REDIRECT::"
|
||
|
|
sectiontag ::= "CLASSMETHODS::"
|
||
|
|
| "INSTANCEMETHODS::"
|
||
|
|
| "DESCRIPTION::"
|
||
|
|
| "EXAMPLES::"
|
||
|
|
optsections ::= [ sections ]
|
||
|
|
sections ::= sections section
|
||
|
|
| section
|
||
|
|
| subsubsections
|
||
|
|
section ::= ( "SECTION::" words2 eol | sectiontag ) optsubsections
|
||
|
|
optsubsections ::= [ subsections ]
|
||
|
|
subsections ::= subsections subsection
|
||
|
|
| subsection
|
||
|
|
| subsubsections
|
||
|
|
subsection ::= "SUBSECTION::" words2 eol optsubsubsections
|
||
|
|
optsubsubsections ::= [ subsubsections ]
|
||
|
|
subsubsections ::= subsubsections subsubsection
|
||
|
|
| subsubsection
|
||
|
|
| body
|
||
|
|
subsubsection ::= "METHOD::" methnames optMETHODARGS eol methodbody
|
||
|
|
| "COPYMETHOD::" words eol
|
||
|
|
| "PRIVATE::" commalist eol
|
||
|
|
optMETHODARGS ::= [ METHODARGS ]
|
||
|
|
methnames ::= { METHODNAME COMMA } METHODNAME
|
||
|
|
methodbody ::= optbody optargs optreturns optdiscussion
|
||
|
|
optbody ::= [ body ]
|
||
|
|
optargs ::= [ args ]
|
||
|
|
args ::= { arg } arg
|
||
|
|
arg ::= "ARGUMENT::" ( words eol optbody | eol body )
|
||
|
|
optreturns ::= [ "RETURNS::" body ]
|
||
|
|
optdiscussion ::= [ "DISCUSSION::" body ]
|
||
|
|
body ::= blockA
|
||
|
|
| blockB
|
||
|
|
blockA ::= [ blockB | blockA ] bodyelem
|
||
|
|
blockB ::= [ blockA ] prose
|
||
|
|
bodyelem ::= rangetag body "::"
|
||
|
|
| listtag listbody "::"
|
||
|
|
| "TABLE::" tablebody "::"
|
||
|
|
| "DEFINITIONLIST::" deflistbody "::"
|
||
|
|
| blocktag wordsnl "::"
|
||
|
|
| "CLASSTREE::" words eol
|
||
|
|
| "KEYWORD::" commalist eol
|
||
|
|
| EMPTYLINES
|
||
|
|
| "IMAGE::" words2 "::"
|
||
|
|
prose ::= { proseelem } proseelem
|
||
|
|
proseelem ::= anyword
|
||
|
|
| URL
|
||
|
|
| inlinetag words "::"
|
||
|
|
| "FOOTNOTE::" body "::"
|
||
|
|
| NEWLINE
|
||
|
|
inlinetag ::= "LINK::"
|
||
|
|
| "STRONG::"
|
||
|
|
| "SOFT::"
|
||
|
|
| "EMPHASIS::"
|
||
|
|
| "CODE::"
|
||
|
|
| "TELETYPE::"
|
||
|
|
| "ANCHOR::"
|
||
|
|
blocktag ::= CODEBLOCK
|
||
|
|
| TELETYPEBLOCK
|
||
|
|
listtag ::= "LIST::"
|
||
|
|
| "TREE::"
|
||
|
|
| "NUMBEREDLIST::"
|
||
|
|
rangetag ::= "WARNING::"
|
||
|
|
| "NOTE::"
|
||
|
|
listbody ::= { "##" body } "##" body
|
||
|
|
tablerow ::= "##" tablecells
|
||
|
|
tablebody ::= { tablerow } tablerow
|
||
|
|
tablecells ::= { optbody "||" } optbody
|
||
|
|
defterms ::= { "##" body } "##" body
|
||
|
|
deflistrow ::= defterms "||" optbody
|
||
|
|
deflistbody ::= { deflistrow } deflistrow
|
||
|
|
anywordurl ::= anyword
|
||
|
|
| URL
|
||
|
|
anyword ::= TEXT
|
||
|
|
| COMMA
|
||
|
|
words ::= { anyword } anyword
|
||
|
|
words2 ::= { anywordurl } anywordurl
|
||
|
|
eol ::= NEWLINE
|
||
|
|
| EMPTYLINES
|
||
|
|
anywordnl ::= anyword
|
||
|
|
| eol
|
||
|
|
wordsnl ::= { anywordnl } anywordnl
|
||
|
|
nocommawords ::= nocommawords TEXT
|
||
|
|
| nocommawords URL
|
||
|
|
| TEXT
|
||
|
|
| URL
|
||
|
|
commalist ::= { nocommawords COMMA } nocommawords
|
||
|
|
::
|
||
|
|
|