From: Jörn Nettingsmeier Date: Mon, 3 Feb 2014 21:35:52 +0000 (+0100) Subject: more copy-editing of chapters 1+2, update style guide to reflect lessons learned. X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=689d1af72ae198d9a38f6c6a6e8aff8f798b67bf;hp=fdbd351eb81927e87b7abed13bbbc8dc3df9e314;p=ardour-manual-diverged more copy-editing of chapters 1+2, update style guide to reflect lessons learned. --- diff --git a/STYLE_GUIDE b/STYLE_GUIDE index 866e86f..f6101bb 100644 --- a/STYLE_GUIDE +++ b/STYLE_GUIDE @@ -105,13 +105,16 @@ 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. is used to explain an abbreviation such as LADSPA. 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. +definition when the user hovers over the word. +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. is used to emphasize a word. Commonly rendered as italics. @@ -176,6 +179,8 @@ class="mod1">N. 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 as a block-level element. +See above for other classes to denote menu items, selections, mouse +events and controller actions. is only used for program code, or the content of configuration files etc. Do diff --git a/_manual/01_welcome-to-ardour/02_about-ardour-documentation.html b/_manual/01_welcome-to-ardour/02_about-ardour-documentation.html index c539e08..4b04400 100644 --- a/_manual/01_welcome-to-ardour/02_about-ardour-documentation.html +++ b/_manual/01_welcome-to-ardour/02_about-ardour-documentation.html @@ -5,97 +5,104 @@ title: About Ardour documentation

Conventions Used In This Manual

-This section covers some of the typographical and language conventions -used in this manual. + This section covers some of the typographical and language conventions + used in this manual.

Keyboards and Modifiers

-Keyboard bindings are shown like this: s or x. -Ctrl x means "press the Ctrl key, keep it pressed and then also -press the x key. You may also see key combinations such as -e, which mean that you should press the   key, then while keeping it pressed also press the -  key and then while -keeping them both pressed, finally press the e key.

+ Keyboard bindings are shown like this: s or + x. +

+

+ Ctrl x means "press the Ctrl key, keep it pressed + and then also press the x key. You may also see key combinations + such as e, which mean that you should hold down + the   key and the +   key, and then while keeping them both + down, press the e key. +

-Note that different platforms have different conventions for which modifier key -(Control or Command) to use as the primary or most common modifier. When viewing -this manual from a machine identifying itself as running OS X, you will see -Cmd where appropriate (for instance in the first example above). -On other machines you will see Ctrl instead. + Note that different platforms have different conventions for which + modifier key (Control or Command) to use as the primary or most common + modifier. When viewing this manual from a machine identifying itself as + running OS X, you will see Cmd where appropriate (for instance + in the first example above). On other machines you will see Ctrl + instead.

Menu Items

-Menu items are indicated like this:
-Top > Next > Deeper. Each ">"-separated item -indicates one level of a nested (sub-)menu. + Menu items are indicated like this:
+ Top > Next > Deeper.
+ Each ">"-separated item indicates one level of a nested (sub-)menu.

Preference/Dialog Options

-Choices in various dialogs, notably the Preferences and Properties dialog, are -indicated like this:
-Edit > Preferences > Audio > Some Option. -Each successive item indicates either a (sub-) menu or a tabbed dialog -navigation. The final item is the one to choose or select. + Choices in various dialogs, notably the Preferences and Properties dialog, are + indicated like this:
+ Edit > Preferences > Audio > Some + Option.
+ Each successive item indicates either a (sub-) menu or a tabbed dialog + navigation. The final item is the one to choose or select.

-If you are requested to deselect an option, you will see something like -this:
-Edit > Preferences > Audio > Some other -Option. + If you are requested to deselect an option, you will see something like + this:
+ Edit > Preferences > Audio > Some other + Option.

Notes

-Important notes about things that might not otherwise be obvious are shown in this -format. + Important notes about things that might not otherwise be obvious are shown in + this format.

Warnings

-Hairy issues that might cause things to go wrong, lose data, or impair sound -quality is displayed in this way. + Hairy issues that might cause things to go wrong, lose data, or impair sound + quality is displayed in this way.

Mouse Buttons

-We refer to mouse buttons as -Left, Middle and -Right. Ardour can use additional buttons, but they have -no default behaviour in the program. + We refer to mouse buttons as + Left, Middle and + Right. Ardour can use additional buttons, but they have + no default behaviour in the program.

Mouse click modifiers

-Many editing functions are performed by clicking the mouse while holding a -modifier key, for example Left. - + Many editing functions are performed by clicking the mouse while holding a + modifier key, for example Left.

+

"Context-click"

-

Many times the term context-click is used to indicate -that you should (typically) right-click on a particular element of the graphical -user interface. Although right-click is the common, default way to do this, there -are other ways to accomplish the same thing - this term refers to any of them, -and the result is always that a menu specific to the item you clicked on will be -displayed. +

