Shamusworld >> Repos - ardour-manual/blob - STYLE_GUIDE

   1 *Style guide for the Ardour manual*
   2
   3
   4
   5 1. Rationale
   6 ============
   7
   8 The Ardour manual should be consistent across different media, and it should
   9 be easily updatable when Ardour's behaviour changes.
  10 The markup should be semantic - looks are determined in the CSS, and only
  11 there. If you feel you must compromise the markup in order to obtain a
  12 certain look: don't do it. Accept the look.
  13 Alternatively, edit the CSS, but be careful not to make matters worse
  14 elsewhere.
  15
  16
  17 1.1 visual markup
  18 -----------------
  19
  20 <b>,<i>,<u>,<font> or any other purely visual elements are not used in
  21 the Ardour manual.
  22 What you really mean is an <em>phasis or a <strong> emphasis.
  23 If you feel that some special terms should always be green and underlined, the
  24 approach of choice is this:
  25 <span class="my_important_keyword">foobar</span>
  26 and then add
  27 .my_important_keyword {
  28         text-decoration: underline;
  29         color: #004400;
  30         background-color: #eeffee;
  31 }
  32 to apps.css.
  33 If you add a new class with semantic meaning, document it below, under
  34 "Custom classes", and be sure to explain it to the reader at
  35 _manual/01_welcome-to-ardour/02_about-ardour-documentation.html.
  36
  37
  38 2. Format and Validation
  39 ========================
  40
  41 The Ardour manual has been converted to valid XHTML 1.0. That means it must
  42 be valid XML, with all tags closed properly. The reason for this extra
  43 complication is that XML can be more easily checked and automatically
  44 refactored than plain HTML, which eases maintenance.
  45
  46 Watch out for the ampersand "&" and angle brackets "<" and ">". They will
  47 render your XHTML invalid, and must be replaced by their named entities
  48 "&amp;", "&lt;", and "&gt;".
  49
  50
  51 3. Custom classes
  52 =================
  53
  54 We use the class attribute for some aspects of styling (such as to float an
  55 image left or right in a text paragraph), and also for more fine-grained
  56 semantic markup than core XHTML allows.
  57
  58 Any XHTML element can include a class attribute. If you need to add a class
  59 attribute to a word or a few words which don't have an element of their own,
  60 use <span class="my_new_category">foo bar</span>.
  61 If you need to apply a class to several block-level elements such as
  62 paragraphs or lists, enclose them in a <div>..</div>. Wherever possible,
  63 create semantic classes rather than visual ones.
  64
  65 .left:
  66 make an element float left in the surrounding paragraph.
  67
  68 .right:
  69 make an element float right in the surrounding paragraph.
  70
  71 .note:
  72 use for important notes that should be visually distinct from the
  73 normal text flow, or asides. Currently rendered in a gray box.
  74
  75 .warning:
  76 use for potentially dangerous situations involving data loss, malfunction,
  77 or sound quality issues. Currently rendered in a red box.
  78
  79 .mac, .lin, .win:
  80 use as additional classes to mark a section as relevant for these operating
  81 systems only.
  82
  83 Check _manual/01_welcome-to-ardour/02_about-ardour-documentation.html, it
  84 serves as a style and markup guide.
  85
  86
  87 4. Element use
  88 ==============
  89
  90
  91 4.1 Main structural elements
  92 ----------------------------
  93
  94 <h1>..<h6>
  95 A <h1/> heading is added by the Ruby framework, so it should not be used in
  96 the manual page itself. If you feel you need another <h1>, start a new
  97 subpage.
  98 Heading levels must not be skipped. Any sub-heading must be exactly one
  99 level below its predecessor. Do not abuse headings to style a head line.
 100
 101 <p>
 102 Every snippet of text should be enclosed in a block level element. The
 103 default choice is <p>, the plain paragraph.
 104
 105
 106 4.1 Inline markups
 107 ------------------
 108
 109 <dfn>
 110 encloses a newly introduced term that is being explained. Use for the first
 111 occurrence of the main concept of every manual page, or the first occurrence
 112 of a new concept after a sub-heading if necessary.
 113 Keep in mind that <dfn> tags might be used to generate an index of keywords
 114 - don't pollute it too much.
 115
 116 <abbr>
 117 is used to explain an abbreviation such as <abbr title="Linux Audio
 118 Developers Simple Plugin API">LADSPA</abbr>. Browsers will usually pop up the
 119 definition when the user hovers over the word.
 120 On each page, use only for the first occurrence of every abbreviation. Avoid
 121 a redundant explanation in the text - the expansion can easily be extracted
 122 via CSS for printing.
 123 Use only in the text body, not in headings.
 124
 125 <em>
 126 is used to emphasize a word. Commonly rendered as italics.
 127 Use only if its a truly ad-hoc, one-off situation. For anything else,
 128 consider adding a new semantic markup with <span class="foo">.
 129
 130 <strong>
 131 is used to strongly emphasize a word. Commonly rendered in bold.
 132 See above for usage.
 133
 134 <br />
 135 A line-break can sometimes be used to structure a paragraph, or to split a
 136 longish heading. Never use spurious <br/>s at the end of paragraphs or to
 137 control the spacing of sections. If you're unhappy with those, fix the CSS
 138 (which fixes the entire manual in one go!)
 139
 140
 141 4.2 Lists
 142 ---------
 143
 144 <ul>,<ol>
 145 Use the unordered list for information snippets that do not have an implied
 146 order. The ordered list should always be used when a sequence of actions is
 147 described. Within the lists, each item must be enclosed in <li> tags.
 148 Lists cannot be included in <p>aragraphs. Close the paragraph first.
 149
 150 <dl>
 151 Definition lists are for technical terms <dt> and their definition <dd>. Do
 152 not abuse them for anything else.
 153
 154
 155 4.3 Quotations
 156 --------------
 157
 158 <blockquote>
 159 is used when an entire paragraph is quoted. Must contain a
 160 cite="http://mysource.net/foo.pdf" attribute. Do not abuse to indent a
 161 paragraph!
 162
 163 <cite>,<q>
 164 For inline citations, the <cite>W3C</cite> recommends to <q
 165 cite="http://www.w3.org/TR/xhtml1/dtds.html">use the cite and q
 166 elements</q>.
 167
 168
 169 4.4 Keyboard/Controller  interaction
 170 ------------------------------------
 171
 172 <kbd>
 173 Any keys or key combinations, mouse buttons, or controllers  should be marked
 174 with this element.
 175 E.g.:
 176 "Press <kbd>F</kbd> to fit all tracks to the height of the Editor window."
 177 "Move <kbd>Fader 1</kbd> on your MIDI controller to bind it.
 178 "
 179 Since modifier keys are not cross-platform and Ardour makes a point of
 180 abstracting them, do not hard-code "Alt", "Cmd" and friends, use
 181         class="modN"
 182 instead.
 183 So if you want the user to press Ctrl-N on Linux, that's actually <kbd
 184 class="mod1">N</kbd>. It will render as "Ctrl+N" for you, and as "Cmd+N" for
 185 your Mac-using friend. Nice, uh?
 186
 187 For anything you want the user to type, use <kbd> as a block-level element.
 188 See above for other <kbd> classes to denote menu items, selections, mouse
 189 events and controller actions.
 190
 191 Keys and mouse key names should always be capitalized. We do not need to
 192 distringuish between "x" and "X", because the latter would be "Shift-X".
 193 In case you forget, the stylesheet takes care of this.
 194 <code>
 195 is only used for program code, or the content of configuration files etc. Do
 196 not abuse to style keys or user input, use <kbd> instead.
 197
 198 <samp>
 199 is only used for the textual output of any code, never for anything the user
 200 types or presses.
 201
 202
 203 4.5 Images
 204 ----------
 205
 206 <img>
 207 The image tag must contain a 'src="/images/yourimage.png"' element and a
 208 descriptive 'alt="A short textual description of the image content"'
 209 element.
 210
 211
 212 5. Other conventions
 213 ====================
 214
 215
 216 5.1 Typography
 217 --------------
 218
 219 * Avoid any typographical quotation marks to highlight terms or express any
 220   kind of subtle inflection, use semantic markup instead.
 221 * The hyphen is used to for compound words such as this well-advised example.
 222 * Do not hyphenate words at line breaks.
 223 * For breaks in thought &mdash; such as this splendid example &mdash; use
 224   the long em-dash.
 225 * For ranges of values, use the en-dash: Monday &ndash; Friday, 0 &ndash;
 226   11.
 227 * Use a non-breaking space ("&nbsp;") between a number and its unit.
 228
 229
 230 5.2 Language
 231 ------------
 232
 233 * The Ardour manual is written in Americal English spelling.
 234 * Use SI units with standard abbreviations. Give imperial units only as
 235   additional information, if at all.
 236
 237
 238 5.3 Headline Capitalization
 239 ---------------------------
 240
 241 Capitalization follows
 242 https://developer.gnome.org/hig-book/3.6/design-text-labels.html.en#layout-capitalization
 243 :
 244
 245 * Capitalize all words in the headline, with the following exceptions:
 246     Articles: a, an, the.
 247     Conjunctions: and, but, for, not, so, yet ...
 248     Prepositions of three or fewer letters: at, for, by, in, to ...
 249 * Keep headlines short and concise.
 250