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 math            V                            x        x
 116 strong          V                            x        x
 117 soft            V                            x        x
 118 image           V                            x        x
 119 ##
 120 ||
 121 (prose)         V
 122
 123 hasText: tag captures text
 124     S is single-line (terminated by newline)
 125     V is variable-line
 126 hasChilds: tag captures child-elements
 127 structural: tag has structural level
 128 needClose: tag needs closing by ::
 129 modal: tag ignores any other tags than closing tag and do not nest
 130 nestable: tag can nest
 131 ::
 132
 133 Notes:
 134 list::
 135 ## modal tags can be written as inline (opening and closing tag on the same line)
 136 or block-style (the closing tag must be a single \:: on its own line).
 137 ## single vs variable line is only applicable for tags that captures text.
 138 ## modal, level and nestable are exclusive. nestable can be seen as a structural tag
 139 without explicit level. It's also because of the explicit level that the structural
 140 tags don't need closing.
 141 ## structural-needClose-modal-nestable could be reduced to one column:
 142   table::
 143   ## 1-4 || level, no close tag
 144   ## M   || modal, need close tag
 145   ## N   || nestable, need close tag
 146   ::
 147 ::
 148
 149 subsection:: Document attributes
 150
 151 These should only occur once in a document, and might be compulsory.
 152 code::
 153 title:: name
 154 class:: name
 155 summary:: text
 156 related:: link(s)
 157 categories:: name(s)
 158 ::
 159
 160 subsection:: Structural tags
 161
 162 These are grouped by their level in the hierarchy, from high to low:
 163 code::
 164 section:: name
 165 description::
 166 examples::
 167 instancemethods::
 168 classmethods::
 169
 170 subsection:: name
 171
 172 method:: name(s)
 173
 174 argument:: name
 175 ::
 176 description, examples and methods are equivalent to code::section\:::: structurally, but used to identify these special sections and render them consistently.
 177
 178 subsection:: Methods and arguments
 179
 180 Methods should appear under code::instancemethods\:::: or code::classmethods\::::, and are written with code:: method\:: name(s) ::.
 181 Do strong::not:: enter any arguments here, only the name.
 182 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.
 183
 184 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\:: ::.
 185
 186 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.
 187
 188 There is an optional code::returns\:::: tag that could be used to describe the methods return value.
 189
 190 If a longer discussion is needed, use the code::discussion\:::: tag. This is a good place to insert example code, etc.
 191
 192 Method signatures and argument defaults are filled in automagically.
 193
 194 Also, when multiple methods have the same signature (like ar and kr in ugens), they should all be listed in one single method tag.
 195
 196 Example:
 197 code::
 198 classmethods::
 199 private:: new1
 200
 201 method:: ar, kr
 202 short description here...
 203
 204 argument:: freq
 205 the frequency
 206 argument:: amp
 207 the amplitude
 208
 209 returns:: a new UGen
 210
 211 method:: foo
 212 short description..
 213
 214 argument:: x
 215 the x value
 216
 217 returns:: some kind of value
 218
 219 discussion::
 220 Here is a longer detailed discussion about this method, perhaps with example code, etc..
 221 ::
 222
 223 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.
 224
 225 subsection:: Copy methods from other class
 226 You can use code:: copymethod\:: ClassName, methodName :: to copy the documentation of a method from another helpfile to this one.
 227
 228 code::methodName:: must be prefixed with code::*:: (asterix) for class methods and code::-:: (dash) for instance methods.
 229
 230 note::
 231 The copied method must itself be a real code::method:: doc, not another code::copymethod::.
 232 ::
 233
 234 subsection:: Modal tags
 235 code::
 236 code::
 237 link::
 238 anchor::
 239 image::
 240 emphasis::
 241 strong::
 242 soft::
 243 teletype::
 244 ::
 245 All of above are closed with \::
 246 If they are used as block tags, the closing \:: must be written as a single word on its own line.
 247 Since they are modal tags, they can't be nested and any other tag than the closing tag is ignored until they are closed.
 248
 249 subsection:: Tables and lists
 250 code::
 251 list::
 252 tree::
 253 numberedList::
 254 definitionList::
 255 table::
 256 ::
 257 Tables and lists are kind of structural tags, but need to be closed with \::
 258 They use code::##:: and code::||:: to delimit items/rows and table columns.
 259
 260 code::
 261 table::
 262 ## one || two || three
 263 ## foo || bar || zoo
 264 \::
 265
 266 list::
 267 ## first
 268 ## second
 269 ## third
 270 \::
 271 ::
 272
 273 Lists can be nested:
 274 code::
 275 definitionList::
 276 ## one || the first thing has three subthings:
 277     list::
 278     ## one A
 279     ## one B
 280     ## one C
 281     \::
 282 ## two || the second thing
 283 \::
 284 ::
 285
 286 subsection:: ClassTree
 287
 288 A special tag to render a class hierarchy tree:
 289 code::
 290 classtree::Pattern
 291 ::
 292
 293 subsection:: Notes and warnings
 294 code::
 295 note:: text ::
 296 warning:: text ::
 297 ::
 298
 299 These tags can be multi-line and must end with \:: . They can contain other tags.
 300
 301 subsection:: Links
 302
 303 URL's are automagically converted to links.
 304
 305 The code::link\:::: tag is used for cross-reference between docs. It uses a simple namespace, example:
 306 code::
 307 See also link::Classes/SinOsc:: for a nice oscillator.
 308 Or take a look at link::Browse#UGens:: for a full list.
 309 The link::Overviews/Methods#play#play method:: is often very useful.
 310 ::
 311
 312 Anchors can be inserted manually with code::anchor\::name\:::: and referenced like this: code::
 313 link::Foo/Bar#hello::
 314 ::
 315 or to jump to an anchor in this document: code::
 316 link::#hello::
 317 ::
 318
 319 All sections get anchor names automagically, by making it lowercase and replacing spaces with '_' (underscore).
 320
 321 All methods get anchor names prefixed with code::*:: for class methods and code::-:: for instance methods.
 322
 323 One can change the rendered text of the link by using another code::#:: character:
 324 code::
 325 Also see link::Classes/SinOsc##a nice oscillator::
 326 ::
 327
 328 A link to specific methods:
 329 code::
 330 Take a look at link::Classes/SinOsc#*ar:: and link::Classes/Function#-play::
 331 ::
 332 Renders as: link::Classes/SinOsc#*ar:: and link::Classes/Function#-play::
 333
 334 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:: :
 335 code::
 336 All classes implementing code::play:: can be seen link::Overviews/Methods#play#here::.
 337 ::
 338 Renders as: All classes implementing code::play:: can be seen link::Overviews/Methods#play#here::.
 339
 340 The link::Browse:: page is also dynamic, and can take a category tree as anchor name:
 341 code::
 342 For more filters, see link::Browse#UGens>Filters::
 343 ::
 344 Renders as: For more filters, see link::Browse#UGens>Filters::
 345
 346 subsection:: Images
 347
 348 Images can be inserted with: code::
 349 image::filename::
 350 ::
 351
 352 A caption can be added like this: code::
 353 image::filename#caption::
 354 ::
 355
 356 subsection:: Footnotes
 357 Footnotes can be entered like this:
 358 code::
 359 Hello I'm a geek footnote::
 360 According to http://en.wikipedia.org/wiki/Geek the word geek is a slang term, with different
 361 meanings ranging from "a computer expert or enthusiast" to "a carnival performer who performs
 362 sensationally morbid or disgusting acts"
 363 \::
 364 ::
 365
 366 The result looks like this:
 367 Hello I'm a geek footnote::
 368 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"
 369 ::
 370
 371 subsection:: Mathematics
 372 Mathematics can be entered in TeX syntax using the code::math\:::: tag. Example:
 373 code::
 374 This is inline math::2\pi:: and below is block display math:
 375 math::
 376 1\over\sqrt{x^\pi}
 377 \::
 378 ::
 379
 380 Renders:
 381
 382 This is inline math::2\pi:: and below is block display math:
 383 math::
 384 1\over\sqrt{x^\pi}
 385 ::
 386
 387 subsection:: Document types
 388
 389 Document type is inferred by seeing if the document has a code::class\:::: or code::title\:::: tag.
 390
 391 Some tags are only allowed in some types of documents. Tags not mentioned below are allowed in all types:
 392 definitionlist::
 393 ## Class (and UGen) reference docs || tags: class, description, methods, examples, subsection
 394 ## Other docs (tutorials and such) || tags: title, section, subsection
 395 ::
 396
 397 Also, documents are organized in a simple directory layout after their "kind":
 398 list::
 399 ## Classes
 400 ## Reference
 401 ## Guides
 402 ## Overviews
 403 ## Tutorials
 404 ## Other
 405 ::
 406
 407 examples::
 408
 409 An example of documentation for LFPulse UGen:
 410
 411 code::
 412 class::LFPulse
 413 summary::pulse oscillator
 414 categories::UGens>Generators>Deterministic, UGens>Oscillators
 415 related::Classes/LFSaw
 416
 417 description::
 418 A non-band-limited pulse oscillator. Outputs a high value of one and a low value of zero.
 419
 420 classmethods::
 421 private:: categories
 422
 423 method:: ar, kr
 424
 425 argument::freq
 426 frequency in Hertz
 427
 428 argument::iphase
 429 initial phase offset in cycles ( 0..1 )
 430
 431 argument::width
 432 pulse width duty cycle from zero to one.
 433
 434 examples::
 435
 436 a plot:
 437 code::
 438 { LFPulse.ar(Line.kr(100, 800, 0.1)) }.plot(0.1);
 439 \::
 440
 441 50 Hz wave:
 442 code::
 443 { LFPulse.ar(50) * 0.1 }.play;
 444 \::
 445 ::
 446