X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=STYLE_GUIDE;h=491794cf5def497e587f675afcfcd434505ebde0;hb=a1e84930287265d6e474a3ca57f4df40a1106256;hp=af78e989efa8cae5b85a68c70fb555576519e56f;hpb=e6123839d20de4f903ed74820cc087fc8401f625;p=ardour-manual

diff --git a/STYLE_GUIDE b/STYLE_GUIDE
index af78e98..491794c 100644
--- a/STYLE_GUIDE
+++ b/STYLE_GUIDE
@@ -50,6 +50,9 @@ 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;".
 
+Keep line lengths within 108 characters so that additions or changes are easy to view in github pull requests.
+Code examples that are supposed to be all one line are an exception in which case the <pre></pre> tag should be
+used to to tell the browser to display the code as one line.
 
 3. Custom classes
 =================
@@ -120,7 +123,7 @@ signal to the build system that it is an internal link that needs to be fixed
 so that it points to the correct URL.
 
 
-4.1 Inline markups
+4.2 Inline markups
 ------------------
 
 <dfn>
@@ -156,7 +159,7 @@ spacing of sections. If you're unhappy with those, fix the CSS (which fixes the
 entire manual in one go!).
 
 
-4.2 Lists
+4.3 Lists
 ---------
 
 <ul>, <ol>
@@ -170,7 +173,7 @@ Definition lists are for technical terms <dt> and their definition <dd>. Do
 not abuse them for anything else.
 
 
-4.3 Quotations
+4.4 Quotations
 --------------
 
 <blockquote>
@@ -182,7 +185,7 @@ For inline citations, the <cite>W3C</cite> recommends to <q cite="http://
 www.w3.org/TR/xhtml1/dtds.html">use the cite and q elements</q>.
 
 
-4.4 Keyboard/Controller interaction
+4.5 Keyboard/Controller interaction
 -----------------------------------
 
 <kbd>
@@ -204,8 +207,10 @@ So if you want the user to press Ctrl-N on Linux, that's actually <kbd
 class="mod1">N</kbd>. It will render as "Ctrl N" for you, and as "Cmd N" for
 your Mac-using friend. Nice, huh?
 
-N.B.: If you want to have just the name of the modifier key by itself, use
-<kbd class="mod1>&zwnj;</kbd> (zero-width non-joiner).
+Multiple modifier keys are supported as "modNM" as well, so for Ctrl-Shift-N on Linux, you would use "mod13".
+
+N.B.: If you want to have just the name of the modifier key by itself, use the
+      modN name followed by a lower case "n", like so: <kbd class="mod1n></kbd>
 
 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
@@ -216,7 +221,7 @@ stylesheet might capitalize them.
 
 CSS Classes used with <kbd> are:
 
-.modN
+.modN, .modNM, .modNn, .modNMn
 .mouse: mouse buttons
 .cmd: a command line
 .lin, .win, .mac: add nice prompts to that command line
@@ -235,7 +240,7 @@ is only used for the textual output of any code, never for anything the user
 types or presses.
 
 
-4.5 Images
+4.6 Images
 ----------
 
 <img>
@@ -244,6 +249,10 @@ 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,
 unless they are no higher than one row and make sense in the text flow.
 
+Images should also be wrapped (unless they are embedded inside a paragraph) in
+a <figure></figure> block, and should contain a <figcaption></figcaption> block
+inside as well to describe to the reader what the image is.
+
 
 5. Other conventions
 ====================
@@ -254,7 +263,7 @@ unless they are no higher than one row and make sense in the text flow.
 
 * Avoid any typographical quotation marks to highlight terms or express any
   kind of subtle inflection, use semantic markup instead.
-* The hyphen is used to for compound words such as this well-advised example.
+* The hyphen is used for compound words such as this well-advised example.
 * Do not hyphenate words at line breaks.
 * For breaks in thought&mdash;such as this splendid example&mdash;use the long
   em-dash. Note that the em-dash is snugged up against the text on both