*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 ----------------- ,,, or any other purely visual elements are not used in the Ardour manual. What you really mean is an phasis or a emphasis. If you feel that some special terms should always be green and underlined, the approach of choice is this: foobar 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 
 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 foo bar.

If you need to apply a class to several block-level elements such as
paragraphs or lists, enclose them in a 
..
. 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
----------------------------


..

An 
 heading is added by the build script, so it should not be used in
the manual page itself. If you feel you need another 
, 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.



Every snippet of text should be enclosed in a block level element. The
default choice is 
, the plain paragraph.


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:



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


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  tags might be used to generate an index of keywords--don't
pollute it too much.


is used to explain an abbreviation such as LADSPA. 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.


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 .


is used to strongly emphasize a word. Commonly rendered in bold. See above for
usage.



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