supercollider-common 1:3.8.0~repack-2 / usr / share / SuperCollider / HelpSource / Reference / SCDocSyntax.schelp

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