copy-editing chapter 5.

[ardour-manual-diverged] / STYLE_GUIDE

diff --git a/STYLE_GUIDE b/STYLE_GUIDE
index 7568a1f6fe5ede6cc1f33d411c42991410653222..5c367ab6dc3cf519f250c625c1fec5842ef4d918 100644 (file)
--- a/STYLE_GUIDE
+++ b/STYLE_GUIDE
@@ -76,6 +76,10 @@ normal text flow, or asides. Currently rendered in a gray box.
 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.
 
@@ -184,6 +188,21 @@ For anything you want the user to type, use <kbd> as a block-level element.
 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.
@@ -200,7 +219,8 @@ types or presses.
 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
 ====================