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".
  35
  36
  37 2. Format and Validation
  38 ========================
  39
  40 The Ardour manual has been converted to valid XHTML 1.0. That means it must
  41 be valid XML, with all tags closed properly. The reason for this extra
  42 complication is that XML can be more easily checked and automatically
  43 refactored than plain HTML, which eases maintenance.
  44
  45 Watch out for the ampersand "&" and angle brackets "<" and ">". They will
  46 render your XHTML invalid, and must be replaced by their named entities
  47 "&amp;", "&lt;", and "&gt;".
  48
  49
  50 3. Custom classes
  51 =================
  52
  53 We use the class attribute for some aspects of styling (such as to float an
  54 image left or right in a text paragraph), and also for more fine-grained
  55 semantic markup than core XHTML allows.
  56
  57 Any XHTML element can include a class attribute. If you need to add a class
  58 attribute to a word or a few words which don't have an element of their own,
  59 use <span class="my_new_category">foo bar</span>.
  60 If you need to apply a class to several block-level elements such as
  61 paragraphs or lists, enclose them in a <div>..</div>. Wherever possible,
  62 create semantic classes rather than visual ones.
  63
  64 .left:
  65 make an element float left in the surrounding paragraph.
  66
  67 .right:
  68 make an element float right in the surrounding paragraph.
  69
  70 .note:
  71 use for important notes that should be visually distinct from the
  72 normal text flow, or asides. Currently rendered in a gray box.
  73
  74 .warning:
  75 use for potentially dangerous situations involving data loss, malfunction,
  76 or sound quality issues. Currently rendered in a red box.
  77
  78
  79 4. Element use
  80 ==============
  81
  82
  83 4.1 Main structural elements
  84 ----------------------------
  85
  86 <h1>..<h6>
  87 A <h1/> heading is added by the Ruby framework, so it should not be used in
  88 the manual page itself. If you feel you need another <h1>, start a new
  89 subpage.
  90 Heading levels must not be skipped. Any sub-heading must be exactly one
  91 level below its predecessor. Do not abuse headings to style a head line.
  92
  93 <p>
  94 Every snippet of text should be enclosed in a block level element. The
  95 default choice is <p>, the plain paragraph.
  96
  97
  98 4.1 Inline markups
  99 ------------------
 100
 101 <dfn>
 102 encloses a newly introduced term that is being explained. Use for the first
 103 occurrence of the main concept of every manual page, or the first occurrence
 104 of a new concept after a sub-heading if necessary.
 105
 106 <abbr>
 107 is used to explain an abbreviation such as <abbr title="Linux Audio
 108 Developers Simple Plugin API">LADSPA</abbr>. Browsers will usually pop up the
 109 definition when the user hovers over the word, and it can easily be
 110 extracted via CSS for printing.
 111 Use only for the first occurrence of every new abbreviation.
 112
 113 <em>
 114 is used to emphasize a word. Commonly rendered as italics.
 115 Use only if its a truly ad-hoc, one-off situation. For anything else,
 116 consider adding a new semantic markup with <span class="foo">.
 117
 118 <strong>
 119 is used to strongly emphasize a word. Commonly rendered in bold.
 120 See above for usage.
 121
 122 <br />
 123 A line-break can sometimes be used to structure a paragraph, or to split a
 124 longish heading. Never use spurious <br/>s at the end of paragraphs or to
 125 control the spacing of sections. If you're unhappy with those, fix the CSS
 126 (which fixes the entire manual in one go!)
 127
 128
 129 4.2 Lists
 130 ---------
 131
 132 <ul>,<ol>
 133 Use the unordered list for information snippets that do not have an implied
 134 order. The ordered list should always be used when a sequence of actions is
 135 described. Within the lists, each item must be enclosed in <li> tags.
 136 Lists cannot be included in <p>aragraphs. Close the paragraph first.
 137
 138 <dl>
 139 Definition lists are for technical terms <dt> and their definition <dd>. Do
 140 not abuse them for anything else.
 141
 142
 143 4.3 Quotations
 144 --------------
 145
 146 <blockquote>
 147 is used when an entire paragraph is quoted. Must contain a
 148 cite="http://mysource.net/foo.pdf" attribute. Do not abuse to indent a
 149 paragraph!
 150
 151 <cite>,<q>
 152 For inline citations, the <cite>W3C</cite> recommends to <q
 153 cite="http://www.w3.org/TR/xhtml1/dtds.html">use the cite and q
 154 elements</q>.
 155
 156
 157 4.4 Keyboard/Controller  interaction
 158 ------------------------------------
 159
 160 <kbd>
 161 Any keys or key combinations, mouse buttons, or controllers  should be marked
 162 with this element.
 163 E.g.:
 164 "Press <kbd>F</kbd> to fit all tracks to the height of the Editor window."
 165 "Move <kbd>Fader 1</kbd> on your MIDI controller to bind it.
 166 "
 167 Since modifier keys are not cross-platform and Ardour makes a point of
 168 abstracting them, do not hard-code "Alt", "Cmd" and friends, use
 169         class="modN"
 170 instead.
 171 So if you want the user to press Ctrl-N on Linux, that's actually <kbd
 172 class="mod1">N</kbd>. It will render as "Ctrl+N" for you, and as "Cmd+N" for
 173 your Mac-using friend. Nice, uh?
 174
 175 For anything you want the user to type, use <kbd> as a block-level element.
 176
 177 <code>
 178 is only used for program code, or the content of configuration files etc. Do
 179 not abuse to style keys or user input, use <kbd> instead.
 180
 181 <samp>
 182 is only used for the textual output of any code, never for anything the user
 183 types or presses.
 184
 185
 186 4.5 Images
 187 ----------
 188
 189 <img>
 190 The image tag must contain a 'src="/images/yourimage.png"' element and a
 191 descriptive 'alt="A short textual description of the image content"'
 192 element.
 193
 194
 195 5. Typography
 196 =============
 197
 198 * Avoid any typographical quotation marks to highlight terms or express any
 199   kind of subtle inflection, use semantic markup instead.
 200 * The hyphen is used to for compound words such as this well-advised example.
 201 * Do not hyphenate words at line breaks.
 202 * For breaks in thought &mdash; such as this splendid example &mdash; use
 203   the long em-dash.
 204 * For ranges of values, use the en-dash: Monday &ndash; Friday, 0 &ndash;
 205   11.
 206
 207