finish copy-editing of chapter 4.

[ardour-manual] / STYLE_GUIDE

diff --git a/STYLE_GUIDE b/STYLE_GUIDE
index f7444967612ce51f51967ac3f5613d7162009a1d..5c367ab6dc3cf519f250c625c1fec5842ef4d918 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
 }
 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
 
 
 2. Format and Validation


@@ -42,6 +43,10 @@ be valid XML, with all tags closed properly. The reason for this extra
 complication is that XML can be more easily checked and automatically
 refactored than plain HTML, which eases maintenance.
 
 complication is that XML can be more easily checked and automatically
 refactored than plain HTML, which eases maintenance.
 

+Watch out for the ampersand "&" and angle brackets "<" and ">". They will
+render your XHTML invalid, and must be replaced by their named entities
+"&amp;", "&lt;", and "&gt;".
+

 
 3. Custom classes
 =================
 
 3. Custom classes
 =================


@@ -57,8 +62,26 @@ If you need to apply a class to several block-level elements such as
 paragraphs or lists, enclose them in a <div>..</div>. Wherever possible,
 create semantic classes rather than visual ones.
 
 paragraphs or lists, enclose them in a <div>..</div>. Wherever possible,
 create semantic classes rather than visual ones.
 

-.left: make an element float left in the surrounding paragraph.
-.right: make an element float right in the surrounding paragraph.
+.left: 
+make an element float left in the surrounding paragraph.
+
+.right: 
+make an element float right in the surrounding paragraph.
+
+.note: 
+use for important notes that should be visually distinct from the
+normal text flow, or asides. Currently rendered in a gray box.
+
+.warning:
+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.

 
 
 4. Element use
 
 
 4. Element use


@@ -87,13 +110,17 @@ default choice is <p>, the plain paragraph.
 encloses a newly introduced term that is being explained. Use for the first
 occurrence of the main concept of every manual page, or the first occurrence
 of a new concept after a sub-heading if necessary.
 encloses a newly introduced term that is being explained. Use for the first
 occurrence of the main concept of every manual page, or the first occurrence
 of a new concept after a sub-heading if necessary.

+Keep in mind that <dfn> tags might be used to generate an index of keywords
+- don't pollute it too much.

 
 <abbr>
 is used to explain an abbreviation such as <abbr title="Linux Audio
 Developers Simple Plugin API">LADSPA</abbr>. Browsers will usually pop up the
 
 <abbr>
 is used to explain an abbreviation such as <abbr title="Linux Audio
 Developers Simple Plugin API">LADSPA</abbr>. Browsers will usually pop up the

-definition when the user hovers over the word, and it can easily be
-extracted via CSS for printing.
-Use only for the first occurrence of every new abbreviation.
+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.
 
 <em>
 is used to emphasize a word. Commonly rendered as italics.


@@ -158,6 +185,23 @@ class="mod1">N</kbd>. It will render as "Ctrl+N" for you, and as "Cmd+N" for
 your Mac-using friend. Nice, uh?
 
 For anything you want the user to type, use <kbd> as a block-level element.
 your Mac-using friend. Nice, uh?
 
 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
 
 <code>
 is only used for program code, or the content of configuration files etc. Do


@@ -175,10 +219,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.
 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.
 
 * Avoid any typographical quotation marks to highlight terms or express any
   kind of subtle inflection, use semantic markup instead.


@@ -188,5 +237,27 @@ element.
   the long em-dash.
 * For ranges of values, use the en-dash: Monday &ndash; Friday, 0 &ndash;
   11.
   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 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.