X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=STYLE_GUIDE;h=09b45dfc9473aa1765418cae7395ecba4c599887;hb=655c21f1a01e7f65f437d13b875e1bc7f0a4d6d5;hp=866e86f0a167ff2860ffa3f15f0aefb27c84e0cb;hpb=fdbd351eb81927e87b7abed13bbbc8dc3df9e314;p=ardour-manual diff --git a/STYLE_GUIDE b/STYLE_GUIDE index 866e86f..09b45df 100644 --- a/STYLE_GUIDE +++ b/STYLE_GUIDE @@ -1,37 +1,41 @@ -*Style guide for the Ardour manual* +*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 +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. +,,, 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". +"Custom classes", and be sure to explain it to the reader at +include/about-ardour-documentation.html. 2. Format and Validation @@ -57,6 +61,7 @@ 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. @@ -75,8 +80,12 @@ normal text flow, or asides. Currently rendered in a gray box. use for potentially dangerous situations involving data loss, malfunction, or sound quality issues. Currently rendered in a red box. -Check _manual/01_welcome-to-ardour/02_about-ardour-documentation.html, it -serves as a style and markup guide. +.mac, .lin, .win: +use as additional classes to mark a section as relevant for these operating +systems only. + +Check include/about-ardour-documentation.html, it serves as a style and +markup guide. 4. Element use @@ -87,16 +96,29 @@ serves as a style and markup guide. ----------------------------

..

-A

heading is added by the Ruby framework, so it should not be used in +An

heading is added by the build script, 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. +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. + +Internal manual links should be absolutely stable, as long as the references in +the master document do not change (and they absolutely *should* not be changed +except for a *very* good reason, even then they probably should not be +changed!). Use the form: + + + +where @@my-internal-link is a reference to a "link:" keyword in a header in the +master document. Note that in the master document, they will not have the +double at-sign ("@@") in front, that is *only* used in the page content to +signal to the build system that it is an internal link that needs to be fixed +so that it points to the correct URL. + 4.1 Inline markups ------------------ @@ -104,39 +126,44 @@ default choice is

, the plain paragraph. 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. +of a new concept after a sub-heading if necessary. Renders in bold face. Keep +in mind that tags might be used to generate an index of keywords--don't +pollute it too much. -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 explain an abbreviation such as LADSPA. Browsers will usually pop up the definition +when the user hovers over the word. Renders as dotted underlined in most +browsers. On each page, use only for the first occurrence of every +abbreviation. Avoid a redundant explanation in the text--the expansion can +easily be extracted via CSS for printing. Use only in the text body, not in +headings. -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 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. +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!) +
+Most of the time, these should be avoided, and used very infrequently. 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 --------- -