copy-editing chapter 7.

[ardour-manual-diverged] / STYLE_GUIDE

*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
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.
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", and be sure to explain it to the reader at
_manual/01_welcome-to-ardour/02_about-ardour-documentation.html.


2. Format and Validation
========================

The Ardour manual has been converted to valid XHTML 1.0. That means it must
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
"&amp;", "&lt;", and "&gt;".


3. Custom classes
=================

We use the class attribute for some aspects of styling (such as to float an
image left or right in a text paragraph), and also for more fine-grained
semantic markup than core XHTML allows.

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.

.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
==============


4.1 Main structural elements
----------------------------

<h1>..<h6>
A <h1/> heading is added by the Ruby framework, 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.

<p>
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.
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.
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">.

<strong>
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!)


4.2 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.

<dl>
Definition lists are for technical terms <dt> and their definition <dd>. Do
not abuse them for anything else.


4.3 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!

<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
------------------------------------

<kbd>
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?

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 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 <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
not abuse to style keys or user input, use <kbd> instead.

<samp>
is only used for the textual output of any code, never for anything the user
types or presses.


4.5 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.
Images are usually placed as block-level elements, i.e. outside of a
paragraph.

5. Other conventions
====================


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.
* Do not hyphenate words at line breaks.
* For breaks in thought &mdash; such as this splendid example &mdash; use
  the long em-dash.
* For ranges of values, use the en-dash: Monday &ndash; Friday, 0 &ndash;
  11.
* Use a non-breaking space ("&nbsp;") 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.