supercollider-common 1:3.6.3~repack-5 / usr / share / SuperCollider / HelpSource / Guides / WritingHelp.schelp

title:: Writing Help
summary:: Get started with writing help
categories:: HelpSystem
related:: Reference/SCDocSyntax, Classes/SCDoc

section:: Writing new help
The simplest way is to look at an existing help file or class document, and read this document and link::Reference/SCDocSyntax::

note:: The help files should use UTF-8 encoding! ::

subsection:: News in SC 3.5.2
SCDoc has been rewritten and the parser is now implemented in C++ for speed and stability.
The syntax has gotten stricter, and it will throw errors or warnings if there are faults in the documentation.

Some important changes to keep in mind:
list::
## Linking to sections does no longer use lower_case_and_underscored anchors, but the exact section title as it is. Example: teletype::link\::#Language-side news\:::: renders: link::#Language-side news::
## Run code::SCDoc.indexAllDocuments:: if you add a new document or other file and want to see the change reflected in the help. If you just changed a document and want to see the changes, just press Reload in the browser and SCDoc will detect and re-index automatically.
## The teletype::CLASS\:::: tag is deprecated, just use teletype::TITLE\:::: instead also for class reference docs.
## The argument name given to the teletype::ARGUMENT\:::: tag is now optional. If not given, SCDoc will auto-fill the real argument name.
::

subsection:: Documenting new classes
When you navigate to an undocumented class, it will contain an schelp template that can be filled in and saved to HelpSource/Classes/ClassName.schelp.

section:: Converting old helpfiles
There is no automated process for this, but for most help files it's really simple to do it manually:

