Every snippet of text should be enclosed in a block level element. The
default choice is <p>, the plain paragraph.
+<a>
+Cross-reference links in the manual are reasonably stable, since they are
+independent of the ordering number (which gets removed from the URL) and the
+pretty page title (the URL is created from the file name). So unless a file
+is renamed or moved to another sub-directory, links should be ok.
4.1 Inline markups
------------------
------------------------------------
<kbd>
-Any keys or key combinations, mouse buttons, or controllers should be marked
-with this element.
+Any keys or key combinations, mouse buttons or controllers, menu items or
+textual user input should be marked with this element. It is used here in
+the widest possible sense, qualified by classes.
E.g.:
"Press <kbd>F</kbd> to fit all tracks to the height of the Editor window."
"Move <kbd>Fader 1</kbd> on your MIDI controller to bind it.
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
====================
additional information, if at all.
-5.3 Headline Capitalization
----------------------------
+5.3 Chapter Headline Capitalization
+------------------------------------
Capitalization follows
https://developer.gnome.org/hig-book/3.6/design-text-labels.html.en#layout-capitalization
Conjunctions: and, but, for, not, so, yet ...
Prepositions of three or fewer letters: at, for, by, in, to ...
* Keep headlines short and concise.
+* secondary headlines in articles are not capitalized
+* Do not capitalize concepts in the text body, with the possible exceptions
+ of _the_ Editor and _the_ Mixer.
+
+
+5.4 Janitorial tasks/review
+---------------------------
+If you encounter something that is unclear or patent nonsense, but you are
+not bold or knowledgeable to fix it, express your doubts with an <p
+class="fixme">editorial note</p>, so that readers will be warned and fellow
+editors know where there's work to do.