}
to apps.css.
If you add a new class with semantic meaning, document it below, under
-"Custom classes".
+"Custom classes", and be sure to explain it to the reader at
+_manual/01_welcome-to-ardour/02_about-ardour-documentation.html.
2. Format and Validation
use for potentially dangerous situations involving data loss, malfunction,
or sound quality issues. Currently rendered in a red box.
+.mac, .lin, .win:
+use as additional classes to mark a section as relevant for these operating
+systems only.
+
Check _manual/01_welcome-to-ardour/02_about-ardour-documentation.html, it
serves as a style and markup guide.
On each page, use only for the first occurrence of every abbreviation. Avoid
a redundant explanation in the text - the expansion can easily be extracted
via CSS for printing.
+Use only in the text body, not in headings.
<em>
is used to emphasize a word. Commonly rendered as italics.
See above for other <kbd> classes to denote menu items, selections, mouse
events and controller actions.
+Keys and mouse key names should always be capitalized. We do not need to
+distringuish between "x" and "X", because the latter would be "Shift-X".
+In case you forget, the stylesheet takes care of this.
+
+CSS Classes used with <kbd> are:
+.modN
+.mouse: mouse buttons
+.cmd: a command line
+.lin, .win, .mac: add nice prompts to that command line
+.input: inline text to be entered by the user
+.menu: path to an Ardour menu or other GUI item
+.option: path to an option, with (X) at the end.
+.optoff: path to an option, with ( ) at the end.
+.button, .fader, .knob: external controllers (OSC or MIDI).
+
<code>
is only used for program code, or the content of configuration files etc. Do
not abuse to style keys or user input, use <kbd> instead.
The image tag must contain a 'src="/images/yourimage.png"' element and a
descriptive 'alt="A short textual description of the image content"'
element.
+Images are usually placed as block-level elements, i.e. outside of a
+paragraph.
+5. Other conventions
+====================
-5. Typography
-=============
+
+5.1 Typography
+--------------
* Avoid any typographical quotation marks to highlight terms or express any
kind of subtle inflection, use semantic markup instead.
the long em-dash.
* For ranges of values, use the en-dash: Monday – Friday, 0 –
11.
+* Use a non-breaking space (" ") between a number and its unit.
+
+
+5.2 Language
+------------
+
+* The Ardour manual is written in Americal English spelling.
+* Use SI units with standard abbreviations. Give imperial units only as
+ additional information, if at all.
+
+
+5.3 Headline Capitalization
+---------------------------
+
+Capitalization follows
+https://developer.gnome.org/hig-book/3.6/design-text-labels.html.en#layout-capitalization
+:
+* Capitalize all words in the headline, with the following exceptions:
+ Articles: a, an, the.
+ Conjunctions: and, but, for, not, so, yet ...
+ Prepositions of three or fewer letters: at, for, by, in, to ...
+* Keep headlines short and concise.