}
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
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.
Every snippet of text should be enclosed in a block level element. The
default choice is <p>, the plain paragraph.
+<a>
+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
------------------
<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.
+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.
------------------------------------
<kbd>
-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 <kbd>F</kbd> to fit all tracks to the height of the Editor window."
+"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
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
+class="mod1">N</kbd>. 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 <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
+.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
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.
+
+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 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.
+* Do not use contractions like "you'll", always write full forms.
+* Do not over-use "You", write about the program, not the user.
+
+
+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.
+
+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 é.