Add the ardour manual converted to docbook format with only a few minor

additions.

Add dbhelper.vim key stroke mappings I use for working with docbook source.

There are no xsl or css files for customizing the html output so it will 
look really boring...this will only be temporary.

Support for content localization and generation of pdf's is planned.



git-svn-id: svn://localhost/ardour2/trunk@1405 d708f5d6-7413-0410-9779-e7cbd77b26cf

1 files changed, 226 insertions, 0 deletions

diff --git a/manual/xml/working_with_playlists.xml b/manual/xml/working_with_playlists.xml
new file mode 100644
index 0000000000..f9710cca98
--- /dev/null
+++ b/manual/xml/working_with_playlists.xml
@@ -0,0 +1,226 @@
+<?xml version="1.0" standalone="no"?>
+
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+
+]>
+
+<section id="sn-working-with-playlists">
+	<title>Working with Playlists</title>
+	<para>
+		As described earlier <link linkend="gt-playlist">playlists</link> are one of
+		the central objects in a digital audio workstation. A playlist is a list of
+		<link linkend="gt-region">regions</link> ordered in time. It defines which
+		parts of which source files should be played and when.
+	</para>
+
+	<para>
+		Each track in Ardour is really just a mechanism for taking a playlist and
+		generating the audio stream that it represents. As a result, editing a track
+		really means modifying its playlist in some way. Since a playlist is a list
+		of regions, most of the modifications involve manipulating regions: their
+		position, length and so forth. This is covered in
+		<xref linkend="sn-working-with-regions"/>. Here, we cover some of the things
+		you can do with playlists as objects in their own right.
+	</para>
+
+	<section id="tracks-are-not-playlists">
+		<title> Tracks are not Playlists </title>
+		<para>
+			It is important to understand that a track is <emphasis>not</emphasis> a
+			playlist. A track is a mechanism for generating the audio stream
+			represented by the playlist and passing it through a signal processing
+			pathway. At any point in time, a track has a single playlist associated
+			with it. When the track is used to record, that playlist will have one or
+			more new regions added to it. When the track is used for playback, the
+			contents of the playlist will be heard. Old tape operators will feel
+			comfortable thinking of the playlist as the tape, and the track as the tape
+			machine.
+		</para>
+
+		<para>
+			However, you can change the playlist associated with a track at (almost)
+			any time, and even share playlists between tracks. There is more on this
+			<link linkend="playlist-operations">below</link>.
+		</para>
+	</section>
+
+	<section id="playlists-are-cheap">
+		<title> Playlists are cheap </title>
+		<para>
+			One thing you should be clear about is that playlists are cheap. They don't
+			cost anything in terms of CPU consumption, and they have very minimal
+			efforts on memory use. Don't be afraid of generating new playlists whenever
+			you want to. They are not equivalent to tracks, which require extra CPU
+			time and significant memory space, or audio files, which use disk space, or
+			to plugins that require extra CPU time. If a playlist is not in use, it
+			occupies a small amount of memory, and nothing more.
+		</para>
+	</section>
+
+	<section id="playlists-as-takes">
+		<title> Playlists as "Takes" or "Virtual Tracks" </title>
+		<para>
+			If you have a background in audio engineering, then it might be easiest for
+			you to think of playlists as "takes". This isn't a particularly useful
+			analogy by itself, and it can be misleading. But if you are working with
+			music where most tracks feature single-pass recordings of a single
+			instrument, then the idea of using one playlist per "take" can make life
+			very convenient. Each time you need to record another take, create a new
+			playlist list first. You will then end up with a simple way of switching
+			back and forth between each version, or even listening to several at the
+			same time.
+		</para>
+
+		<para>
+			If you have some experience of other DAWs, then you might have come across
+			the term "virtual track", normally defined as a track that isn't actually
+			playing or doing anything, but can be mapped/assigned to a "real track".
+			This concept is functionally identical to Ardour's playlists. We just like
+			to be little more clear about what is actually happening rather than mixing
+			old and new terminology ("virtual" and "track") into confusing terminology.
+		</para>
+	</section>
+
+	<section id="playlist-operations">
+		<title> Playlist Operations </title>
+		<para>
+			At this point, all operations on playlists start by clicking on the
+			playlist button (labelled <guibutton>p</guibutton>) in the control area of a track in the
+			editor. Clicking the button will popup a menu with the following choices:
+		</para>
+
+		<variablelist>
+			<title></title>
+			<varlistentry>
+				<term><guilabel>Current</guilabel></term>
+				<listitem>
+					<para>
+						shows the name of the current playlist used by this track
+					</para>
+				</listitem>
+			</varlistentry>
+
+			<varlistentry>
+				<term><guilabel>Rename</guilabel></term>
+				<listitem>
+					<para>
+						pops up a dialog that allows the current playlist to be renamed
+					</para>
+				</listitem>
+			</varlistentry>
+
+			<varlistentry>
+				<term><guilabel>New</guilabel></term>
+				<listitem>
+					<para>
+						creates a new <emphasis>empty</emphasis> playlist, and switches this
+						track to use it
+					</para>
+				</listitem>
+			</varlistentry>
+
+			<varlistentry>
+				<term><guilabel>New Copy</guilabel></term>
+				<listitem>
+					<para>
+						creates a new playlist that is a copy of the current playlist, and
+						switches this track to use it
+					</para>
+				</listitem>
+			</varlistentry>
+
+			<varlistentry>
+				<term><guilabel>Clear Current</guilabel></term>
+				<listitem>
+					<para>
+						removes all regions from the current playlist
+					</para>
+				</listitem>
+			</varlistentry>
+
+			<varlistentry>
+				<term><guilabel>Select</guilabel></term>
+				<listitem>
+					<para>
+						pops up a playlist browser to manually choose which playlist this track
+						should use
+					</para>
+				</listitem>
+			</varlistentry>
+		</variablelist>
+
+		<section id="renaming-playlists">
+			<title>Renaming Playlists</title>
+			<para>
+				Playlists are created with the name of the track of which they are
+				associated, plus a version number. So, the first playlist for a track
+				called "Cowbell" will be called "Cowbell.1". This name will be used to
+				define the names of any regions added to the playlist by recording. You
+				can change the name at any time, to anything you want. Ardour does not
+				require that your playlist names are all unique, but it will make your
+				life easier if they are. Suggested examples of user-assigned names for a
+				playlist might include "Lead Guitar, 2nd take", "vocals (quiet)", and
+				"downbeat cuica". Notice how these might be different from the associated
+				track names, which for these examples might be "Lead Guitar", "Vocals" and
+				"Cuica". The playlist name provides more information because it is about a
+				specific version of the material that may (or may not) end up in the final
+				version of the track.
+			</para>
+
+			<para>
+				If you are going to rename your playlists, do so before recording new
+				material to them.
+			</para>
+		</section>
+
+		<section id="selecting-playlists">
+			<title>Selecting Playlists</title>
+			<para>
+				If you click on the "Select" choice of the playlist button menu, a dialog
+				will appear that displays all playlists in a tree-structure (many will be
+				hidden). Playlists will be grouped by the track for which they were
+				created, with all those created for the current track displayed. Other
+				tracks are hidden in a collapsed tree that can be expanded as you wish to
+				find other playlists.
+			</para>
+		</section>
+
+		<section id="sharing-playlists">
+			<title>Sharing Playlists</title>
+			<para>
+				It is entirely possible to share playlists between tracks. The only
+				slightly unusual thing you may notice when sharing is that edits to the
+				playlist made in one track will magically appear in the other. If you
+				think about this for a moment, its an obvious consequence of sharing.
+			</para>
+
+			<para>
+				You might not want this kind of behaviour, even though you still want two
+				tracks to use the same (or substantially the same) playlist. To accomplish
+				this, select the chosen playlist in the second track, and then use
+				<guilabel>New Copy</guilabel> to generate an independent copy of it for
+				that track. You can then edit this playlist without affecting the
+				original.
+			</para>
+		</section>
+
+		<section id="using-playlists-for-takes">
+			<title>Using playlists for takes</title>
+			<para>
+				You have several choices here. You can obviously record new takes directly
+				over an existing one, because of the non-destructive nature of digital
+				audio editing. You can also use the <guilabel>Clear Current</guilabel>
+				operation each time you want to start a new take. This is a
+				non-destructive operation that removes all existing regions from the
+				current playlist. Although you won't lose any information doing this, its
+				probably not appropriate unless the last take was so awful that you want
+				to discard it (although without the finality of <emphasis>Remove Last
+				Capture</emphasis> ). Finally, and probably most useful, you can use the
+				<guilabel>New</guilabel> operation in the playlist button menu to create a
+				new empty playlist, ready for the next take. Later, you can
+				<guilabel>Select</guilabel> your way back to previous or later takes as
+				desired, either in this or some other track.
+			</para>
+		</section>
+	</section>
+</section>