X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=STYLE_GUIDE;h=001b2a72c65b23041400ab5aebe7d9c36e04b035;hb=e3adb8ef44a7daf61312b42f86c547357ecfbb15;hp=02cd1c26d6ed109ee8f532093ff8267d6699244e;hpb=2d0291a89ca5b90531dd728f73c09c4238f92f68;p=ardour-manual
diff --git a/STYLE_GUIDE b/STYLE_GUIDE
index 02cd1c2..001b2a7 100644
--- a/STYLE_GUIDE
+++ b/STYLE_GUIDE
@@ -102,6 +102,11 @@ 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.
+
+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
------------------
@@ -170,8 +175,9 @@ 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."
"Move Fader 1 on your MIDI controller to bind it.
@@ -219,7 +225,8 @@ types or presses.
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.
5. Other conventions
====================
@@ -247,8 +254,8 @@ element.
additional information, if at all.
-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
@@ -259,4 +266,31 @@ 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.