Editing/Writing Manual Pages
Some rules of thumb for manual writing/editing:
- Keyboard bindings are marked up with <kbd>
- Bindings involving the platform specific "primary" modifier should be marked up with <kbd class=mod1>. There are also "mod12" and "mod13" to markup bindings involving primary, secondary and tertiary modifiers.
- Markup menu selections as <code>Foo > Bar</code>
- Definition Lists (<dl>) are presented with dt and dd elements on the same line. If you need more space for the dt element, add
class="wide-table"to the <dl> tag.
- Try to keep pages to not much more than 1 screenful (whatever that means in this era)
- All pages start with <h2>TITLE</h2>
- All chapter pages end with: "This chapter covers the following:"
- If you need to nest below <h3>, consider a new child page
- Ask before adding new chapters (top level pages)
- If you need to embed links, or use <kbd> tags, be sure to change the Input Format to "Ardour Manual". Links are not allowed in the default format (though <img src=....> is fine). In general, using this input format rather than "Filtered HTML" will not hurt and is probably sensible.
- At the present time (December 2012), merging existing documentation is more important than writing new stuff.