X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;ds=sidebyside;f=STYLE_GUIDE;fp=STYLE_GUIDE;h=be65d6381b365ee4a7596826b116489ec9315d1d;hb=ac92ade0dcdc6d3aad15228590f426741bf7558e;hp=09f7a6c51e43b352f12557d6283bb76f7b038a01;hpb=ab74074e3fb3d79813ac88f5e239b2ef3189cae6;p=ardour-manual diff --git a/STYLE_GUIDE b/STYLE_GUIDE index 09f7a6c..be65d63 100644 --- a/STYLE_GUIDE +++ b/STYLE_GUIDE @@ -114,9 +114,9 @@ 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. Renders in bold face. 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. 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. @@ -138,7 +138,6 @@ 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 @@ -192,9 +191,6 @@ 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 your Mac-using friend. Nice, uh? -N.B.: If you want to have just the name of the modifier key by itself, use -

block. +flow. 5. Other conventions ==================== @@ -245,27 +240,21 @@ flow. Aside from this exception, they should *always* be wrapped inside of a 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. 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. +* 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. * Use a non-breaking space (" ") between a number and its unit. -* Colons (":") always snug up to their text on the left: it is an error to add - space between text on the left and the colon. 5.2 Language ------------ -* The Ardour manual is written in American English spelling. +* The Ardour manual is written in Americal English spelling. * Use SI units with standard abbreviations. Give imperial units only as additional information, if at all. -* Do not use contractions like "it'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 ...". +* Do not use contractions like "you'll", always write full forms. +* Do not over-use "You", write about the program, not the user. 5.3 Chapter Headline Capitalization @@ -308,8 +297,6 @@ 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 ------------- @@ -319,4 +306,3 @@ headings. 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 é. -