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.