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
34 "Custom classes", and be sure to explain it to the reader at
35 _manual/01_welcome-to-ardour/02_about-ardour-documentation.html.
38 2. Format and Validation
39 ========================
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.
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 "&", "<", and ">".
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.
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.
66 make an element float left in the surrounding paragraph.
69 make an element float right in the surrounding paragraph.
72 use for important notes that should be visually distinct from the
73 normal text flow, or asides. Currently rendered in a gray box.
76 use for potentially dangerous situations involving data loss, malfunction,
77 or sound quality issues. Currently rendered in a red box.
80 use as additional classes to mark a section as relevant for these operating
83 Check _manual/01_welcome-to-ardour/02_about-ardour-documentation.html, it
84 serves as a style and markup guide.
91 4.1 Main structural elements
92 ----------------------------
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
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.
102 Every snippet of text should be enclosed in a block level element. The
103 default choice is <p>, the plain paragraph.
106 Cross-reference links in the manual are reasonably stable, since they are
107 independent of the ordering number (which gets removed from the URL) and the
108 pretty page title (the URL is created from the file name). So unless a file
109 is renamed or moved to another sub-directory, links should be ok.
115 encloses a newly introduced term that is being explained. Use for the first
116 occurrence of the main concept of every manual page, or the first occurrence
117 of a new concept after a sub-heading if necessary. Renders in bold face.
118 Keep in mind that <dfn> tags might be used to generate an index of keywords
119 - don't pollute it too much.
122 is used to explain an abbreviation such as <abbr title="Linux Audio
123 Developers Simple Plugin API">LADSPA</abbr>. Browsers will usually pop up the
124 definition when the user hovers over the word. Renders as dotted underlined
126 On each page, use only for the first occurrence of every abbreviation. Avoid
127 a redundant explanation in the text - the expansion can easily be extracted
128 via CSS for printing.
129 Use only in the text body, not in headings.
132 is used to emphasize a word. Commonly rendered as italics.
133 Use only if its a truly ad-hoc, one-off situation. For anything else,
134 consider adding a new semantic markup with <span class="foo">.
137 is used to strongly emphasize a word. Commonly rendered in bold.
141 A line-break can sometimes be used to structure a paragraph, or to split a
142 longish heading. Never use spurious <br/>s at the end of paragraphs or to
143 control the spacing of sections. If you're unhappy with those, fix the CSS
144 (which fixes the entire manual in one go!)
151 Use the unordered list for information snippets that do not have an implied
152 order. The ordered list should always be used when a sequence of actions is
153 described. Within the lists, each item must be enclosed in <li> tags.
154 Lists cannot be included in <p>aragraphs. Close the paragraph first.
157 Definition lists are for technical terms <dt> and their definition <dd>. Do
158 not abuse them for anything else.
165 is used when an entire paragraph is quoted. Must contain a
166 cite="http://mysource.net/foo.pdf" attribute. Do not abuse to indent a
170 For inline citations, the <cite>W3C</cite> recommends to <q
171 cite="http://www.w3.org/TR/xhtml1/dtds.html">use the cite and q
175 4.4 Keyboard/Controller interaction
176 ------------------------------------
179 Any keys or key combinations, mouse buttons or controllers, menu items or
180 textual user input should be marked with this element. It is used here in
181 the widest possible sense, qualified by classes.
183 "Press <kbd>f</kbd> to fit all tracks to the height of the Editor window."
184 "Move <kbd>Fader 1</kbd> on your MIDI controller to bind it.
186 Since modifier keys are not cross-platform and Ardour makes a point of
187 abstracting them, do not hard-code "Alt", "Cmd" and friends, use
190 So if you want the user to press Ctrl-N on Linux, that's actually <kbd
191 class="mod1">N</kbd>. It will render as "Ctrl N" for you, and as "Cmd N" for
192 your Mac-using friend. Nice, uh?
194 For anything you want the user to type, use <kbd> as a block-level element.
195 See above for other <kbd> classes to denote menu items, selections, mouse
196 events and controller actions.
198 Keys and mouse key names should always be entered lowercase, even though the
199 stylesheet might capitalize them.
201 CSS Classes used with <kbd> are:
203 .mouse: mouse buttons
205 .lin, .win, .mac: add nice prompts to that command line
206 .input: inline text to be entered by the user
207 .menu: path to an Ardour menu or other GUI item
208 .option: path to an option, with (X) at the end.
209 .optoff: path to an option, with ( ) at the end.
210 .button, .fader, .knob: external controllers (OSC or MIDI).
213 is only used for program code, or the content of configuration files etc. Do
214 not abuse to style keys or user input, use <kbd> instead.
217 is only used for the textual output of any code, never for anything the user
225 The image tag must contain a 'src="/images/yourimage.png"' element and a
226 descriptive 'alt="A short textual description of the image content"'
228 Images are usually placed as block-level elements, i.e. outside of a
229 paragraph, unless they are no higher than one row and make sense in the text
239 * Avoid any typographical quotation marks to highlight terms or express any
240 kind of subtle inflection, use semantic markup instead.
241 * The hyphen is used to for compound words such as this well-advised example.
242 * Do not hyphenate words at line breaks.
243 * For breaks in thought — such as this splendid example — use
245 * For ranges of values, use the en-dash: Monday – Friday, 0 –
247 * Use a non-breaking space (" ") between a number and its unit.
253 * The Ardour manual is written in Americal English spelling.
254 * Use SI units with standard abbreviations. Give imperial units only as
255 additional information, if at all.
256 * Do not use contractions like "you'll", always write full forms.
257 * Do not over-use "You", write about the program, not the user.
260 5.3 Chapter Headline Capitalization
261 ------------------------------------
263 Capitalization follows
264 https://developer.gnome.org/hig-book/3.6/design-text-labels.html.en#layout-capitalization
267 * Capitalize all words in the headline, with the following exceptions:
268 Articles: a, an, the.
269 Conjunctions: and, but, for, not, so, yet ...
270 Prepositions of three or fewer letters: at, for, by, in, to ...
271 * Keep headlines short and concise.
272 * secondary headlines in articles are not capitalized
273 * Do not capitalize concepts in the text body, with the possible exceptions
274 of _the_ Editor and _the_ Mixer.
277 5.4 Janitorial tasks/review
278 ---------------------------
280 If you encounter something that is unclear or patent nonsense, but you are
281 not bold or knowledgeable to fix it, express your doubts with an <p
282 class="fixme">editorial note</p>, so that readers will be warned and fellow
283 editors know where there's work to do.
285 5.5 Writing style suggestions
286 -----------------------------
288 * "Click OK" and similar explanations of the utterly obvious should be
289 avoided. Keep the writing concise and to the point. Explain as much as
290 possible, with as few words as possible.
291 * Do not fear repetitions, this is not artistic prose. Repeat important
292 keywords, rather than burden the user with synonyms made up on the spot.
293 * Do not create headings for different ways of doing the same thing (<h>Via
294 the context menu</h>,...<h>Via hotkeys</h>). Headings separate new
295 concepts. To not add gratuitous sub-headings if there is very little
296 content per heading and you do not expect the article to grow.
297 * If pages grow long, consider splitting them into sub-chapters at their
299 * Nobody needs "the next paragraph is about the following" paragraphs.
304 * Pages should be encoded in UTF-8, with Unix-style newlines if possible
305 (although that's not critical). Avoid using verbatim special symbols, use
306 HTML character entities instead, for example for cursor arrows: →
307 ← ↑ ↓. Diacriticals on vowels and other special letters are
308 probably ok by now, so don't bother with é and friends, just type é.