344 lines
12 KiB
Plaintext
344 lines
12 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
|
|
include/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 ">".
|
|
|
|
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
|
|
=================
|
|
|
|
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 include/about-ardour-documentation.html, it serves as a style and
|
|
markup guide.
|
|
|
|
|
|
4. Element use
|
|
==============
|
|
|
|
|
|
4.1 Main structural elements
|
|
----------------------------
|
|
|
|
<h1>..<h6>
|
|
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.
|
|
|
|
<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.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. 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>
|
|
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.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.
|
|
|
|
<dl>
|
|
Definition lists are for technical terms <dt> and their definition <dd>. Do
|
|
not abuse them for anything else.
|
|
|
|
|
|
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!
|
|
|
|
<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.5 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, 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
|
|
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.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.
|
|
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.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 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. 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 é.
|
|
|