numberedlist::
## open the old helpfile in your web browser
## copy the text and insert it in a new textfile: FileName.schelp
## add the appropriate tags, like title, sections, etc.. (see below)
## save the file to the right subdirectory under HelpSource, depending on the document kind (see link::#Directory layout:: below)
## strong:: check that it rendered OK ::.
You can run code::SCDoc.indexAllDocuments:: (link to method documentation: link::Classes/SCDoc#*indexAllDocuments::) to make SCDoc detect the new file and add it to the document index.

If the file already existed and you want to see the changes, just press Reload in the help browser and SCDoc will re-render it.
::

A list of all undocumented classes can be seen here: link::Browse#Undocumented classes:: (auto-generated).

section:: Directory layout
The help system uses different folders under HelpSource depending on document kind:
definitionlist::
## HelpSource ||
definitionlist::
## Classes || class reference, file must be named as the class.
## Reference || other reference documentation.
## Tutorials || yes, tutorials.
## Guides || guides that explain stuff but without beeing a real tutorial.
## Overviews || overviews of other documents, these are mostly auto-generated.
## Other || stuff that don't fit in any other directory.
::
::

note:: It's important that the document is put in the right folder. For Classes, it's a must! ::

All .schelp files will be parsed and rendered to an equal directory layout in the help target directory. Any other files, like images or ready-made HTML files, will just be copied.

section:: Document header

All tags that are used for document metadata should be entered at the top of the document source file, before any section or other text. See link::Reference/SCDocSyntax#Header tags::

note:: You should always specify title, summary and categories. ::

section:: Normal documents

Example header:
teletype::
title:: My help file
summary:: A short single-line summary of what this is
categories:: Language>Conditionals, SomeOtherCategory
related:: Reference/FooBar
::

Then use normal text in sections and subsections, and possible other tags for lists, tables, trees, images, links, etc.. See link::Reference/SCDocSyntax:: for tag reference.

teletype::
section:: Introduction

This is a nice document...
blah blah blah..

subsection:: Details

Some details..
::

section:: Class reference
Class reference has some special tags and a more strict structure. Normal text should be written inside the special top-level sections DESCRIPTION, CLASSMETHODS, INSTANCEMETHODS and EXAMPLES.

Named subsections can be used under each of the above mentioned top-level sections.

Also named sections can be used, but they will be put after all above top-level sections.

subsection:: Methods and arguments
Methods are documented like this:
tree::
## teletype::method\:::: name(s)
    tree::
    ## short description of method.
    ## teletype::argument\:::: name1
    tree::
        ## description of argument
        ::
    ## teletype::argument\:::: name2
    tree::
        ## description of another argument.
        ::
    ## teletype::returns\::::
    tree::
        ## description of return value
        ::
    ## teletype::discussion\::::
    tree::
        ## optional discussion and example code
        ::
    ::
::

note:: Don't list arguments in the method tag, only the method names ::

After the method description comes the arguments, written with teletype:: argument\:: name :: where
strong::name:: is optional, and will be auto-filled in if not given. If given, it must match the real argument name of the method. After each argument line comes the description of that argument.

There is an optional teletype::returns\:::: tag that could be used to describe the methods return value.

If a longer discussion is needed, use the teletype::discussion\:::: tag. This is a good place to insert example code, etc.

Setters are handled automagically, when documenting a setter/getter, use only the getter name (no underscore) and describe both setter and getter as a single property, example:
teletype::
method:: helpSourceDir
set or get the help source directory
::

Methods get an anchor name automatically, prefixed with teletype::*:: for class methods and teletype::-:: for instance methods. For example, to link to the teletype::foo:: class method, use teletype:: link\::#*foo\:: ::.

The teletype::method\:::: tag can be used also in normal documents, and emphasis::should:: then have argumentnames. This can be useful for documenting common interfaces outside of a specific class document, for example link::Reference/plot::.
Anchors for these methods get prefixed with a dot (.) instead of * or -.

When multiple methods have the same signature (like ar and kr in ugens), they should all be listed in one single method tag.


SCDoc generates docs for all undocumented methods. To ignore private methods, add them to a teletype::private\:::: tag, which works just like the method tag but without a section body.

Extensions can add methods to existing class docs, see the link::#Extensions:: section below.

subsection:: Copy methods from other class
You can use teletype:: copymethod\:: ClassName, methodName :: to copy the documentation of a method from another helpfile to this one.

teletype::methodName:: must be prefixed with teletype::*:: (asterix) for class methods and teletype::-:: (dash) for instance methods.


subsection:: Redirect classes
Some classes uses the code::*doesNotUnderstand:: trick to redirect to another implementing class. To document such classes, you need to add this tag in the header:
teletype::
redirect:: implClass
::
Where teletype::implClass:: is the name of the class variable holding the implementing class.

subsection:: Example

An example of documentation for LFPulse UGen, saved to HelpSource/Classes/LFPulse.schelp

teletype::
TITLE:: LFPulse
summary:: pulse oscillator
categories:: UGens>Generators>Deterministic, UGens>Oscillators
related:: Classes/LFSaw

DESCRIPTION::
A non-band-limited pulse oscillator. Outputs a high value of one and a low value of zero.

CLASSMETHODS::
private:: categories

METHOD:: ar, kr

argument::freq
frequency in Hertz

argument::iphase
initial phase offset in cycles ( 0..1 )

argument::width
pulse width duty cycle from zero to one.

returns::
An UGen.

EXAMPLES::

a plot:
code:: { LFPulse.ar(Line.kr(100, 800, 0.1)) }.plot(0.1); ::

50 Hz wave:
code:: { LFPulse.ar(50) * 0.1 }.play; ::
::


section:: Categories
Try to find good categories for the doc you are writing/converting. If a suitable category already exists, you should use that. See the link::Browse##Document Browser:: (auto-generated) for existing categories.

For UGens, you should use the existing categories like UGens>Filter>Nonlinear. View the current categories like this:
code::
Ball.categories
::

Documents can exist in multiple categories, and also have hierarchical categories, like Sequencing>Patterns.

section:: Cross-document linking
To link another document, use teletype:: link\::Path/To/Document\:: :: where the path is relative to link::Classes/SCDoc#*helpTargetDir:: and the document filename is with no extension. Example:
teletype::
Also take a look at link::Classes/SinOsc:: and link::Reference/Literals::
::

subsection:: Methods
To link to a specific class method, append code::#*methodName:: or to an instance method, append code::#-methodName:::
teletype::
Also take a look at the play method of link::Classes/Function#-play::
::
This will render as link::Classes/Function#-play::

For generic methods documented outside of instancemethods or classmethods (like the generic link::Reference/play:: document), use a dot (.) as prefix instead of * or -.

The special link::Overviews/Methods:: overview is dynamic and allows a specific method to be shown by appending code::#name:: where name is the name of the method:
teletype::
For all implementations of play, see link::Overviews/Methods#play::
::

section:: Making the document findable by Search
The link::Search:: page can match on document title/filename, summary, non-private methods, and categories.
If you mention something that should match in search but is not one of the above, you can explicitly add it with the keyword tag:
teletype::
keyword:: someKeyWords
::

section:: Extensions
subsection:: Quarks and extensions
Each extension should have their own HelpSource folder with files that should be included in the help system.

Example file layout:
code::
MyQuark/HelpSource/Classes/MyClass1.schelp
MyQuark/HelpSource/Classes/MyClass2.schelp
MyQuark/HelpSource/Guides/MyGuide.schelp
MyQuark/HelpSource/Guides/MyPicture.png
MyQuark/MyClass1.sc
MyQuark/MyClass2.sc
::

note::
All helpfiles contained in a quark will automatically get a category "Quarks>NameOfQuark" added, so you should not add this yourself. This makes it easy to navigate all documentation of a specific quark.
::

If you want to set a main help file for the quark, set code::\schelp:: in the Quark directory file to the path for the help file relative to teletype::HelpSource:: and without the teletype::.schelp:: extension. Example: code::\schelp: "Guides/MyGuide"::

subsection:: Method extensions
An extension that adds methods to existing classes should document these in code::Classes/TheClass.ext.schelp::, only including the relevant bits (no title, summary, categories, etc..)

Example: Classes/String.ext.schelp
teletype::
INSTANCEMETHODS::

subsection:: Extensions by SCDoc

method:: stripWhiteSpace
strips whitespace at the beginning and end of the string
returns:: the stripped string
::

The contents are inserted into the right spot (section, subsection, etc).
It works for all kind of sections, for example one can add a subsection to code::DESCRIPTION\:::: with additional information, or add another top-level section, etc.





section:: Links

URL's are automagically converted to links.

The code::link\:::: tag is used for cross-reference between docs. It uses a simple namespace, example:
code::
See also link::Classes/SinOsc:: for a nice oscillator.
Or take a look at link::Browse#UGens:: for a full list.
The link::Overviews/Methods#play#play method:: is often very useful.
::

Anchors can be inserted manually with code::anchor\::name\:::: and referenced like this: code::
link::Foo/Bar#hello::
::
or to jump to an anchor in this document: code::
link::#hello::
::

All sections get anchor names automagically.

All methods get anchor names prefixed with code::*:: for class methods and code::-:: for instance methods.

One can change the rendered text of the link by using another code::#:: character:
code::
Also see link::Classes/SinOsc##a nice oscillator::
::

A link to specific methods:
code::
Take a look at link::Classes/SinOsc#*ar:: and link::Classes/Function#-play::
::
Renders as: link::Classes/SinOsc#*ar:: and link::Classes/Function#-play::

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:: :
code::
All classes implementing code::play:: can be seen link::Overviews/Methods#play#here::.
::
Renders as: All classes implementing code::play:: can be seen link::Overviews/Methods#play#here::.

The link::Browse:: page is also dynamic, and can take a category tree as anchor name:
code::
For more filters, see link::Browse#UGens>Filters::
::
Renders as: For more filters, see link::Browse#UGens>Filters::