X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=STYLE_GUIDE;h=7ab923ba19ef51d0a6c51b56c9ca5237cd30acf6;hb=8e3b4c710683de8f44cc46d5f00d9e19c0855527;hp=001b2a72c65b23041400ab5aebe7d9c36e04b035;hpb=41145e543a32161a85d73cf407b18efe70d0788b;p=ardour-manual-diverged diff --git a/STYLE_GUIDE b/STYLE_GUIDE index 001b2a7..7ab923b 100644 --- a/STYLE_GUIDE +++ b/STYLE_GUIDE @@ -114,16 +114,17 @@ is renamed or moved to another sub-directory, links should be ok. 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. +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 +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. @@ -137,6 +138,7 @@ is used to strongly emphasize a word. Commonly rendered in bold. See above for usage.
+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 @@ -179,7 +181,7 @@ Any keys or key combinations, mouse buttons or controllers, menu items or textual user input should be marked with this element. It is used here in the widest possible sense, qualified by classes. E.g.: -"Press F to fit all tracks to the height of the Editor window." +"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 @@ -187,16 +189,18 @@ 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 +class="mod1">N. It will render as "Ctrl N" for you, and as "Cmd N" for your Mac-using friend. Nice, uh? +N.B.: If you want to have just the name of the modifier key by itself, use + are: .modN @@ -226,7 +230,9 @@ The image tag must contain a 'src="/images/yourimage.png"' element and a descriptive 'alt="A short textual description of the image content"' element. Images are usually placed as block-level elements, i.e. outside of a -paragraph. +paragraph, unless they are no higher than one row and make sense in the text +flow. Aside from this exception, they should *always* be wrapped inside of a +

block. 5. Other conventions ==================== @@ -239,19 +245,25 @@ paragraph. 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. +* For breaks in thought—such as this splendid example—use + the long em-dash. Note that the em-dash is snugged up against the text on both + sides--this is the proper way to use them. +* For ranges of values, use the en-dash: Monday–Friday, 0–11. Note + again, the en-dash is snugged up to its surrounding elements. * Use a non-breaking space (" ") between a number and its unit. 5.2 Language ------------ -* The Ardour manual is written in Americal English spelling. +* The Ardour manual is written in American English spelling. * Use SI units with standard abbreviations. Give imperial units only as additional information, if at all. +* Do not use contractions like "you'll", always write full forms. +* Do not over-use "You", write about the program, not the user. Avoid it if at + all possible, it makes for tighter and better reading text. +* Always write out numbers less than 11. E.g., "One or two ..." instead of + "1 or 2 ...". 5.3 Chapter Headline Capitalization @@ -294,3 +306,15 @@ content per heading and you do not expect the article to grow. * If pages grow long, consider splitting them into sub-chapters at their headings. * Nobody needs "the next paragraph is about the following" paragraphs. +* When creating a

NOTE

, *do not* put the word NOTE into + the note, the styling tells the user that it is a note. + +5.6. Encoding +------------- + +* Pages should be encoded in UTF-8, with Unix-style newlines if possible +(although that's not critical). Avoid using verbatim special symbols, use +HTML character entities instead, for example for cursor arrows: → +← ↑ ↓. Diacriticals on vowels and other special letters are +probably ok by now, so don't bother with é and friends, just type é. +