more copy-editing of chapters 1+2, update style guide to reflect lessons learned.
This commit is contained in:
Jörn Nettingsmeier
parent
fdbd351eb8
commit
689d1af72a
11
STYLE_GUIDE
11
STYLE_GUIDE
@ -105,13 +105,16 @@ default choice is <p>, 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 <dfn> tags might be used to generate an index of keywords
|
||||
- don't pollute it too much.
|
||||
|
||||
<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.
|
||||
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.
|
||||
|
||||
<em>
|
||||
is used to emphasize a word. Commonly rendered as italics.
|
||||
@ -176,6 +179,8 @@ 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.
|
||||
See above for other <kbd> classes to denote menu items, selections, mouse
|
||||
events and controller actions.
|
||||
|
||||
<code>
|
||||
is only used for program code, or the content of configuration files etc. Do
|
||||
|
||||
@ -5,97 +5,104 @@ title: About Ardour documentation
|
||||
|
||||
<h2>Conventions Used In This Manual</h2>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
|
||||
<h3>Keyboards and Modifiers</h3>
|
||||
<p>
|
||||
Keyboard bindings are shown like this: <kbd>s</kbd> or <kbd class="mod1">x</kbd>.
|
||||
<kbd>Ctrl x</kbd> means "press the <kbd>Ctrl</kbd> key, keep it pressed and then also
|
||||
press the <kbd>x</kbd> key. You may also see key combinations such as
|
||||
<kbd class="mod12">e</kbd>, which mean that you should press the <kbd
|
||||
class="mod1"> </kbd> key, then while keeping it pressed also press the
|
||||
<kbd class="mod2"> </kbd> key and then while
|
||||
keeping them both pressed, finally press the <kbd>e</kbd> key.</p>
|
||||
<dfn>Keyboard bindings</dfn> are shown like this: <kbd>s</kbd> or
|
||||
<kbd class="mod1">x</kbd>.
|
||||
</p>
|
||||
<p>
|
||||
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
|
||||
<kbd>Cmd</kbd> where appropriate (for instance in the first example above).
|
||||
On other machines you will see <kbd>Ctrl</kbd> instead.
|
||||
<kbd>Ctrl x</kbd> means "press the <kbd>Ctrl</kbd> key, keep it pressed
|
||||
and then also press the <kbd>x</kbd> key. You may also see key combinations
|
||||
such as <kbd class="mod12">e</kbd>, which mean that you should hold down
|
||||
the <kbd class="mod1"> </kbd> key <em>and</em> the
|
||||
<kbd class="mod2"> </kbd> key, and then while keeping them both
|
||||
down, press the <kbd>e</kbd> key.
|
||||
</p>
|
||||
<p>
|
||||
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 <kbd>Cmd</kbd> where appropriate (for instance
|
||||
in the first example above). On other machines you will see <kbd>Ctrl</kbd>
|
||||
instead.
|
||||
</p>
|
||||
|
||||
<h3>Menu Items</h3>
|
||||
<p>
|
||||
Menu items are indicated like this:<br />
|
||||
<kbd class="menu">Top > Next > Deeper</kbd>. Each ">"-separated item
|
||||
indicates one level of a nested (sub-)menu.
|
||||
Menu items are indicated like this:<br />
|
||||
<kbd class="menu">Top > Next > Deeper</kbd>.<br />
|
||||
Each ">"-separated item indicates one level of a nested (sub-)menu.
|
||||
</p>
|
||||
|
||||
<h3>Preference/Dialog Options</h3>
|
||||
<p>
|
||||
Choices in various dialogs, notably the Preferences and Properties dialog, are
|
||||
indicated like this:<br />
|
||||
<kbd class="option">Edit > Preferences > Audio > Some Option</kbd>.
|
||||
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:<br />
|
||||
<kbd class="option">Edit > Preferences > Audio > Some
|
||||
Option</kbd>.<br />
|
||||
Each successive item indicates either a (sub-) menu or a tabbed dialog
|
||||
navigation. The final item is the one to choose or select.
|
||||
</p>
|
||||
<p>
|
||||
If you are requested to deselect an option, you will see something like
|
||||
this:<br />
|
||||
<kbd class="optoff">Edit > Preferences > Audio > Some other
|
||||
Option</kbd>.
|
||||
If you are requested to deselect an option, you will see something like
|
||||
this:<br />
|
||||
<kbd class="optoff">Edit > Preferences > Audio > Some other
|
||||
Option</kbd>.<br />
|
||||
</p>
|
||||
|
||||
|
||||
<h3>Notes</h3>
|
||||
<p class="note">
|
||||
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.
|
||||
</p>
|
||||
|
||||
<h3>Warnings</h3>
|
||||
<p class="warning">
|
||||
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.
|
||||
</p>
|
||||
|
||||
|
||||
<h3>Mouse Buttons</h3>
|
||||
<p>
|
||||
We refer to <a href="/setting-up-your-system/the-mouse">mouse buttons</a> as
|
||||
<kbd class="mouse">Left</kbd>, <kbd class="mouse">Middle</kbd> and
|
||||
<kbd class="mouse">Right</kbd>. Ardour can use additional buttons, but they have
|
||||
no default behaviour in the program.
|
||||
We refer to <a href="/setting-up-your-system/the-mouse">mouse buttons</a> as
|
||||
<kbd class="mouse">Left</kbd>, <kbd class="mouse">Middle</kbd> and
|
||||
<kbd class="mouse">Right</kbd>. Ardour can use additional buttons, but they have
|
||||
no default behaviour in the program.
|
||||
</p>
|
||||
|
||||
<h4>Mouse click modifiers</h4>
|
||||
<p>
|
||||
Many editing functions are performed by clicking the mouse while holding a
|
||||
modifier key, for example <kbd class="mouse mod1">Left</kbd>.
|
||||
|
||||
Many editing functions are performed by clicking the mouse while holding a
|
||||
modifier key, for example <kbd class="mouse mod1">Left</kbd>.
|
||||
</p>
|
||||
|
||||
<h4>"Context-click"</h4>
|
||||
<p>Many times the term <kbd class="mouse">context-click</kbd> 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.
|
||||
<p>
|
||||
Many times the term <kbd class="mouse">context-click</kbd> 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.
|
||||
</p>
|
||||
|
||||
<h3>"The Pointer"</h3>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
|
||||
<h3>Other user input</h3>
|
||||
<p>
|
||||
Ardour supports hardware controllers, such as banks of <kbd
|
||||
class="fader">faders</kbd>, <kbd class="knob">knobs</kbd>, or <kbd
|
||||
class="button">buttons</kbd>.
|
||||
Ardour supports hardware controllers, such as banks of
|
||||
<kbd class="fader">faders</kbd>, <kbd class="knob">knobs</kbd>, or
|
||||
<kbd class="button">buttons</kbd>.
|
||||
</p>
|
||||
|
||||
|
||||
@ -4,7 +4,7 @@ title: Additional Resources
|
||||
---
|
||||
|
||||
<p>In addition to this documentation, you may check a variety of other
|
||||
resources:</p>
|
||||
<dfn>resources</dfn>:</p>
|
||||
<ul>
|
||||
<li>the <a href="https://ardour.org/whatsnew.html">Ardour release
|
||||
notes</a></li>
|
||||
@ -14,10 +14,10 @@ resources:</p>
|
||||
Support</a> via mailing lists and IRC (chat)</li>
|
||||
</ul>
|
||||
<p>
|
||||
The IRC channels in particular are where most of the day-to-day
|
||||
The <dfn>IRC channels</dfn> 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.<br />
|
||||
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.
|
||||
</p>
|
||||
|
||||
@ -26,10 +26,10 @@ title: Creating Music with Ardour
|
||||
material to it, which can be done in one of 3 ways:
|
||||
</p>
|
||||
<ul>
|
||||
<li>Record incoming audio or MIDI data, either via audio or MIDI hardware
|
||||
<li><dfn>Record</dfn> incoming audio or MIDI data, either via audio or MIDI hardware
|
||||
connected to your computer, or from other applications.</li>
|
||||
<li>Create new MIDI data using the mouse and/or various dialogs</li>
|
||||
<li>Import existing media files into the session</li>
|
||||
<li><dfn>Create</dfn> new MIDI data using the mouse and/or various dialogs</li>
|
||||
<li><dfn>Import</dfn> existing media files into the session</li>
|
||||
</ul>
|
||||
<p>
|
||||
<dfn>MIDI recordings</dfn> consist of performance data ("play note X at
|
||||
@ -59,7 +59,7 @@ title: Creating Music with Ardour
|
||||
</p>
|
||||
<p>
|
||||
Your audio/MIDI data appears in chunks called <dfn>regions</dfn>, which
|
||||
are arranged into horizontal lanes called <dfn>tracks<dfn>. Tracks are
|
||||
are arranged into horizontal lanes called <dfn>tracks</dfn>. 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 <dfn>non-destructive</dfn> editor. (Almost)
|
||||
|
||||
@ -13,7 +13,8 @@ title: Understanding Basic Concepts and Terminology
|
||||
<p>
|
||||
An <dfn>Ardour session</dfn> is a container for an entire project. A
|
||||
session may contain an arbitrary number of <dfn>tracks</dfn> and
|
||||
<dfn>busses</dfn> consisting of audio and MIDI data, along with
|
||||
<dfn>busses</dfn> consisting of audio and <abbr title="Musical Instrument
|
||||
Digital Interface">MIDI</abbr> 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.
|
||||
</p>
|
||||
<p>
|
||||
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
|
||||
<abbr title="eXtensible Markup Language">XML</abbr> 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 <abbr title="Standard MIDI File">SMF</abbr>.
|
||||
</p>
|
||||
<p>
|
||||
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:
|
||||
</p>
|
||||
<dl class="wide-table">
|
||||
<dt>LADSPA</dt>
|
||||
<dt><abbr title="Linux Audio Developers' Simple Plugin API">LADSPA</abbr></dt>
|
||||
<dd>the first major plugin standard for Linux. Many LADSPA plugins are
|
||||
available, mostly free and open-source.</dd>
|
||||
<dt>LV2</dt>
|
||||
<dt><abbr title="LADSPA Version 2">LV2</abbr></dt>
|
||||
<dd>the successor to LADSPA. Lots of plugins have been ported from
|
||||
LADSPA to LV2, and also many new plugins written.</dd>
|
||||
<dt>VST</dt>
|
||||
<dt><abbr title="Virtual Studio Technology">VST</abbr></dt>
|
||||
<dd>Ardour supports VST plugins that have been compiled for Linux.</dd>
|
||||
<dt>AudioUnit (AU)</dt>
|
||||
<dt><abbr title="Audio Units">AU</abbr></dt>
|
||||
<dd>Mac OS X versions of Ardour support AudioUnit plugins.</dd>
|
||||
</dl>
|
||||
<p>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user