X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=STYLE_GUIDE;h=491794cf5def497e587f675afcfcd434505ebde0;hb=a1e84930287265d6e474a3ca57f4df40a1106256;hp=4c57d00ca94a9d487a505adb974278858c78e1e6;hpb=2e006d9b931807ddc386650766de3a5fe44a271b;p=ardour-manual diff --git a/STYLE_GUIDE b/STYLE_GUIDE index 4c57d00..491794c 100644 --- a/STYLE_GUIDE +++ b/STYLE_GUIDE @@ -1,38 +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", and be sure to explain it to the reader at -_manual/01_welcome-to-ardour/02_about-ardour-documentation.html. +include/about-ardour-documentation.html. 2. Format and Validation @@ -47,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
 =================
@@ -58,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.
@@ -80,8 +87,8 @@ or sound quality issues. Currently rendered in a red box.
 use as additional classes to mark a section as relevant for these operating
 systems only.
 
-Check _manual/01_welcome-to-ardour/02_about-ardour-documentation.html, it
-serves as a style and markup guide.
+Check include/about-ardour-documentation.html, it serves as a style and
+markup guide.
 
 
 4. Element use
@@ -92,113 +99,129 @@ 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.
 
 
-Cross-reference links in the manual are reasonably stable, since they are
-independent of the ordering number (which gets removed from the URL) and the
-pretty page title (the URL is created from the file name). So unless a file
-is renamed or moved to another sub-directory, links should be ok.
+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:
 
-4.1 Inline markups
+
+
+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.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.
-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.
-Use only in the text body, not in headings.
+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
 ---------
 
-