Examples Style Guide
This guide describes how to style and format the text and images in a Gaffer example.
- Backdrops
- Style
- Grammar
- Punctuation
- Word choice
- Spelling
- Nodes
- Plugs
- Data
- Interface
- Actions and gestures
- API
- 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:
| Backdrop purpose | Text | Color |
|---|---|---|
| Title of example | Example: [Example Name] | — |
| Note | Note: [Note title] | Color3f( 0.3479, 0.4386, 0.5 ) |
| Tip | Tip: [Tip title] | Color3f( 0.3, 0.5, 0.4605 ) |
| Other backdrop | [Backdrop title] | — |
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:
- Select the InteractiveAppleseedRender node.
- Click play.
- Select the Catalogue node.
- 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.
| Correct | Incorrect |
|---|---|
| click the node to select it | clicking the node will select it |
In lists with more than two items, use the Oxford comma.
| Correct | Incorrect |
|---|---|
| Lions, tigers, and bears. | Lions, tigers and bears. |
Don't mark acronyms, initialisms, abbreviations, and contractions with periods.
| Correct | Incorrect |
|---|---|
| OSL | O.S.L. |
| Encoded using FACS. | Encoded using F.A.C.S. |
| comp work | comp. work |
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.
| Correct | Incorrect |
|---|---|
| Your render will be queued on the farm. | Your render will be queued on the farm... |
| any `gaffer execute ...` command |
Avoid colloquial and slang words and phrases.
| Correct | Incorrect |
|---|---|
| lots | gobs |
| to start | starter for ten |
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.
| Correct | Incorrect |
|---|---|
| such as | i.e. |
| in other words | |
| in place | in situ |
| for example | e.g. |
| specifically | to wit |
| primitives such as spheres, cubes, cones, etc |
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".
| Correct | Incorrect |
|---|---|
| we will demonstrate how to | I will demonstrate how to |
When speaking directly to the user, use "you" and "your".
| Correct | Incorrect |
|---|---|
| Select whichever color you prefer. | The user should select their preferred color. |
Word spellings should follow Canadian English, using the following patterns that differ from American or British spelling:
| Preferred spelling patterns |
|---|
| serialize |
| centre |
| licence |
| travelling |
| fulfill |
| dialogue |
| program |
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.
| American spelling exceptions |
|---|
| color |
| Color3f |
| center |
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.
| Correct | Incorrect |
|---|---|
| macOS | MacOS |
| FFmpeg | FFMPEG |
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.
| Correct | Incorrect |
|---|---|
| Arnold `.ass` file. | Arnold ASS file. |
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.
| Correct | Incorrect |
|---|---|
| an Instancer node | an Instancer |
| Create two more Instancer nodes. | Create two more Instancers. |
| add to the `root["Instancer"]` node | add to `root["Instancer"]` |
| OSL's AddColor node | OSLAddColor node |
| the Appleseed point_light node | the asPoint node |
| Connect the Sphere node to the Instancer, Parent, and Group nodes. | Connect the Sphere to the Instancer, Parent, and Group. |
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.
| Correct | Incorrect |
|---|---|
| Camera_Render | renderCam |
| Group_Lights | Group_lights |
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.
| Correct | Incorrect |
|---|---|
| check the Expand Data Window plug | check expandDataWindow |
| call the method on the `expandDataWindow` plug | call the method on the expandDataWindow plug |
| In the Graph Editor, connect the Sphere node's out plug to the Group node's in1 plug. | Connect the Sphere node's Out plug to the Group node's In plug. |
Format string and number values as inline code.
| Correct | Incorrect |
|---|---|
| Set the Radius plug to `2.3`. | Set the Radius plug to 2.3. |
Format multi-line strings as code blocks.
| Correct | Incorrect |
|---|---|
| ``` There are more things in heaven and earth, Horatio, Than are dreamt of in your philosophy. ``` |
"There are more things in heaven and earth, Horatio, Than are dreamt of in your philosophy." |
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.
| Correct | Incorrect |
|---|---|
| Type `/asset01/REN` into the Parent plug. | Type "/asset01/REN" into the Parent plug. |
| the attributes of the `REN` child location | the attributes of `REN` |
| ``` /extremely/long/path/to/a/particular/location ``` |
`/extremely/long/path/to/a/particular/location` |
Enclose set and channel names in double quotation marks.
| Correct | Incorrect |
|---|---|
| the "REN" set | the `REN` set |
Refer to the editors exactly as they appear in the interface.
| Correct | Incorrect |
|---|---|
| Viewer | viewport |
| Primitive Inspector | PrimitiveInspector |
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.
| Examples |
|---|
| the Graph Editor |
| the Node Editor |
| Open a new Viewer. |
| Open two more Viewers. |
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."
| Examples |
|---|
| Right-click the node, then select Set Color 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.
| Action | Verbs and phrasing |
|---|---|
| left-clicking | click [button name or image] |
| right- and middle-clicking | right-click the node |
| clicking and dragging | click and drag a marquee around the nodes |
| middle-click and drag the node onto the Viewer | |
| clicking with a modifier key | SHIFT-click the other node |
| choosing an item from a drop-down list | select Color from the list |
| choosing a menu bar item | Go File > Settings. |
| choosing a context menu item | select Scene > Hierarchy > Group |
| inputting text | type `user:custom` into the plug |
| hovering the cursor | hover the cursor over the Graph Editor |
| keystroke | hit ENTER |
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.
| Examples |
|---|
| the `imath` module |
| To return the value of the Radius plug, use the `getValue()` method. |
| the plug can be accessed at `root["Sphere"]["radius"]` |
Format entire lines of code as code blocks.
| Examples |
|---|
| ``` root["Sphere"]["radius"].getValue() ``` |
| ``` import imath root["Sphere"]["transform"]["translate"].setValue( imath.V3f( 0, 1, 0 ) ) ``` |
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.
| Correct | Incorrect |
|---|---|
| hit ENTER | hit Enter |
| hit CTRL + ALT + C | hit Ctrl-Alt-c |