gold-plating the bikeshed: a style guide for the Ardour manual.
This commit is contained in:
Jörn Nettingsmeier
parent
19ee4b8d24
commit
f6c0d65cd8
192
STYLE_GUIDE
Normal file
192
STYLE_GUIDE
Normal file
@ -0,0 +1,192 @@
|
|||||||
|
*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".
|
||||||
|
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
<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.
|
||||||
|
|
||||||
|
<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 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.
|
||||||
|
"
|
||||||
|
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.
|
||||||
|
|
||||||
|
<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.
|
||||||
|
|
||||||
|
|
||||||
|
5. 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.
|
||||||
|
|
||||||
|
|
||||||
Loading…
Reference in New Issue
Block a user