Documenting the 5.6 toolbar changes

[ardour-manual] / STYLE_GUIDE

diff --git a/STYLE_GUIDE b/STYLE_GUIDE
index 7568a1f6fe5ede6cc1f33d411c42991410653222..09f7a6c51e43b352f12557d6283bb76f7b038a01 100644 (file)
--- a/STYLE_GUIDE
+++ b/STYLE_GUIDE
@@ -76,6 +76,10 @@ normal text flow, or asides. Currently rendered in a gray box.
 use for potentially dangerous situations involving data loss, malfunction,
 or sound quality issues. Currently rendered in a red box.
 
 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.
 
 Check _manual/01_welcome-to-ardour/02_about-ardour-documentation.html, it
 serves as a style and markup guide.
 


@@ -98,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
 ------------------


@@ -105,16 +114,17 @@ default choice is <p>, the plain paragraph.
 <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.
-Keep in mind that <dfn> tags might be used to generate an index of keywords
-- don't pollute it too much.
+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>
 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.
+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
 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 
+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.
 
 via CSS for printing.
 Use only in the text body, not in headings.
 


@@ -128,6 +138,7 @@ is used to strongly emphasize a word. Commonly rendered in bold.
 See above for usage.
 
 <br />
 See above for usage.
 
 <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
 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


@@ -166,10 +177,11 @@ 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.:
 E.g.:

-"Press <kbd>F</kbd> to fit all tracks to the height of the Editor window."
+"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 
 "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 


@@ -177,13 +189,30 @@ abstracting them, do not hard-code "Alt", "Cmd" and friends, use
        class="modN" 
 instead.
 So if you want the user to press Ctrl-N on Linux, that's actually <kbd
        class="modN" 
 instead.
 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
+class="mod1">N</kbd>. It will render as "Ctrl N" for you, and as "Cmd N" for

 your Mac-using friend. Nice, uh?
 
 your Mac-using friend. Nice, uh?
 

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

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


@@ -200,7 +229,10 @@ 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, unless they are no higher than one row and make sense in the text
+flow. Aside from this exception, they should *always* be wrapped inside of a
+<p></p> block.

 
 5. Other conventions
 ====================
 
 5. Other conventions
 ====================


@@ -213,23 +245,31 @@ element.
   kind of subtle inflection, use semantic markup instead.
 * The hyphen is used to for compound words such as this well-advised example.
 * Do not hyphenate words at line breaks.
   kind of subtle inflection, use semantic markup instead.
 * The hyphen is used to 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.
-* 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.
 * 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
 ------------
 
 
 
 5.2 Language
 ------------
 

-* The Ardour manual is written in Americal English spelling.
+* 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.
 * 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 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


@@ -240,4 +280,43 @@ 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.
+
+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 é.