-*Style guide for the Ardour manual*
+*Style guide for the Ardour manual*
1. Rationale
============
The Ardour manual should be consistent across different media, and it should
-be easily updatable when Ardour's behaviour changes.
-The markup should be semantic - looks are determined in the CSS, and only
-there. If you feel you must compromise the markup in order to obtain a
-certain look: don't do it. Accept the look.
-Alternatively, edit the CSS, but be careful not to make matters worse
+be easily updatable when Ardour's behaviour changes. The markup should be
+semantic--looks are determined in the CSS, and only there. If you feel you must
+compromise the markup in order to obtain a certain look: don't do it. Accept
+the look. Alternatively, edit the CSS, but be careful not to make matters worse
elsewhere.
1.1 visual markup
-----------------
-<b>,<i>,<u>,<font> or any other purely visual elements are not used in
-the Ardour manual.
-What you really mean is an <em>phasis or a <strong> emphasis.
+<b>,<i>,<u>,<font> or any other purely visual elements are not used in the
+Ardour manual. What you really mean is an <em>phasis or a <strong> emphasis.
If you feel that some special terms should always be green and underlined, the
approach of choice is this:
+
<span class="my_important_keyword">foobar</span>
+
and then add
+
.my_important_keyword {
text-decoration: underline;
color: #004400;
background-color: #eeffee;
}
+
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
+include/about-ardour-documentation.html.
2. Format and Validation
render your XHTML invalid, and must be replaced by their named entities
"&", "<", and ">".
+Keep line lengths within 108 characters so that additions or changes are easy to view in github pull requests.
+Code examples that are supposed to be all one line are an exception in which case the <pre></pre> tag should be
+used to to tell the browser to display the code as one line.
3. Custom classes
=================
Any XHTML element can include a class attribute. If you need to add a class
attribute to a word or a few words which don't have an element of their own,
use <span class="my_new_category">foo bar</span>.
+
If you need to apply a class to several block-level elements such as
paragraphs or lists, enclose them in a <div>..</div>. Wherever possible,
create semantic classes rather than visual ones.
use for potentially dangerous situations involving data loss, malfunction,
or sound quality issues. Currently rendered in a red box.
-Check _manual/01_welcome-to-ardour/02_about-ardour-documentation.html, it
-serves as a style and markup guide.
+.mac, .lin, .win:
+use as additional classes to mark a section as relevant for these operating
+systems only.
+
+Check include/about-ardour-documentation.html, it serves as a style and
+markup guide.
4. Element use
----------------------------
<h1>..<h6>
-A <h1/> heading is added by the Ruby framework, so it should not be used in
+An <h1/> heading is added by the build script, so it should not be used in
the manual page itself. If you feel you need another <h1>, start a new
-subpage.
-Heading levels must not be skipped. Any sub-heading must be exactly one
-level below its predecessor. Do not abuse headings to style a head line.
+subpage. Heading levels must not be skipped. Any sub-heading must be exactly
+one level below its predecessor. Do not abuse headings to style a head line.
<p>
Every snippet of text should be enclosed in a block level element. The
default choice is <p>, the plain paragraph.
+<a>
+Internal manual links should be absolutely stable, as long as the references in
+the master document do not change (and they absolutely *should* not be changed
+except for a *very* good reason, even then they probably should not be
+changed!). Use the form:
+
+<a href="@@my-internal-link">
+
+where @@my-internal-link is a reference to a "link:" keyword in a header in the
+master document. Note that in the master document, they will not have the
+double at-sign ("@@") in front, that is *only* used in the page content to
+signal to the build system that it is an internal link that needs to be fixed
+so that it points to the correct URL.
-4.1 Inline markups
+
+4.2 Inline markups
------------------
<dfn>
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 <dfn> tags might be used to generate an index of keywords--don't
+pollute it too much.
<abbr>
-is used to explain an abbreviation such as <abbr title="Linux Audio
-Developers Simple Plugin API">LADSPA</abbr>. 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.
+is used to explain an abbreviation such as <abbr title="Linux Audio Developers
+Simple Plugin API">LADSPA</abbr>. 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 via CSS for printing. Use only in the text body, not in
+headings.
<em>
-is used to emphasize a word. Commonly rendered as italics.
-Use only if its a truly ad-hoc, one-off situation. For anything else,
-consider adding a new semantic markup with <span class="foo">.
+is used to emphasize a word. Commonly rendered as italics. Use only if its a
+truly ad-hoc, one-off situation. For anything else, consider adding a new
+semantic markup with <span class="foo">.
<strong>
-is used to strongly emphasize a word. Commonly rendered in bold.
-See above for usage.
+is used to strongly emphasize a word. Commonly rendered in bold. See above for
+usage.
-<br />
-A line-break can sometimes be used to structure a paragraph, or to split a
-longish heading. Never use spurious <br/>s at the end of paragraphs or to
-control the spacing of sections. If you're unhappy with those, fix the CSS
-(which fixes the entire manual in one go!)
+<br>
+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 <br>s at the end of paragraphs or to control the
+spacing of sections. If you're unhappy with those, fix the CSS (which fixes the
+entire manual in one go!).
-4.2 Lists
+4.3 Lists
---------
-<ul>,<ol>
Use the unordered list for information snippets that do not have an implied
order. The ordered list should always be used when a sequence of actions is
-described. Within the lists, each item must be enclosed in <li> tags.
-
Lists cannot be included in <p>aragraphs. Close the paragraph first.
+described. Within the lists, each item must be enclosed in <li> tags. Lists
+cannot be included in <p>aragraphs. Close the paragraph first.
<dl>
Definition lists are for technical terms <dt> and their definition <dd>. Do
not abuse them for anything else.
-4.3 Quotations
+4.4 Quotations
--------------
<blockquote>
-is used when an entire paragraph is quoted. Must contain a
-cite="http://mysource.net/foo.pdf" attribute. Do not abuse to indent a
-paragraph!
+is used when an entire paragraph is quoted. Must contain a cite="http://
+mysource.net/foo.pdf" attribute. Do not abuse to indent a paragraph!
-<cite>,<q>
-For inline citations, the <cite>W3C</cite> recommends to <q
-cite="http://www.w3.org/TR/xhtml1/dtds.html">use the cite and q
-elements</q>.
+<cite>, <q>
+For inline citations, the <cite>W3C</cite> recommends to <q cite="http://
+www.w3.org/TR/xhtml1/dtds.html">use the cite and q elements</q>.
-4.4 Keyboard/Controller interaction
-------------------------------------
+4.5 Keyboard/Controller interaction
+-----------------------------------
<kbd>
-Any keys or key combinations, mouse buttons, or controllers should be marked
-with this element.
-E.g.:
-"Press <kbd>F</kbd> to fit all tracks to the height of the Editor window."
-"Move <kbd>Fader 1</kbd> on your MIDI controller to bind it.
-"
+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 <kbd>f</kbd> to fit all tracks to the height of the Editor window."
+"Move <kbd>Fader 1</kbd> on your MIDI controller to bind it."
+
Since modifier keys are not cross-platform and Ardour makes a point of
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 <kbd
-class="mod1">N</kbd>. It will render as "Ctrl+N" for you, and as "Cmd+N" for
-your Mac-using friend. Nice, uh?
+class="mod1">N</kbd>. It will render as "Ctrl N" for you, and as "Cmd N" for
+your Mac-using friend. Nice, huh?
+
+Multiple modifier keys are supported as "modNM" as well, so for Ctrl-Shift-N on Linux, you would use "mod13".
+
+N.B.: If you want to have just the name of the modifier key by itself, use the
+ modN name followed by a lower case "n", like so: <kbd class="mod1n></kbd>
For anything you want the user to type, use <kbd> as a block-level element.
+See above for other <kbd> classes to denote menu items, selections, mouse
+events and controller actions.
+
+Keys and mouse key names should always be entered lowercase, even though the
+stylesheet might capitalize them.
+
+CSS Classes used with <kbd> are:
+
+.modN, .modNM, .modNn, .modNMn
+.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).
<code>
is only used for program code, or the content of configuration files etc. Do
types or presses.
-4.5 Images
+4.6 Images
----------
<img>
The image tag must contain a 'src="/images/yourimage.png"' element and a
-descriptive 'alt="A short textual description of the image content"'
-element.
+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.
+
+Images should also be wrapped (unless they are embedded inside a paragraph) in
+a <figure></figure> block, and should contain a <figcaption></figcaption> block
+inside as well to describe to the reader what the image is.
+
+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.
-* The hyphen is used to for compound words such as this well-advised example.
+* The hyphen is used 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 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 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.
+
+
+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 <p
+class="fixme">editorial note</p>, 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 (<h>Via
+ the context menu</h>,...<h>Via hotkeys</h>). 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 <p class="note">NOTE</p>, *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 é.
projects / ardour-manual / blobdiff