X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=STYLE_GUIDE;h=09f7a6c51e43b352f12557d6283bb76f7b038a01;hb=ab74074e3fb3d79813ac88f5e239b2ef3189cae6;hp=02cd1c26d6ed109ee8f532093ff8267d6699244e;hpb=2d0291a89ca5b90531dd728f73c09c4238f92f68;p=ardour-manual diff --git a/STYLE_GUIDE b/STYLE_GUIDE index 02cd1c2..09f7a6c 100644 --- a/STYLE_GUIDE +++ b/STYLE_GUIDE @@ -102,6 +102,11 @@ 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. 4.1 Inline markups ------------------ @@ -109,16 +114,17 @@ 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. +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. @@ -132,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 @@ -170,10 +177,11 @@ elements. ------------------------------------ -Any keys or key combinations, mouse buttons, or controllers should be marked -with this element. +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 @@ -181,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 @@ -219,7 +229,10 @@ types or presses. 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, 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 ==================== @@ -232,23 +245,31 @@ element. 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. +* 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 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 "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 ...". -5.3 Headline Capitalization ---------------------------- +5.3 Chapter Headline Capitalization +------------------------------------ Capitalization follows https://developer.gnome.org/hig-book/3.6/design-text-labels.html.en#layout-capitalization @@ -259,4 +280,43 @@ https://developer.gnome.org/hig-book/3.6/design-text-labels.html.en#layout-capit Conjunctions: and, but, for, not, so, yet ... Prepositions of three or fewer letters: at, for, by, in, to ... * Keep headlines short and concise. +* secondary headlines in articles are not capitalized +* Do not capitalize concepts in the text body, with the possible exceptions + of _the_ Editor and _the_ Mixer. + + +5.4 Janitorial tasks/review +--------------------------- + +If you encounter something that is unclear or patent nonsense, but you are +not bold or knowledgeable to fix it, express your doubts with an

editorial note

, so that readers will be warned and fellow +editors know where there's work to do. + +5.5 Writing style suggestions +----------------------------- + +* "Click OK" and similar explanations of the utterly obvious should be +avoided. Keep the writing concise and to the point. Explain as much as +possible, with as few words as possible. +* Do not fear repetitions, this is not artistic prose. Repeat important +keywords, rather than burden the user with synonyms made up on the spot. +* Do not create headings for different ways of doing the same thing (Via +the context menu,...Via hotkeys). Headings separate new +concepts. To not add gratuitous sub-headings if there is very little +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 é.