X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=STYLE_GUIDE;h=09b45dfc9473aa1765418cae7395ecba4c599887;hb=d26989c791fc8af686619457925bf7391944f316;hp=f6101bbe4961e8a719b3efbb38abe8cc402ef0f6;hpb=689d1af72ae198d9a38f6c6a6e8aff8f798b67bf;p=ardour-manual diff --git a/STYLE_GUIDE b/STYLE_GUIDE index f6101bb..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,42 +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. -Keep in mind that tags might be used to generate an index of keywords -- don't pollute it too much. +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. -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. +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 --------- -