Writing help in wiki format

In the Help tabs of custom shelf items and digital assets, you can type help in straight HTML, or use wiki formatting. Wiki formatting is designed to be easier and clearer than HTML.

Wiki formatting lets you write help similarly to how you write email. Instead of using <p> tags, you separate paragraphs with a blank line…

This is the first paragraph.

This is the second paragraph.

…and you use common email-style formatting for emphasis…

Let's put _this bit_ in italics and *this bit* in bold.

…and lists…

* First item
* Second item
* Third item

There are more complicated bits of markup, such as for making a link to the documentation for a node…

See the documentation for the [Paint node|Node:sop/paint]
for more information.

…but the basics are pretty easy to pick up.

You can even use HTML inside wiki formatted text when you need to…

This parameter doesn't work yet because
I'm <h:strike>lazy</h:strike> not sure it's needed.

…and you can use a slightly more compact shorthand for big pieces of structured HTML…

table>>
    tr>>
        td>>
            This is the content of the table cell
            on the left.

            - First item
            - Second item
        td>>
            This is what's in the table cell
            on the right.

            You can still use _wiki markup_
            here, of course.

A line starting with an = sign sets the title of the document. Only use one title per file.

= Document title =

Put a summary of the file’s contents inside triple-quotes.

"""Explains how to use wiki formatting markup."""

When you're documenting shelf items, Houdini uses this summary for the tooltip when you hover over the item on the shelf.

Headings are done similarly to in MediaWiki:

== Heading ==

=== Sub heading ===

The number of = signs at the beginning of the line determines the heading level, or you can indent the contents under the heading, in which case the number of = signs is ignored (as long as it’s 2 or more) and the indentation is used to determine what contents are under what headings.

A heading with 1 = at the beginning is always the title of the document. Do not use a single = for in-page headings.

Lines that start #name: value set page properties. These are used by the Houdini documentation to set up page metadata, but the only one that’s very useful for user help is…

#largeicon: opdef:Object/my_asset?icon.png

This uses an image file (in this case embedded in a digital asset) as the icon that appears next to the title. For a digital asset, this should be a bitmap of the node’s icon. The image should be 48 by 48 pixels.

Note that if your image file is on disk, you can refer to it using the help system’s virtual path. For example:

#largeicon: /nodes/obj/my_asset.png

The virtual path gets mapped to the help search path. So if you save my_asset.png into $HOME/houdiniX.Y/help/nodes/obj (or $HOME/Library/Preferences/houdini/X.Y/help/nodes/obj on Mac OSX), then the help system will be able to locate your icon using the line above.

- Start bullet lists with a minus or asterisk, followed by a space.
  - Indent sub-items.

* You can also use traditional wiki bullets
** In this style, the number of -s or *s determines the item's level.

# Start numbered lists with a hash sign, followed by a space.
# This is item number 2.

For definition lists, put the term on its own line with a : at the end, and indent the definition paragraph(s).

Term:
   Definition.

Another term:
    Its definition.

Use *asterisks for bold* and _underlines for italics_.

Use double underlines to indicate a button, option, menu, or other UI element…

# Click the __Help__ tab.
# Write some help.
# Click __Accept___.

Put descriptions of keypresses in double parentheses. You can use LMB, MMB, and RMB for the mouse buttons.

Hold ((Space)), then press ((Ctrl + K), then click ((Shift + RMB)).

Put computer text between backticks (see also code blocks below)…

Type `run test` in the console.

These follow a common style.

[What's new in Houdini 10.0|/news/10/]

[Node:sop/copy]

[Cmd:alias]

[Exp:turb]

[Hom:hou.Node.name]

[Vex:bumpmap]

[Image:/images/brush.png]

To make internal links, first put a bit of ID text after a heading in parentheses…

== Locking the geometry == (locking)

Then to link to that heading…

See [locking geometry|#locking] below.

NOTE:
  This is a note.

  This is the second paragraph.

NOTE: This is another note.

TIP: This is a tip.

WARNING:
  This is a warning.

For blocks of code, start with {{{ (three open curly braces), followed by the lines of code, and finish with }}} (three close curly braces).

{{{
This is a block of
preformatted code.

  All whitespace is preserved.
  
    And any characters that are normally
    wiki markup are ignored
}}}

You can specify syntax coloring of the block contents by writing #! followed by the coloring type as the first line inside the block. For example, if the first line inside the block is #!python, it will use Python syntax coloring.

The can color many different types of information. Some useful values are python, vex, hscript, xml, c, c++, and sh.

{{{
#!python
def add(a, b):
    return a + b
}}}

When documenting digital assets you can use special headings starting with an @ symbol followed by a name. These mark special sections that could potentially be rendered differently. For example, definition lists are given a distinctive look inside @parameters sections.

These special sections function like headings of a higher level than headings you make with ==, so you can use == headings inside them.

= My Asset =

"""Creates a rain box."""

Explain how to use the asset here.

@inputs

Bounding box:
    If you connect something to the first input,
    this asset will use it as the bounding box for
    the rain.

@parameters

== Options tab ==

Activate:
    When this is 1, the rain falls. When this is 0,
    the rain stops.

== Rendering tab ==



@locals

PPX:
    The pixel in the image map corresponding to the
    current point.

Any text after the @ symbol and the name overrides default heading text…

@parameters The Parameters of This Node

These sections are largely future-proofing against potential translation, so we don’t have to explicitly check that a heading uses a certain English word or phrase. For example, you could potentially mark the parameters section using the parameters name but show translated heading text…

@parameters Parámetros

• To indicate that a character should be passed through and not considered markup, precede it with a backslash. For example, to prevent the square brackets in a[0,0,3] from becoming a link…

  Extract the array value a\[0,0,3].
  

  If you actually want a backslash in your text, use a double backslash (so the first backslash escapes the second one)…

  Put a backslash (\\) between the parts of the path on Windows.
  

  Note

  Most markup is ignored inside backticks, so when you explicitly mark something as computer text by putting it inside backticks, you usually don’t need to worry about escaping characters. This is especially useful for file paths on Windows – put them inside backticks so you don’t need to escape the backslashes.

• Text between @< and >@ is passed through unparsed – it’s like escaping every character inside.

• Wiki markup is always treated as UTF-8 encoded.