X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=STYLE_GUIDE;h=491794cf5def497e587f675afcfcd434505ebde0;hb=a1e84930287265d6e474a3ca57f4df40a1106256;hp=53170b13f87cbfe6a3fa32d25e1a5c2effdecd4a;hpb=0d92391d1c96ae134759271d036a8fe68f09f9b0;p=ardour-manual diff --git a/STYLE_GUIDE b/STYLE_GUIDE index 53170b1..491794c 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 @@ -46,6 +50,9 @@ Watch out for the ampersand "&" and angle brackets "<" and ">". They will render your XHTML invalid, and must be replaced by their named entities "&", "<", and ">". +Keep line lengths within 108 characters so that additions or changes are easy to view in github pull requests. +Code examples that are supposed to be all one line are an exception in which case the 
 tag should be
+used to to tell the browser to display the code as one line.
 
 3. Custom classes
 =================
@@ -57,6 +64,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,6 +83,13 @@ 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.
 
+.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
 ==============
@@ -84,95 +99,137 @@ or sound quality issues. Currently rendered in a red box.
 ----------------------------
 
 
..

-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
+
+4.2 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.
+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
+4.3 Lists
 ---------
 
-