This guide describes how to style and format the text and images in a Gaffer example.

1. Backdrops
2. Style
3. Grammar
4. Punctuation
5. Word choice
6. Spelling
7. Nodes
8. Plugs
9. Data
10. Interface
11. Actions and gestures
12. API
13. Other formatting

A Backdrop title should be clear and short. Regular Backdrop titles should be in sentence case, while the titular Backdrop should be in title case. A Backdrop's title shouldn't be wider than the Backdrop itself. If you need the extra space, create a second, wider Backdrop with no text but the same color, and place it behind the first.

The example name in the title Backdrop should match exactly how it appears in the Examples menu in Gaffer, and vice versa.

Backdrops titles should use the following formatting:

Each Backdrop with text should be 40 units wide for optimal line width. Note that this measure is in dimensionless Qt units.

You can initialize a Backdrop to use the correct size with this command in the Python Editor:

root["Backdrop"]["__uiBound"].setValue( imath.Box2f( imath.V2f( 0, 0 ), imath.V2f( 40, 20 ) ) )

Once initialized, manually adjust the height of the Backdrop to encompass its text.

All examples must have a titular Backdrop, with a properly-formatted title, and with body text describing what the example is showing and giving a brief rundown of how it works. For example:

In this graph, we show a procedurally-generated Macbeth chart. We load a "MacbethTexture" reference script to generate a texture in OSL, pass the texture to a standard Appleseed shader, and then assign it to a 5:3 ratio plane. To preview the scene in an IPR:

1. Select the InteractiveAppleseedRender node.
2. Click play.
3. Select the Catalogue node.
4. The IPR will display in the Viewer. To frame the image, hover the mouse cursor over the Viewer, then hit F.

When describing or pointing out a node inside your example with a text Backdrop, encompass the Backdrop and the node by placing a second Backdrop with the same color, and resize it to cover both the node Backdrop and the node. For example:

Never forget that you're directly writing to a person. If it helps, pretend you're writing an email to a coworker who's new to Gaffer.

When illustrating an idea or concept, try to provide one salient but simple and generic example that hits at the core of your point. Your example shouldn't be more complicated than the idea you're trying to convey. Examples that are overly esoteric, or assume too much prior knowledge risk distracting the user. If your example isn't immediately recognizable to the majority of Gaffer's users, it is useless.

Write instructions in the imperative tense.

In lists with more than two items, use the Oxford comma.

Don't mark acronyms, initialisms, abbreviations, and contractions with periods.

Only use ellipsis (...) when referring to wildcards in a path or set expression, or to indicate that you are omitting parts of code. Don't use them to trail off or hedge your words.

Avoid colloquial and slang words and phrases.

Don't use Latin/legal words, phrases, and abbreviations. The only exception is "etc", which you can use at the end of a list in a sentence.

When referring to yourself (the author), Gaffer's developers, or the collective efforts of the project as a whole, use the royal "we" and "our".

When speaking directly to the user, use "you" and "your".

Word spellings should follow Canadian English, using the following patterns that differ from American or British spelling:

The exceptions to this are words integral to VFX that conventionally (or predominantly) use American spellings, or that occur extremely frequently in the API, and would require too much effort to vary per context.

Note: The above table is subject to change.

Spell project names, software, and technologies the way their authors have established, even if they defy convention.

When referring to a file extension, but not the technology that drives it, enclose it in backticks, put it in lower case, and prefix it with a period.

There are two contexts where you can refer to a node by name: the Graph Editor and the API. In both cases, write the name exactly as it appears in context, like so: "[node name] node". When referring to multiple nodes in a row, put "[node name] nodes" only for the last node. If the node's name in context obfuscates its purpose, invoke its module as well. Do not use the node name as it appears in the node menu.

When modifying a node's name to indicate its purpose, append an underscore (_) and then any extra words in camel case (specifically Pascal case), so as to preserve its original name. The only exception is the Box node, which you can provide with a completely custom name, so long as it's in Pascal case.

There are three contexts where you can refer to a plug by name: the Node Editor, the API, and the Graph Editor. In all three cases, write the name exactly as it appears in context, like so: "[plug name] plug". When referring to multiple plugs in a row, put "[plug name] plugs" only for the last plug.

For a plug in the API, format it as inline code.

For a plug in the Graph Editor, use the name visible when you hover the cursor over it.

Format string and number values as inline code.

Format multi-line strings as code blocks.

Format scene and file paths shorter than a line width as inline code. Include the forward slash (/) in full paths. Format scene and file paths longer than the line width as code blocks.

To disambiguate path snippets in a sentence, add "parent/child location" for scene paths and "directory"/"sub-directory"/etc for file paths.

Do not use wildcard characters (* or ...) to indicate you have omitted part of the path.

Enclose set and channel names in double quotation marks.

Refer to the editors exactly as they appear in the interface.

When referring to an editor in general, use the definite article ("the"). When covering a task that requires a layout with multiple editors of the same type, use indefinite articles ("a", "an", "some", "any") as needed. In the majority of contexts, it's safe to assume the user's layout has at least one of each editor.

When instructing the user to select a top-level entry in an unnamed or context-specific menu, use the form "[Action/gesture] the [widget], then select [entry] from the context menu."

Use the following menu names:

Menu	Name
	the node menu
	the node context menu
	the Expansion menu the Selection Mask menu the Drawing menu etc

Use the following action-phrasing correspondence when instructing the user to perform an action in the interface. Never use the word "set" to describe an action.

Format references to modules, API code, and Python Editor code snippets as inline code. This includes API node names, plug names, methods, types, and data values.

Format entire lines of code as code blocks.

When referring to a keyboard key, put each key in upper case. When depicting a key combination, separate each key with a space, a plus (+), and another space: "CTRL + C".

When referring to the typical control key, spell it "Ctrl" to represent both Ctrl in Linux and the Command key (⌘) in macOS. If macOS's actual Control key is required, draw the user's attention to its atypical use.