diff --git a/STYLE_GUIDE b/STYLE_GUIDE new file mode 100644 index 0000000..f744496 --- /dev/null +++ b/STYLE_GUIDE @@ -0,0 +1,192 @@ +*Style guide for the Ardour manual* + + + +1. Rationale +============ + +The Ardour manual should be consistent across different media, and it should +be easily updatable when Ardour's behaviour changes. +The markup should be semantic - looks are determined in the CSS, and only +there. If you feel you must compromise the markup in order to obtain a +certain look: don't do it. Accept the look. +Alternatively, edit the CSS, but be careful not to make matters worse +elsewhere. + + +1.1 visual markup +----------------- + +,,, or any other purely visual elements are not used in +the Ardour manual. +What you really mean is an phasis or a emphasis. +If you feel that some special terms should always be green and underlined, the +approach of choice is this: +foobar +and then add +.my_important_keyword { + text-decoration: underline; + color: #004400; + background-color: #eeffee; +} +to apps.css. +If you add a new class with semantic meaning, document it below, under +"Custom classes". + + +2. Format and Validation +======================== + +The Ardour manual has been converted to valid XHTML 1.0. That means it must +be valid XML, with all tags closed properly. The reason for this extra +complication is that XML can be more easily checked and automatically +refactored than plain HTML, which eases maintenance. + + +3. Custom classes +================= + +We use the class attribute for some aspects of styling (such as to float an +image left or right in a text paragraph), and also for more fine-grained +semantic markup than core XHTML allows. + +Any XHTML element can include a class attribute. If you need to add a class +attribute to a word or a few words which don't have an element of their own, +use foo bar. +If you need to apply a class to several block-level elements such as +paragraphs or lists, enclose them in a
..
. Wherever possible, +create semantic classes rather than visual ones. + +.left: make an element float left in the surrounding paragraph. +.right: make an element float right in the surrounding paragraph. + + +4. Element use +============== + + +4.1 Main structural elements +---------------------------- + +

..

+A

heading is added by the Ruby framework, so it should not be used in +the manual page itself. If you feel you need another

, start a new +subpage. +Heading levels must not be skipped. Any sub-heading must be exactly one +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

, the plain paragraph. + + +4.1 Inline markups +------------------ + + +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. + + +is used to explain an abbreviation such as LADSPA. Browsers will usually pop up the +definition when the user hovers over the word, and it can easily be +extracted via CSS for printing. +Use only for the first occurrence of every new abbreviation. + + +is used to emphasize a word. Commonly rendered as italics. +Use only if its a truly ad-hoc, one-off situation. For anything else, +consider adding a new semantic markup with . + + +is used to strongly emphasize a word. Commonly rendered in bold. +See above for usage. + +
+A line-break can sometimes be used to structure a paragraph, or to split a +longish heading. Never use spurious
s at the end of paragraphs or to +control the spacing of sections. If you're unhappy with those, fix the CSS +(which fixes the entire manual in one go!) + + +4.2 Lists +--------- + +

    ,
      +Use the unordered list for information snippets that do not have an implied +order. The ordered list should always be used when a sequence of actions is +described. Within the lists, each item must be enclosed in
    1. tags. +Lists cannot be included in

      aragraphs. Close the paragraph first. + +

      +Definition lists are for technical terms
      and their definition
      . Do +not abuse them for anything else. + + +4.3 Quotations +-------------- + +
      +is used when an entire paragraph is quoted. Must contain a +cite="http://mysource.net/foo.pdf" attribute. Do not abuse to indent a +paragraph! + +, +For inline citations, the W3C recommends to use the cite and q +elements. + + +4.4 Keyboard/Controller interaction +------------------------------------ + + +Any keys or key combinations, mouse buttons, or controllers should be marked +with this element. +E.g.: +"Press F to fit all tracks to the height of the Editor window." +"Move Fader 1 on your MIDI controller to bind it. +" +Since modifier keys are not cross-platform and Ardour makes a point of +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 N. It will render as "Ctrl+N" for you, and as "Cmd+N" for +your Mac-using friend. Nice, uh? + +For anything you want the user to type, use as a block-level element. + + +is only used for program code, or the content of configuration files etc. Do +not abuse to style keys or user input, use instead. + + +is only used for the textual output of any code, never for anything the user +types or presses. + + +4.5 Images +---------- + + +The image tag must contain a 'src="/images/yourimage.png"' element and a +descriptive 'alt="A short textual description of the image content"' +element. + + +5. Typography +============= + +* Avoid any typographical quotation marks to highlight terms or express any + 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 — such as this splendid example — use + the long em-dash. +* For ranges of values, use the en-dash: Monday – Friday, 0 – + 11. + +