+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
------------------
@@ -105,16 +114,17 @@ default choice is , the plain paragraph.
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 tags might be used to generate an index of keywords
-- don't pollute it too much.
+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.
+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
+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.
@@ -128,6 +138,7 @@ 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
@@ -166,10 +177,11 @@ elements.
------------------------------------
-Any keys or key combinations, mouse buttons, or controllers should be marked
-with this element.
+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 F to fit all tracks to the height of the Editor window."
+"Press f to fit all tracks to the height of the Editor window."
"Move Fader 1 on your MIDI controller to bind it.
"
Since modifier keys are not cross-platform and Ardour makes a point of
@@ -177,13 +189,30 @@ 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 N. It will render as "Ctrl+N" for you, and as "Cmd+N" for
+class="mod1">N. It will render as "Ctrl N" for you, and as "Cmd N" for
your Mac-using friend. Nice, uh?
+N.B.: If you want to have just the name of the modifier key by itself, use
+
block.
5. Other conventions
====================
@@ -213,23 +245,29 @@ element.
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.
+* 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.
5.2 Language
------------
-* The Ardour manual is written in Americal English spelling.
+* 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 "you'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 Headline Capitalization
----------------------------
+5.3 Chapter Headline Capitalization
+------------------------------------
Capitalization follows
https://developer.gnome.org/hig-book/3.6/design-text-labels.html.en#layout-capitalization
@@ -240,4 +278,43 @@ https://developer.gnome.org/hig-book/3.6/design-text-labels.html.en#layout-capit
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 editorial note
, 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 (Via
+the context menu,...Via hotkeys). 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 NOTE
, *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 é.