HelpSource/Reference/SCDocSyntax.schelp

   1 title:: SCDocSyntax
   2 summary:: SCDoc markup language syntax
   3 categories:: HelpSystem
   4 related:: Guides/WritingHelp, Classes/SCDoc, Classes/SCDocParser, Classes/SCDocRenderer
   5
   6 This ML consists of a specification for writing documents with semantic annotations, in a manner which does not target a specific layout or output format. Its purpose is to allow for human-writable documents to be produced in a variety of formats and for a variety of target platforms. Usability and learnability are paramount, so the syntax is as simple as possible.
   7
   8 A guide to writing help can be found here: link::Guides/WritingHelp::.
   9
  10 section::Markup Language Syntax
  11
  12 Documents consist of tags and text. Some tags associate text with them, some just denotes a structural location in the document. Untagged text is treated as 'normal prose'.
  13
  14 Tags are of two types, single-line tags and range tags, indicated using code::keyword\::::
  15
  16 Tags are case insensitive, code::FooBar\:::: is the same as code::foobar\:::: or code::FOOBAR\::::
  17
  18 Some tags might only be meaningful after other tags, like code::argument\:::: after code::method\::::
  19
  20 Single-line tags are specified like so, and terminated with a newline. They can have a text associated with the tag:
  21 code::
  22 foo:: some text associated with this tag
  23 bar::
  24 This is "normal prose" and the above tag just denotes a section or location in the document.
  25 ::
  26
  27 Single-line tags that don't associate with text will treat any text starting on the same line after the tag as normal prose:
  28 code::
  29 bar:: This is also "normal prose" as above, since this particular tag doesn't take any text.
  30 ::
  31
  32 Any untagged text following the newline will be treated as normal prose. For example:
  33 code::
  34 title:: This text will be treated as a 'title'.
  35 This is 'normal prose' since it's untagged.
  36 section:: This text is a section title
  37 This is also normal prose.
  38 ::
  39
  40 Some single-line tags, e.g. code::related\:::: and code::summary\:::: can be understood as floating, i.e. the renderer will decide how and where to place them. Some tags are not even actually rendered to the output but only provides document metadata, e.g. code::categories\::::.
  41
  42 Range tags consist of an opening tag and a closing tag. They can be written as a block:
  43 code::
  44 variableTag::
  45 Some text of a
  46 variable line tag
  47 \::
  48 ::
  49 They can also occur on the same line inside normal prose:
  50 code::
  51 This is some normal prose containing a code::inline code example::.
  52 Also see link::Foo:: for more information.
  53 ::
  54 Some tags are "modal" tags and can't be nested, they would ignore any other tags inside it.
  55 If they are used as block tags, the closing \:: must be written as a single word on its own line.
  56
  57 subsection:: Structure
  58
  59 Some tags have structural meaning (for instance identifying a document section). They may or may not have text directly associated with them, for example a code:: section\:: section_title ::. Structural tags are hierarchical in nature, and persist until the next tag of the same or higher level.
  60 code::
  61 section:: Section 1
  62 Here's some normal prose.
  63 subsection:: Subsection 1
  64 Text in subsection 1.
  65 subsection:: Subsection 2
  66 Text in subsection 2.
  67 examples::
  68 The examples tag is at the same level in the hierarchy as section,
  69 so Section 1 ends at the examples tag above.
  70 ::
  71
  72 Structural tags at the same level in the hierarchy may be functionally equivalent, but treated differently for rendering or querying purposes. For example code::examples\:::: is equivalent to code::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.
  73
  74 Some structural tags don't have a specific section level, but builds hierarchies by using a close tag, like lists and tables. They can be nested.
  75
  76 All structural tags has children elements, for example the items in a list or the subsections and prose in a section.
  77
  78 section::Tags for use in the new SC Doc system
  79
  80 code::
  81 tag             hasText hasChilds structural needClose modal nestable
  82 ---------------------------------------------------------------------
  83 title           S
  84 class           S
  85 redirect        S
  86 related         S
  87 summary         S
  88 classtree       S
  89 copymethod      S
  90 keyword         S
  91 private         S
  92 section         S       x         1
  93 subsection      S       x         2
  94 method          S       x         3
  95 argument        S       x         4
  96 description             x         1
  97 classmethods            x         1
  98 instancemethods         x         1
  99 examples                x         1
 100 returns                 x         4
 101 discussion              x         4
 102 list                    x                    x               x
 103 tree                    x                    x               x
 104 numberedlist            x                    x               x
 105 definitionlist          x                    x               x
 106 table                   x                    x               x
 107 footnote                x                    x               x
 108 note                    x                    x               x
 109 warning                 x                    x               x
 110 code            V                            x        x
 111 link            V                            x        x
 112 anchor          V                            x        x
 113 emphasis        V                            x        x
 114 teletype        V                            x        x
 115 strong          V                            x        x
 116 soft            V                            x        x
 117 image           V                            x        x
 118 ##
 119 ||
 120 (prose)         V
 121
 122 hasText: tag captures text
 123     S is single-line (terminated by newline)
 124     V is variable-line
 125 hasChilds: tag captures child-elements
 126 structural: tag has structural level
 127 needClose: tag needs closing by ::
 128 modal: tag ignores any other tags than closing tag and do not nest
 129 nestable: tag can nest
 130 ::
 131
 132 Notes:
 133 list::
 134 ## modal tags can be written as inline (opening and closing tag on the same line)
 135 or block-style (the closing tag must be a single \:: on its own line).
 136 ## single vs variable line is only applicable for tags that captures text.
 137 ## modal, level and nestable are exclusive. nestable can be seen as a structural tag
 138 without explicit level. It's also because of the explicit level that the structural
 139 tags don't need closing.
 140 ## structural-needClose-modal-nestable could be reduced to one column:
 141   table::
 142   ## 1-4 || level, no close tag
 143   ## M   || modal, need close tag
 144   ## N   || nestable, need close tag
 145   ::
 146 ::
 147
 148 subsection:: Document attributes
 149
 150 These should only occur once in a document, and might be compulsory.
 151 code::
 152 title:: name
 153 class:: name
 154 summary:: text
 155 related:: link(s)
 156 categories:: name(s)
 157 ::
 158
 159 subsection:: Structural tags
 160
 161 These are grouped by their level in the hierarchy, from high to low:
 162 code::
 163 section:: name
 164 description::
 165 examples::
 166 instancemethods::
 167 classmethods::
 168
 169 subsection:: name
 170
 171 method:: name(s)
 172
 173 argument:: name
 174 ::
 175 description, examples and methods are equivalent to code::section\:::: structurally, but used to identify these special sections and render them consistently.
 176
 177 subsection:: Methods and arguments
 178
 179 Methods should appear under code::instancemethods\:::: or code::classmethods\::::, and are written with code:: method\:: name(s) ::.
 180 Do strong::not:: enter any arguments here, only the name.
 181 After the method, there should be a short description. Even if it can be multiple lines, keep it short and use code::discussion\:::: if you need more.
 182
 183 Methods get an anchor name automatically, prefixed with code::*:: for class methods and code::-:: for instance methods. For example, to link to the code::foo:: class method, use code:: link\::#*foo\:: ::.
 184
 185 After the method description comes the arguments, written with code:: argument\:: name :: where code::name:: must correspond to one of the methods arguments. After each argument line comes the description of that argument.
 186
 187 There is an optional code::returns\:::: tag that could be used to describe the methods return value.
 188
 189 If a longer discussion is needed, use the code::discussion\:::: tag. This is a good place to insert example code, etc.
 190
 191 Method signatures and argument defaults are filled in automagically.
 192
 193 Also, when multiple methods have the same signature (like ar and kr in ugens), they should all be listed in one single method tag.
 194
 195 Example:
 196 code::
 197 classmethods::
 198 private:: new1
 199
 200 method:: ar, kr
 201 short description here...
 202
 203 argument:: freq
 204 the frequency
 205 argument:: amp
 206 the amplitude
 207
 208 returns:: a new UGen
 209
 210 method:: foo
 211 short description..
 212
 213 argument:: x
 214 the x value
 215
 216 returns:: some kind of value
 217
 218 discussion::
 219 Here is a longer detailed discussion about this method, perhaps with example code, etc..
 220 ::
 221
 222 Any undocumented methods will show up in the rendered help file. To ignore methods, put them in a code::private\:::: tag, which must come directly after the code::instancemethods:: or code::classmethods:: tag.
 223
 224 subsection:: Copy methods from other class
 225 You can use code:: copymethod\:: ClassName, methodName :: to copy the documentation of a method from another helpfile to this one.
 226
 227 code::methodName:: must be prefixed with code::*:: (asterix) for class methods and code::-:: (dash) for instance methods.
 228
 229 note::
 230 The copied method must itself be a real code::method:: doc, not another code::copymethod::.
 231 ::
 232
 233 subsection:: Modal tags
 234 code::
 235 code::
 236 link::
 237 anchor::
 238 image::
 239 emphasis::
 240 strong::
 241 soft::
 242 teletype::
 243 ::
 244 All of above are closed with \::
 245 If they are used as block tags, the closing \:: must be written as a single word on its own line.
 246 Since they are modal tags, they can't be nested and any other tag than the closing tag is ignored until they are closed.
 247
 248 subsection:: Tables and lists
 249 code::
 250 list::
 251 tree::
 252 numberedList::
 253 definitionList::
 254 table::
 255 ::
 256 Tables and lists are kind of structural tags, but need to be closed with \::
 257 They use code::##:: and code::||:: to delimit items/rows and table columns.
 258
 259 code::
 260 table::
 261 ## one || two || three
 262 ## foo || bar || zoo
 263 \::
 264
 265 list::
 266 ## first
 267 ## second
 268 ## third
 269 \::
 270 ::
 271
 272 Lists can be nested:
 273 code::
 274 definitionList::
 275 ## one || the first thing has three subthings:
 276     list::
 277     ## one A
 278     ## one B
 279     ## one C
 280     \::
 281 ## two || the second thing
 282 \::
 283 ::
 284
 285 subsection:: ClassTree
 286
 287 A special tag to render a class hierarchy tree:
 288 code::
 289 classtree::Pattern
 290 ::
 291
 292 subsection:: Notes and warnings
 293 code::
 294 note:: text ::
 295 warning:: text ::
 296 ::
 297
 298 These tags can be multi-line and must end with \:: . They can contain other tags.
 299
 300 subsection:: Links
 301
 302 URL's are automagically converted to links.
 303
 304 The code::link\:::: tag is used for cross-reference between docs. It uses a simple namespace, example:
 305 code::
 306 See also link::Classes/SinOsc:: for a nice oscillator.
 307 Or take a look at link::Browse#UGens:: for a full list.
 308 The link::Overviews/Methods#play#play method:: is often very useful.
 309 ::
 310
 311 Anchors can be inserted manually with code::anchor\::name\:::: and referenced like this: code::
 312 link::Foo/Bar#hello::
 313 ::
 314 or to jump to an anchor in this document: code::
 315 link::#hello::
 316 ::
 317
 318 All sections get anchor names automagically, by making it lowercase and replacing spaces with '_' (underscore).
 319
 320 All methods get anchor names prefixed with code::*:: for class methods and code::-:: for instance methods.
 321
 322 One can change the rendered text of the link by using another code::#:: character:
 323 code::
 324 Also see link::Classes/SinOsc##a nice oscillator::
 325 ::
 326
 327 A link to specific methods:
 328 code::
 329 Take a look at link::Classes/SinOsc#*ar:: and link::Classes/Function#-play::
 330 ::
 331 Renders as: link::Classes/SinOsc#*ar:: and link::Classes/Function#-play::
 332
 333 The link::Overviews/Methods:: overview is dynamic and allows a specific method to be shown, by using the methodname as anchor, for example to get a list of all classes implementing code::play:: :
 334 code::
 335 All classes implementing code::play:: can be seen link::Overviews/Methods#play#here::.
 336 ::
 337 Renders as: All classes implementing code::play:: can be seen link::Overviews/Methods#play#here::.
 338
 339 The link::Browse:: page is also dynamic, and can take a category tree as anchor name:
 340 code::
 341 For more filters, see link::Browse#UGens>Filters::
 342 ::
 343 Renders as: For more filters, see link::Browse#UGens>Filters::
 344
 345 subsection:: Images
 346
 347 Images can be inserted with: code::
 348 image::filename::
 349 ::
 350
 351 A caption can be added like this: code::
 352 image::filename#caption::
 353 ::
 354
 355 subsection:: Footnotes
 356 Footnotes can be entered like this:
 357 code::
 358 Hello I'm a geek footnote::
 359 According to http://en.wikipedia.org/wiki/Geek the word geek is a slang term, with different
 360 meanings ranging from "a computer expert or enthusiast" to "a carnival performer who performs
 361 sensationally morbid or disgusting acts"
 362 \::
 363 ::
 364
 365 The result looks like this:
 366 Hello I'm a geek footnote::
 367 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"
 368 ::
 369
 370 subsection:: Document types
 371
 372 Document type is inferred by seeing if the document has a code::class\:::: or code::title\:::: tag.
 373
 374 Some tags are only allowed in some types of documents. Tags not mentioned below are allowed in all types:
 375 definitionlist::
 376 ## Class (and UGen) reference docs || tags: class, description, methods, examples, subsection
 377 ## Other docs (tutorials and such) || tags: title, section, subsection
 378 ::
 379
 380 Also, documents are organized in a simple directory layout after their "kind":
 381 list::
 382 ## Classes
 383 ## Reference
 384 ## Guides
 385 ## Overviews
 386 ## Tutorials
 387 ## Other
 388 ::
 389
 390 examples::
 391
 392 An example of documentation for LFPulse UGen:
 393
 394 code::
 395 class::LFPulse
 396 summary::pulse oscillator
 397 categories::UGens>Generators>Deterministic, UGens>Oscillators
 398 related::Classes/LFSaw
 399
 400 description::
 401 A non-band-limited pulse oscillator. Outputs a high value of one and a low value of zero.
 402
 403 classmethods::
 404 private:: categories
 405
 406 method:: ar, kr
 407
 408 argument::freq
 409 frequency in Hertz
 410
 411 argument::iphase
 412 initial phase offset in cycles ( 0..1 )
 413
 414 argument::width
 415 pulse width duty cycle from zero to one.
 416
 417 examples::
 418
 419 a plot:
 420 code::
 421 { LFPulse.ar(Line.kr(100, 800, 0.1)) }.plot(0.1);
 422 \::
 423
 424 50 Hz wave:
 425 code::
 426 { LFPulse.ar(50) * 0.1 }.play;
 427 \::
 428 ::
 429