X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=STYLE_GUIDE;h=5c367ab6dc3cf519f250c625c1fec5842ef4d918;hb=5f92c0832cc395082fef91df5cb695bb53510e6a;hp=f7444967612ce51f51967ac3f5613d7162009a1d;hpb=f6c0d65cd832fce3a6f4ae166a1e410792f23338;p=ardour-manual diff --git a/STYLE_GUIDE b/STYLE_GUIDE index f744496..5c367ab 100644 --- a/STYLE_GUIDE +++ b/STYLE_GUIDE @@ -31,7 +31,8 @@ and then add } to apps.css. If you add a new class with semantic meaning, document it below, under -"Custom classes". +"Custom classes", and be sure to explain it to the reader at +_manual/01_welcome-to-ardour/02_about-ardour-documentation.html. 2. Format and Validation @@ -42,6 +43,10 @@ be valid XML, with all tags closed properly. The reason for this extra complication is that XML can be more easily checked and automatically refactored than plain HTML, which eases maintenance. +Watch out for the ampersand "&" and angle brackets "<" and ">". They will +render your XHTML invalid, and must be replaced by their named entities +"&", "<", and ">". + 3. Custom classes ================= @@ -57,8 +62,26 @@ 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. -.left: make an element float left in the surrounding paragraph. -.right: make an element float right in the surrounding paragraph. +.left: +make an element float left in the surrounding paragraph. + +.right: +make an element float right in the surrounding paragraph. + +.note: +use for important notes that should be visually distinct from the +normal text flow, or asides. Currently rendered in a gray box. + +.warning: +use for potentially dangerous situations involving data loss, malfunction, +or sound quality issues. Currently rendered in a red box. + +.mac, .lin, .win: +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. 4. Element use @@ -87,13 +110,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. is used to explain an abbreviation such as LADSPA. Browsers will usually pop up the -definition when the user hovers over the word, and it can easily be -extracted via CSS for printing. -Use only for the first occurrence of every new abbreviation. +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 emphasize a word. Commonly rendered as italics. @@ -158,6 +185,23 @@ 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. + +CSS Classes used with are: +.modN +.mouse: mouse buttons +.cmd: a command line +.lin, .win, .mac: add nice prompts to that command line +.input: inline text to be entered by the user +.menu: path to an Ardour menu or other GUI item +.option: path to an option, with (X) at the end. +.optoff: path to an option, with ( ) at the end. +.button, .fader, .knob: external controllers (OSC or MIDI). is only used for program code, or the content of configuration files etc. Do @@ -175,10 +219,15 @@ 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. + +5. Other conventions +==================== -5. Typography -============= +5.1 Typography +-------------- * Avoid any typographical quotation marks to highlight terms or express any kind of subtle inflection, use semantic markup instead. @@ -188,5 +237,27 @@ element. 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. + + +5.2 Language +------------ + +* 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. + + +5.3 Headline Capitalization +--------------------------- + +Capitalization follows +https://developer.gnome.org/hig-book/3.6/design-text-labels.html.en#layout-capitalization +: +* Capitalize all words in the headline, with the following exceptions: + Articles: a, an, the. + Conjunctions: and, but, for, not, so, yet ... + Prepositions of three or fewer letters: at, for, by, in, to ... +* Keep headlines short and concise.