1 *Style guide for the Ardour manual*
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
20 <b>,<i>,<u>,<font> or any other purely visual elements are not used in
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>
27 .my_important_keyword {
28 text-decoration: underline;
30 background-color: #eeffee;
33 If you add a new class with semantic meaning, document it below, under
37 2. Format and Validation
38 ========================
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.
49 We use the class attribute for some aspects of styling (such as to float an
50 image left or right in a text paragraph), and also for more fine-grained
51 semantic markup than core XHTML allows.
53 Any XHTML element can include a class attribute. If you need to add a class
54 attribute to a word or a few words which don't have an element of their own,
55 use <span class="my_new_category">foo bar</span>.
56 If you need to apply a class to several block-level elements such as
57 paragraphs or lists, enclose them in a <div>..</div>. Wherever possible,
58 create semantic classes rather than visual ones.
60 .left: make an element float left in the surrounding paragraph.
61 .right: make an element float right in the surrounding paragraph.
68 4.1 Main structural elements
69 ----------------------------
72 A <h1/> heading is added by the Ruby framework, so it should not be used in
73 the manual page itself. If you feel you need another <h1>, start a new
75 Heading levels must not be skipped. Any sub-heading must be exactly one
76 level below its predecessor. Do not abuse headings to style a head line.
79 Every snippet of text should be enclosed in a block level element. The
80 default choice is <p>, the plain paragraph.
87 encloses a newly introduced term that is being explained. Use for the first
88 occurrence of the main concept of every manual page, or the first occurrence
89 of a new concept after a sub-heading if necessary.
92 is used to explain an abbreviation such as <abbr title="Linux Audio
93 Developers Simple Plugin API">LADSPA</abbr>. Browsers will usually pop up the
94 definition when the user hovers over the word, and it can easily be
95 extracted via CSS for printing.
96 Use only for the first occurrence of every new abbreviation.
99 is used to emphasize a word. Commonly rendered as italics.
100 Use only if its a truly ad-hoc, one-off situation. For anything else,
101 consider adding a new semantic markup with <span class="foo">.
104 is used to strongly emphasize a word. Commonly rendered in bold.
108 A line-break can sometimes be used to structure a paragraph, or to split a
109 longish heading. Never use spurious <br/>s at the end of paragraphs or to
110 control the spacing of sections. If you're unhappy with those, fix the CSS
111 (which fixes the entire manual in one go!)
118 Use the unordered list for information snippets that do not have an implied
119 order. The ordered list should always be used when a sequence of actions is
120 described. Within the lists, each item must be enclosed in <li> tags.
121 Lists cannot be included in <p>aragraphs. Close the paragraph first.
124 Definition lists are for technical terms <dt> and their definition <dd>. Do
125 not abuse them for anything else.
132 is used when an entire paragraph is quoted. Must contain a
133 cite="http://mysource.net/foo.pdf" attribute. Do not abuse to indent a
137 For inline citations, the <cite>W3C</cite> recommends to <q
138 cite="http://www.w3.org/TR/xhtml1/dtds.html">use the cite and q
142 4.4 Keyboard/Controller interaction
143 ------------------------------------
146 Any keys or key combinations, mouse buttons, or controllers should be marked
149 "Press <kbd>F</kbd> to fit all tracks to the height of the Editor window."
150 "Move <kbd>Fader 1</kbd> on your MIDI controller to bind it.
152 Since modifier keys are not cross-platform and Ardour makes a point of
153 abstracting them, do not hard-code "Alt", "Cmd" and friends, use
156 So if you want the user to press Ctrl-N on Linux, that's actually <kbd
157 class="mod1">N</kbd>. It will render as "Ctrl+N" for you, and as "Cmd+N" for
158 your Mac-using friend. Nice, uh?
160 For anything you want the user to type, use <kbd> as a block-level element.
163 is only used for program code, or the content of configuration files etc. Do
164 not abuse to style keys or user input, use <kbd> instead.
167 is only used for the textual output of any code, never for anything the user
175 The image tag must contain a 'src="/images/yourimage.png"' element and a
176 descriptive 'alt="A short textual description of the image content"'
183 * Avoid any typographical quotation marks to highlight terms or express any
184 kind of subtle inflection, use semantic markup instead.
185 * The hyphen is used to for compound words such as this well-advised example.
186 * Do not hyphenate words at line breaks.
187 * For breaks in thought — such as this splendid example — use
189 * For ranges of values, use the en-dash: Monday – Friday, 0 –