+ Many times the term context-click is used to indicate + that you should (typically) right-click on a particular element of the graphical + user interface. Although right-click is the common, default way to do this, there + are other ways to accomplish the same thing - this term refers to any of them, + and the result is always that a menu specific to the item you clicked on will be + displayed.

"The Pointer"

-When the manual refers to the "pointer", it means the on-screen representation -of the mouse position or the location of a touch action if you are using a touch -interface. + When the manual refers to the "pointer", it means the on-screen representation + of the mouse position or the location of a touch action if you are using a touch + interface.

Other user input

-Ardour supports hardware controllers, such as banks of faders, knobs, or buttons. + Ardour supports hardware controllers, such as banks of + faders, knobs, or + buttons.

diff --git a/_manual/01_welcome-to-ardour/03_additional-resources.html b/_manual/01_welcome-to-ardour/03_additional-resources.html index db665df..aaa8c6b 100644 --- a/_manual/01_welcome-to-ardour/03_additional-resources.html +++ b/_manual/01_welcome-to-ardour/03_additional-resources.html @@ -4,7 +4,7 @@ title: Additional Resources ---

In addition to this documentation, you may check a variety of other -resources:

+resources:

- The IRC channels in particular are where most of the day-to-day + The IRC channels in particular are where most of the day-to-day development and debugging is done, and there are plenty of experienced users to help you if you run into problems.
Please be prepared to hang around for a few hours, the chat is usually - busiest from 19:00UTC to 04:00UTC. If you can, keep your chat window open, - so that you don't miss a belated answer. + busiest from 19:00 UTC to 04:00 UTC. If you can, keep your chat + window open, so that you don't miss a belated answer.

diff --git a/_manual/02_introducing-ardour/01_creating-music-with-ardour.html b/_manual/02_introducing-ardour/01_creating-music-with-ardour.html index 63b9aa6..54e2054 100644 --- a/_manual/02_introducing-ardour/01_creating-music-with-ardour.html +++ b/_manual/02_introducing-ardour/01_creating-music-with-ardour.html @@ -26,10 +26,10 @@ title: Creating Music with Ardour material to it, which can be done in one of 3 ways:

    -
  • Record incoming audio or MIDI data, either via audio or MIDI hardware +
  • Record incoming audio or MIDI data, either via audio or MIDI hardware connected to your computer, or from other applications.
    • -
  • Create new MIDI data using the mouse and/or various dialogs
    • -
  • Import existing media files into the session
    • +
  • Create new MIDI data using the mouse and/or various dialogs
    • +
  • Import existing media files into the session

MIDI recordings consist of performance data ("play note X at @@ -59,7 +59,7 @@ title: Creating Music with Ardour

Your audio/MIDI data appears in chunks called regions, which - are arranged into horizontal lanes called tracks. Tracks are + are arranged into horizontal lanes called tracks. Tracks are stacked vertically in the Editor window. You can copy, shorten, move, and delete regions without changing the actual data stored in the session at all — Ardour is a non-destructive editor. (Almost) diff --git a/_manual/02_introducing-ardour/02_understanding-basic-concepts-and-terminology.html b/_manual/02_introducing-ardour/02_understanding-basic-concepts-and-terminology.html index 82189eb..2342147 100644 --- a/_manual/02_introducing-ardour/02_understanding-basic-concepts-and-terminology.html +++ b/_manual/02_introducing-ardour/02_understanding-basic-concepts-and-terminology.html @@ -13,7 +13,8 @@ title: Understanding Basic Concepts and Terminology

An Ardour session is a container for an entire project. A session may contain an arbitrary number of tracks and - busses consisting of audio and MIDI data, along with + busses consisting of audio and MIDI data, along with information on processing those tracks, a mix of levels, and everything else related to the project. A session might typically contain a song, or perhaps an entire album or a complete live recording. @@ -26,10 +27,11 @@ title: Understanding Basic Concepts and Terminology other details.

- Ardour's session file is kept in XML format, which is advantageous as it - is somewhat human-readable, and human-editable in a crisis. Sound files - are stored in one of a number of optional formats, and MIDI files as SMF - (standard MIDI format). + Ardour's session file is kept in + XML format, which is + advantageous as it is somewhat human-readable, and human-editable in a + crisis. Sound files are stored in one of a number of optional formats, and + MIDI files as SMF.

It is also possible for Ardour sessions to reference sound and MIDI files @@ -127,15 +129,15 @@ title: Understanding Basic Concepts and Terminology the following plugin standards:

-
LADSPA
+
LADSPA
the first major plugin standard for Linux. Many LADSPA plugins are available, mostly free and open-source.
-
LV2
+
LV2
the successor to LADSPA. Lots of plugins have been ported from LADSPA to LV2, and also many new plugins written.
-
VST
+
VST
Ardour supports VST plugins that have been compiled for Linux.
-
AudioUnit (AU)
+
AU
Mac OS X versions of Ardour support AudioUnit plugins.