X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=STYLE_GUIDE;h=f9d4ce2786f85b9c4cbc72471974e76a2a5114cf;hb=0fed26b3130003f7444857c0c0247c631be9db8b;hp=4c57d00ca94a9d487a505adb974278858c78e1e6;hpb=2e006d9b931807ddc386650766de3a5fe44a271b;p=ardour-manual diff --git a/STYLE_GUIDE b/STYLE_GUIDE index 4c57d00..f9d4ce2 100644 --- a/STYLE_GUIDE +++ b/STYLE_GUIDE @@ -114,14 +114,15 @@ 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. +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 via CSS for printing. @@ -175,10 +176,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 @@ -186,16 +188,15 @@ 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? For anything you want the user to type, use as a block-level element. See above for other classes to denote menu items, selections, mouse events and controller actions. -Keys and mouse key names should always be capitalized. We do not need to -distringuish between "x" and "X", because the latter would be "Shift-X". -In case you forget, the stylesheet takes care of this. +Keys and mouse key names should always be entered lowercase, even though the +stylesheet might capitalize them. CSS Classes used with are: .modN @@ -225,7 +226,8 @@ 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. 5. Other conventions ==================== @@ -269,3 +271,36 @@ https://developer.gnome.org/hig-book/3.6/design-text-labels.html.en#layout-capit * 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. + +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 é.