NO-OP: whitespace

[ardour-manual] / STYLE_GUIDE

diff --git a/STYLE_GUIDE b/STYLE_GUIDE
index f7444967612ce51f51967ac3f5613d7162009a1d..491794cf5def497e587f675afcfcd434505ebde0 100644 (file)
--- a/STYLE_GUIDE
+++ b/STYLE_GUIDE
@@ -1,37 +1,41 @@
-*Style guide for the Ardour manual*

 
 

+*Style guide for the Ardour manual*

 
 
 1. Rationale
 ============
 
 The Ardour manual should be consistent across different media, and it should
 
 
 1. Rationale
 ============
 
 The Ardour manual should be consistent across different media, and it should

-be easily updatable when Ardour's behaviour changes. 
-The markup should be semantic - looks are determined in the CSS, and only
-there. If you feel you must compromise the markup in order to obtain a
-certain look: don't do it. Accept the look.
-Alternatively, edit the CSS, but be careful not to make matters worse
+be easily updatable when Ardour's behaviour changes. The markup should be
+semantic--looks are determined in the CSS, and only there. If you feel you must
+compromise the markup in order to obtain a certain look: don't do it. Accept
+the look. Alternatively, edit the CSS, but be careful not to make matters worse

 elsewhere.
 
 
 1.1 visual markup
 -----------------
 
 elsewhere.
 
 
 1.1 visual markup
 -----------------
 

-<b>,<i>,<u>,<font> or any other purely visual elements are not used in 
-the Ardour manual.
-What you really mean is an <em>phasis or a <strong> emphasis.
+<b>,<i>,<u>,<font> or any other purely visual elements are not used in the
+Ardour manual. What you really mean is an <em>phasis or a <strong> emphasis.

 If you feel that some special terms should always be green and underlined, the
 approach of choice is this:
 If you feel that some special terms should always be green and underlined, the
 approach of choice is this:

+

 <span class="my_important_keyword">foobar</span>
 <span class="my_important_keyword">foobar</span>

+

 and then add
 and then add

+

 .my_important_keyword {
        text-decoration: underline;
         color: #004400;
         background-color: #eeffee;
 }
 .my_important_keyword {
        text-decoration: underline;
         color: #004400;
         background-color: #eeffee;
 }

+

 to apps.css.
 to apps.css.

+

 If you add a new class with semantic meaning, document it below, under
 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
+include/about-ardour-documentation.html.

 
 
 2. Format and Validation
 
 
 2. Format and Validation


@@ -42,6 +46,13 @@ 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;".
+
+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
 =================
 
 3. Custom classes
 =================


@@ -53,12 +64,31 @@ semantic markup than core XHTML allows.
 Any XHTML element can include a class attribute. If you need to add a class
 attribute to a word or a few words which don't have an element of their own,
 use <span class="my_new_category">foo bar</span>.
 Any XHTML element can include a class attribute. If you need to add a class
 attribute to a word or a few words which don't have an element of their own,
 use <span class="my_new_category">foo bar</span>.

+

 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.
 
 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.
 

-.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 include/about-ardour-documentation.html, it serves as a style and
+markup guide.

 
 
 4. Element use
 
 
 4. Element use


@@ -69,95 +99,137 @@ create semantic classes rather than visual ones.
 ----------------------------
 
 <h1>..<h6>
 ----------------------------
 
 <h1>..<h6>

-A <h1/> heading is added by the Ruby framework, so it should not be used in
+An <h1/> heading is added by the build script, so it should not be used in

 the manual page itself. If you feel you need another <h1>, start a new
 the manual page itself. If you feel you need another <h1>, start a new

-subpage.
-Heading levels must not be skipped. Any sub-heading must be exactly one
-level below its predecessor. Do not abuse headings to style a head line.
+subpage. Heading levels must not be skipped. Any sub-heading must be exactly
+one level below its predecessor. Do not abuse headings to style a head line.

 
 <p>
 Every snippet of text should be enclosed in a block level element. The
 default choice is <p>, the plain paragraph.
 
 
 <p>
 Every snippet of text should be enclosed in a block level element. The
 default choice is <p>, the plain paragraph.
 

+<a>
+Internal manual links should be absolutely stable, as long as the references in
+the master document do not change (and they absolutely *should* not be changed
+except for a *very* good reason, even then they probably should not be
+changed!). Use the form:
+
+<a href="@@my-internal-link">
+
+where @@my-internal-link is a reference to a "link:" keyword in a header in the
+master document. Note that in the master document, they will not have the
+double at-sign ("@@") in front, that is *only* used in the page content to
+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>
 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
 ------------------
 
 <dfn>
 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.
+of a new concept after a sub-heading if necessary. Renders in bold face. Keep
+in mind that <dfn> tags might be used to generate an index of keywords--don't
+pollute it too much.

 
 <abbr>
 
 <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.
+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. Renders as dotted underlined in most
+browsers. 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>
 
 <em>

-is used to emphasize a word. Commonly rendered as italics.
-Use only if its a truly ad-hoc, one-off situation. For anything else,
-consider adding a new semantic markup with <span class="foo">.
+is used to emphasize a word. Commonly rendered as italics. Use only if its a
+truly ad-hoc, one-off situation. For anything else, consider adding a new
+semantic markup with <span class="foo">.

 
 <strong>
 
 <strong>

-is used to strongly emphasize a word. Commonly rendered in bold.
-See above for usage.
+is used to strongly emphasize a word. Commonly rendered in bold. See above for
+usage.

 
 

