copy-editing chapter 8.

[ardour-manual] / STYLE_GUIDE

diff --git a/STYLE_GUIDE b/STYLE_GUIDE
index f6101bbe4961e8a719b3efbb38abe8cc402ef0f6..7d2dad4ee7db2489a6d13d079d13917bb792c442 100644 (file)
--- a/STYLE_GUIDE
+++ b/STYLE_GUIDE
@@ -31,7 +31,8 @@ and then add
 }
 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
@@ -75,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.
 
@@ -97,6 +102,11 @@ level below its predecessor. Do not abuse headings to style a head line.
 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
 ------------------
@@ -115,6 +125,7 @@ definition when the user hovers over the word.
 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.
@@ -164,8 +175,9 @@ elements</q>.
 ------------------------------------
 
 <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.
@@ -182,6 +194,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.
@@ -198,10 +225,15 @@ 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
+====================
 
-5. Typography
-=============
+
+5.1 Typography
+--------------
 
 * Avoid any typographical quotation marks to highlight terms or express any
   kind of subtle inflection, use semantic markup instead.
@@ -211,5 +243,38 @@ element.
   the long em-dash.
 * For ranges of values, use the en-dash: Monday &ndash; Friday, 0 &ndash;
   11.
+* Use a non-breaking space ("&nbsp;") 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 Chapter 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.
+* 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.