X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=STYLE_GUIDE;h=278c65a0d4bd1860480b3f19fb9a72a28dc544f1;hb=5432a9fe7de29efd25d570bccb662ea3c2b4783c;hp=f6101bbe4961e8a719b3efbb38abe8cc402ef0f6;hpb=689d1af72ae198d9a38f6c6a6e8aff8f798b67bf;p=ardour-manual-diverged diff --git a/STYLE_GUIDE b/STYLE_GUIDE index f6101bb..278c65a 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 @@ -75,6 +76,10 @@ normal text flow, or asides. Currently rendered in a gray box. 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. @@ -97,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 ------------------ @@ -115,6 +125,7 @@ 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. @@ -164,8 +175,9 @@ 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." "Move Fader 1 on your MIDI controller to bind it. @@ -182,6 +194,21 @@ 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 not abuse to style keys or user input, use instead. @@ -198,10 +225,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. @@ -211,5 +243,30 @@ 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 Chapter 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. +* 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.