309 lines
11 KiB
Plaintext
309 lines
11 KiB
Plaintext
*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
|
|
"&", "<", and ">".
|
|
|
|
|
|
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. 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. 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">.
|
|
|
|
<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 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
|
|
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, unless they are no higher than one row and make sense in the text
|
|
flow.
|
|
|
|
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 — such as this splendid example — use
|
|
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 é.
|