-<br />
-A line-break can sometimes be used to structure a paragraph, or to split a
-longish heading. Never use spurious <br/>s at the end of paragraphs or to
-control the spacing of sections. If you're unhappy with those, fix the CSS
-(which fixes the entire manual in one go!)
+<br>
+Most of the time, these should be avoided, and used very infrequently. A line-
+break can sometimes be used to structure a paragraph, or to split a longish
+heading. Never use spurious <br>s at the end of paragraphs or to control the
+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>
+<ul>, <ol>

 Use the unordered list for information snippets that do not have an implied
 order. The ordered list should always be used when a sequence of actions is
 Use the unordered list for information snippets that do not have an implied
 order. The ordered list should always be used when a sequence of actions is

-described. Within the lists, each item must be enclosed in <li> tags.
-Lists cannot be included in <p>aragraphs. Close the paragraph first.
+described. Within the lists, each item must be enclosed in <li> tags. Lists
+cannot be included in <p>aragraphs. Close the paragraph first.

 
 <dl>
 Definition lists are for technical terms <dt> and their definition <dd>. Do
 not abuse them for anything else.
 
 
 
 <dl>
 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>
 --------------
 
 <blockquote>

-is used when an entire paragraph is quoted. Must contain a
-cite="http://mysource.net/foo.pdf" attribute. Do not abuse to indent a
-paragraph!
+is used when an entire paragraph is quoted. Must contain a cite="http://
+mysource.net/foo.pdf" attribute. Do not abuse to indent a paragraph!

 
 

-<cite>,<q>
-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>.
+<cite>, <q>
+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>
 
 <kbd>

-Any keys or key combinations, mouse buttons, or controllers  should be marked
-with this element. 
-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.
-"
+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."
+

 Since modifier keys are not cross-platform and Ardour makes a point of 
 abstracting them, do not hard-code "Alt", "Cmd" and friends, use 
 Since modifier keys are not cross-platform and Ardour makes a point of 
 abstracting them, do not hard-code "Alt", "Cmd" and friends, use 

+

        class="modN" 
        class="modN" 

+

 instead.
 instead.

+

 So if you want the user to press Ctrl-N on Linux, that's actually <kbd
 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, uh?
+class="mod1">N</kbd>. It will render as "Ctrl N" for you, and as "Cmd N" for
+your Mac-using friend. Nice, huh?
+
+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.
 
 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 entered lowercase, even though the
+stylesheet might capitalize them.
+
+CSS Classes used with <kbd> are:
+
+.modN, .modNM, .modNn, .modNMn
+.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


@@ -168,25 +240,104 @@ is only used for the textual output of any code, never for anything the user
 types or presses.
 
 
 types or presses.
 
 

-4.5 Images
+4.6 Images

 ----------
 
 <img>
 The image tag must contain a 'src="/images/yourimage.png"' element and a
 ----------
 
 <img>
 The image tag must contain a 'src="/images/yourimage.png"' element and a

-descriptive 'alt="A short textual description of the image content"'
-element.
+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. 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.
 
 * 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.
 * Do not hyphenate words at line breaks.

-* For breaks in thought &mdash; such as this splendid example &mdash; use
-  the long em-dash.
-* For ranges of values, use the en-dash: Monday &ndash; Friday, 0 &ndash;
-  11.
+* 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
+  sides--this is the proper way to use them.
+* For ranges of values, use the en-dash: Monday&ndash;Friday, 0&ndash;11. Note
+  again, the en-dash is snugged up to its surrounding elements.
+* Use a non-breaking space ("&nbsp;") between a number and its unit.
+* Colons (":") always snug up to their text on the left: it is an error to add
+  space between text on the left and the colon.
+
+
+5.2 Language
+------------
+
+* The Ardour manual is written in American English spelling.
+* Use SI units with standard abbreviations. Give imperial units only as
+  additional information, if at all.
+* Do not use contractions like "it'll", always write full forms.
+* Do not over-use "You"; write about the program, not the user. Avoid it if at 
+  all possible, it makes for tighter and better reading text.
+* Always write out numbers less than 11. E.g., "One or two ..." instead of
+  "1 or 2 ...".
+
+
+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.
+
+
+5.5 Writing style suggestions
+-----------------------------
+
+* "Click OK" and similar explanations of the utterly obvious should be
+  avoided. Keep the writing concise and to the point. Explain as much as
+  possible, with as few words as possible.
+* Do not fear repetitions, this is not artistic prose. Repeat important 
+  keywords, rather than burden the user with synonyms made up on the spot.
+* Do not create headings for different ways of doing the same thing (<h>Via
+  the context menu</h>,...<h>Via hotkeys</h>). Headings separate new
+  concepts. To not add gratuitous sub-headings if there is very little
+  content per heading and you do not expect the article to grow.
+* If pages grow long, consider splitting them into sub-chapters at their
+  headings.
+* Nobody needs "the next paragraph is about the following" paragraphs.
+* When creating a <p class="note">NOTE</p>, *do not* put the word NOTE into
+  the note, the styling tells the user that it is a note.
+
+
+5.6. Encoding
+-------------
+
+* Pages should be encoded in UTF-8, with Unix-style newlines if possible
+  (although that's not critical). Avoid using verbatim special symbols, use
+  HTML character entities instead, for example for cursor arrows: &rarr;
+  &larr; &uarr; &darr;. Diacriticals on vowels and other special letters are
+  probably ok by now, so don't bother with &eacute; and friends, just type é.