copy-editing chapter 8.

[ardour-manual] / STYLE_GUIDE

diff --git a/STYLE_GUIDE b/STYLE_GUIDE
index e991b7c93872bef2d5eb5e1e5fb66c89aaf62500..7d2dad4ee7db2489a6d13d079d13917bb792c442 100644 (file)
--- a/STYLE_GUIDE
+++ b/STYLE_GUIDE
@@ -102,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.
 
 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
 ------------------
 
 4.1 Inline markups
 ------------------


@@ -170,8 +175,9 @@ elements</q>.
 ------------------------------------
 
 <kbd>
 ------------------------------------
 
 <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.
 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.


@@ -191,6 +197,18 @@ 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.
 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.
 <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.


@@ -207,7 +225,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.
 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. Other conventions
 ====================


@@ -235,8 +254,8 @@ element.
   additional information, if at all.
 
 
   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
 
 Capitalization follows
 https://developer.gnome.org/hig-book/3.6/design-text-labels.html.en#layout-capitalization


@@ -247,4 +266,15 @@ https://developer.gnome.org/hig-book/3.6/design-text-labels.html.en#layout-capit
     Conjunctions: and, but, for, not, so, yet ...
     Prepositions of three or fewer letters: at, for, by, in, to ...
 * Keep headlines short and concise.
     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.