X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=STYLE_GUIDE;h=7568a1f6fe5ede6cc1f33d411c42991410653222;hb=bcd15d4ba5093d128f5ab6c0526272148a766ca0;hp=f7444967612ce51f51967ac3f5613d7162009a1d;hpb=f6c0d65cd832fce3a6f4ae166a1e410792f23338;p=ardour-manual-diverged diff --git a/STYLE_GUIDE b/STYLE_GUIDE index f744496..7568a1f 100644 --- 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 @@ -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. +Watch out for the ampersand "&" and angle brackets "<" and ">". They will +render your XHTML invalid, and must be replaced by their named entities +"&", "<", and ">". + 3. Custom classes ================= @@ -57,8 +62,22 @@ If you need to apply a class to several block-level elements such as paragraphs or lists, enclose them in a
, 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.
+Keep in mind that tags might be used to generate an index of keywords
+- don't pollute it too much.
is used to explain an abbreviation such as LADSPA. 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.
is used to emphasize a word. Commonly rendered as italics.
@@ -158,6 +181,8 @@ class="mod1">N. 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 as a block-level element.
+See above for other classes to denote menu items, selections, mouse
+events and controller actions.
is only used for program code, or the content of configuration files etc. Do
@@ -177,8 +202,12 @@ descriptive 'alt="A short textual description of the image content"'
element.
-5. Typography
-=============
+5. Other conventions
+====================
+
+
+5.1 Typography
+--------------
* Avoid any typographical quotation marks to highlight terms or express any
kind of subtle inflection, use semantic markup instead.
@@ -188,5 +217,27 @@ element.
the long em-dash.
* For ranges of values, use the en-dash: Monday – Friday, 0 –
11.
+* Use a non-breaking space (" ") 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.