[Traverso-commit] docs/manual/en installation.tex intro.tex quick...

[Nicola Doebelin]

CVSROOT:        /sources/traverso
Module name:    docs
Changes by:     Nicola Doebelin <n_doebelin>    07/11/27 19:56:54

Modified files:
        manual/en      : installation.tex intro.tex quickstart.tex 
                         setup.tex traverso-manual01.pdf 
Added files:
        manual/en/images: mac.png tux.png win.png 

Log message:
        general overhaul of the manual

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/docs/manual/en/images/mac.png?cvsroot=traverso&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/docs/manual/en/images/tux.png?cvsroot=traverso&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/docs/manual/en/images/win.png?cvsroot=traverso&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/docs/manual/en/installation.tex?cvsroot=traverso&r1=1.2&r2=1.3
http://cvs.savannah.gnu.org/viewcvs/docs/manual/en/intro.tex?cvsroot=traverso&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/docs/manual/en/quickstart.tex?cvsroot=traverso&r1=1.2&r2=1.3
http://cvs.savannah.gnu.org/viewcvs/docs/manual/en/setup.tex?cvsroot=traverso&r1=1.2&r2=1.3
http://cvs.savannah.gnu.org/viewcvs/docs/manual/en/traverso-manual01.pdf?cvsroot=traverso&rev=1.3

Patches:
Index: installation.tex
===================================================================
RCS file: /sources/traverso/docs/manual/en/installation.tex,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- installation.tex    24 Nov 2007 22:16:38 -0000      1.2
+++ installation.tex    27 Nov 2007 19:56:53 -0000      1.3
@@ -61,7 +61,7 @@
 $ make -j 2
 \end{verbatim}
 
-This will take some time, and if you followed the instructions above 
carefully, it should run through without errors. When the make process has 
finished and you get back the  command line prompt, check the last 10 lines for 
the word ``Error''. If you don't find it, everything is ok. If you find it, 
check again if you followed the instructions above correctly. Now you can 
install the software by typing the following lines:
+This will take some time, and if you followed the instructions above 
carefully, it should run through without errors. When the make process has 
finished and you get back the  command line prompt, start Traverso by typing 
\texttt{bin/traverso}. If this doesn't work, check again if you followed the 
instructions above correctly, as the compilation seems to have failed. To  
install the software, type the following lines:
 
 \begin{verbatim}
 $ sudo make install

Index: intro.tex
===================================================================
RCS file: /sources/traverso/docs/manual/en/intro.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- intro.tex   23 Nov 2007 11:50:13 -0000      1.1
+++ intro.tex   27 Nov 2007 19:56:53 -0000      1.2
@@ -1,4 +1,4 @@
-Traverso is a multitrack audio recording and editing program for GNU/Linux 
with special emphasis on an intuitive, clean, and above all efficient user 
interface. The program currently supports recording of any number of audio 
tracks (only limited by hardware capabilities), basic mixing features, and 
rendering of the  project into various standard audio file formats. The audio 
engine uses 32 bit floating point precision for all calculations to preserve 
the highest possible audio quality even after extensive processing.
+Traverso is a multitrack audio recording and editing program for GNU/Linux 
with special emphasis on an intuitive, clean, and above all efficient user 
interface. The program currently supports recording of any number of audio 
tracks (only limited by hardware capabilities), basic mixing features, writing 
to CD, and rendering of the project into various standard audio file formats. 
The audio engine uses 32 bit floating point precision for all calculations to 
preserve the highest possible audio quality even after extensive processing.
 
 The user interface uses a contextual interaction concept; instead of relying 
on the mouse to operate on graphical objects, combinations of mouse and 
keyboard are used to control the program. This results in a higher flexibility 
and much faster control of the program when compared to the traditional 
mouse-based approach. It even goes far beyond the possibilities offered by 
conventional key shortcuts. The mouse only has to be placed on an object and 
all functions become available instantly by pressing a key on the keyboard. 
Since the object under the mouse cursor is automatically selected, this concept 
is called ``soft selection''.
 
@@ -16,7 +16,7 @@
 In an analogue recording studio with a mixing desk, you have lots of channels, 
and each channel has lots of buttons, faders, knobs etc. To toggle ``Solo'' or 
``Mute'', you identify the channel strip on the mixing desk, and press the 
corresponding button. If you want to do the same with several channels, you can 
quickly press many buttons in a row. The fact that there is a dedicated button 
for each and every function (which is not always trivial to find, depending on 
the size of the desk), makes it easy to switch the button, but results in 
mixing desks being huge and complicated electronic devices.
 
 \minisec{The ``Digital Way''}
-On a conventional digital audio workstation (DAW) you identify your channel 
and press the corresponding solo or mute button with the mouse. Depending on 
the user's skills and the size of the button, this can already be a minor 
challenge. Switching several channels in a row, however, is very slow and 
inefficient, because hitting the button requires careful positioning of the 
mouse cursor each time.
+On a conventional digital audio workstation (DAW) you identify your channel 
and press the corresponding solo or mute button with the mouse. Depending on 
the user's skills and the size of the button and screen, this can already be a 
minor challenge. Switching several channels in a row, however, is very slow and 
inefficient, because hitting the button requires careful positioning of the 
mouse cursor each time.
 
 \minisec{The ``Traverso Way'': Soft Selection}
 In Traverso you move the mouse over the track you want to process, and press a 
key on the keyboard, e.g. ``U'' for mute, or ``O'' for solo. Most users hit the 
key without looking at the keyboard. The track panel is a large area, which is 
entirely sensitive for the key actions, so even if several tracks should be 
switched, the mouse cursor can be placed anywhere on the track, requiring much 
less aiming.

Index: quickstart.tex
===================================================================
RCS file: /sources/traverso/docs/manual/en/quickstart.tex,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- quickstart.tex      24 Nov 2007 22:16:38 -0000      1.2
+++ quickstart.tex      27 Nov 2007 19:56:53 -0000      1.3
@@ -1,11 +1,11 @@
 The default project automatically created by Traverso contains six empty 
tracks and is called \emph{Untitled}. So how should we get started?
 Let's just start Traverso and import a file to work on.
 
-You will need a wave audio file, or better a couple of them. You can import 
them from any location on your hard disk, or place them in your Traverso 
project directory, and further in "Untitled/audiosources" to keep you 
directories tidy. Back in Traverso, press the I key on an empty track, navigate 
to the wave files in the file dialog, and select one of them. It will be placed 
in the track, and after a couple of seconds the wave form will be drawn (it 
takes a few seconds to calculate the wave form the first time).
+You will need a wave audio file, or better a couple of them. You can import 
them from any location on your hard disk, or place them in your Traverso 
project directory, and further in ``Untitled/audiosources'' to keep you 
directories tidy. Back in Traverso, press the I key on an empty track, navigate 
to the wave files in the file dialog, and select one of them. It will be placed 
in the track, and after a couple of seconds the wave form will be drawn (it 
takes a few seconds to calculate the wave form the first time).
 
 We start listening to our imported audio file by pressing the spacebar. The 
VUMeters will show the level of the output signal. If the VUMeters are not 
visible, show them from the menu ``Views $\rightarrow$ VUMeters''. Muting the 
audio clip is done by pressing the U key while the mouse points to the audio 
clip. To unmute the clip, press U again. To make life easier, throughout this 
manual we use this notation for pressing the U key: \sact{U}. So, whenever you 
see a letter enclosed in these brackets, it means press that key once. If you 
point the cursor to the track background and press \sact{U}, the entire track 
is muted---and finally the ``mute'' button lights up!
 
-OK, what about splitting our clip into half? Point the mouse to where you want 
your clip split, and press X, the shorthand notation then will be \sact{X}. All 
of a sudden we have two clips! Use the undo button in the menu bar to undo the 
latest action. The clip will return to it's previous state.
+OK, what about splitting our clip into half? Point the mouse to where you want 
your clip split, and press X, the shorthand notation then will be \sact{X}. All 
of a sudden we have two clips! Use the undo button in the menu bar to undo the 
latest action. The clip will return to its previous state.
 
 Changing the gain of a track or audio clip is done as follows: Point your 
mouse to the audio clip, and press and hold the G key! The cursor will change 
to a gain symbol (\FigB\ \ref{fig_gaincursor}). Now move the mouse up/down, and 
see the gain value change. To make live easier again, the shorthand notation 
for keys that are pressed \emph{and} held is \hact{G}. When releasing the G 
key, the cursor returns to it's normal state, and the new gain value will be 
used. If you point the cursor to the background of the track, e.\,g. between 
two clips or to the track panel on the left (where the ``Solo'', ``Mute'', and 
``Rec'' buttons are), holding \hact{G} and moving the mouse will change the 
gain of the entire track. Instead of moving the mouse, try scrolling with the 
mouse wheel while holding \hact{G} to change the gain in very small steps. 
These actions, as you can see in the History view, are also un/redoable. You 
can also select an entry in the history view to jump directly to a certain 
state in the history.
 
@@ -23,11 +23,9 @@
  \label{fig_clipmenu}
 \end{figure}
 
-Moving the audio clip can be done by pressing the left mouse button, and 
keeping it pressed, or by doing the same with the D key. According to our 
notation scheme that would be \hact{D} or \hact{Left MouseButton}. 
Alternatively, you can just drag the audio clip with the mousecursor. You can 
move the mouse freely to position the audio clip to your own liking, the view 
will automatically scroll if the mouse comes close to the boundaries of the 
view. Also check out the \hact{Z} and \hact{S} actions to zoom and move the 
horizontal slider.
+Moving the audio clip can be done by pressing the left mouse button, and 
keeping it pressed, or by doing the same with the D key. According to our 
notation scheme that would be \hact{D}, \hact{Left MouseButton}, or \hact{LMB}. 
You can move the mouse freely to position the audio clip to your own liking, 
the view will automatically scroll if the mouse comes close to the boundaries 
of the view. Also check out the \hact{Z} and \hact{S} actions to zoom and move 
the horizontal slider.
 
 By now we learned two kinds of actions, the single key actions \sact{K}, and 
the hold actions \hact{K}. We also learned that key actions always work on the 
object beneath the mouse cursor. But before you start exploring the 
possibilities of Traverso on your own, let's look at some more (randomly 
selected) functions.
 
 If you want to reset the gain of an audio clip or track to 0 dB, point the 
mouse cursor to a clip and press the G key twice. This works just like 
double-clicking with the mouse. In our notation scheme, a double key stroke is 
notated as \dact{G}. You will see that this action first resets the gain to 0 
dB, and if called again, toggles the gain between $-6$ and 0 dB. This also 
works on the track gain.
 
-As a last example let's delete an audio clip. First select the clip by hitting 
\sact{S} on it. Its background will become dark. Then hit X and C twice at the 
same time. This action is difficult to perform, maybe you need a couple of 
attempts to get it right. But this makes the action ideal for ``dangerous'' 
function which should by no means happen accidentally. According to our 
notation scheme this function writes as \dact{X C}. An overview of all 
available action types is given in chapter \ref{sect_keyactions}. Chapters 
\ref{sect_recording} and \ref{sect_mixing} provide more detailed information on 
recording and mixing.
-

Index: setup.tex
===================================================================
RCS file: /sources/traverso/docs/manual/en/setup.tex,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- setup.tex   24 Nov 2007 22:16:38 -0000      1.2
+++ setup.tex   27 Nov 2007 19:56:53 -0000      1.3
@@ -11,7 +11,7 @@
 Traverso uses dock windows for its tool dialogs, which allows to re-arrange 
the layout to your own liking. Just grab each one by the title bar and drag it 
to a new position. You can even stack the dock widgets on top of each other or 
detach from the main window and move freely. The latter is particularly handy 
with dual-screen setups, for the main window can occupy one screen, and the 
dock windows can be moved to the second screen (\FigB\ \ref{fig_mainwin02}).
 
 \begin{figure}
- \centering\includegraphics[width=0.9\textwidth]{images/sshot03.png}
+ \centering\includegraphics[width=\textwidth]{images/sshot03.png}
  \caption{The dock windows can also be detached from the main window and moved 
to the second screen in a multi-screen setup.}
  \label{fig_mainwin02}
 \end{figure}
@@ -20,13 +20,22 @@
 Four driver backends are supported to date: The Null driver, ALSA, the jack 
soundserver, and Port Audio (on Windows and Mac OS X). Let's have a look at all 
of them, what the advantages and disadvantages are, and how to set them up 
correctly. The currently loaded driver is displayed in the menu bar.
 
 \subsection{Null Driver}
+\includegraphics[height=\baselineskip]{images/tux.png}
+\includegraphics[height=\baselineskip]{images/mac.png}
+\includegraphics[height=\baselineskip]{images/win.png}
+\\
 The Null driver is a fallback solution which is set if no other driver is 
available, but you won't hear any output as long as the Null Driver is loaded. 
Hence there's hardly a situation where you want to load it manually. To select 
a valid driver, click on the \emph{Null Driver} label in the menu bar to open a 
configuration dialog (\FigB\ \ref{fig_driverconf}).
 
 \subsection{ALSA}
-If ALSA is selected, Traverso communicates directly with the ALSA layer, which 
is only possible if no other application occupies the sound system. So before 
selecting ALSA as your driver, make sure you stop playback of all other sound 
applications. Also check the KDE/Gnome system tray for minimized instances of 
amarok, XMMS, etc. Back in Traverso's driver configuration dialog set the 
driver to \emph{ALSA}, the rate to 44100, and leave the latency. Then press 
\emph{Save} and \emph{Apply} and check if the entry in the menu bar has 
switched to \emph{ALSA}. If it refuses to load the new driver, your sound card 
may still be occupied by another application, so check again if you correctly 
stopped all multimedia applications and make sure that the sound daemon (e.\,g. 
aRTs) shuts down automatically when not used. Then try again to set the driver 
to ALSA. If it was accepted as a valid driver, the sound driver is set up 
correctly.
+\includegraphics[height=\baselineskip]{images/tux.png}
+\\
+If ALSA is selected, Traverso communicates directly with the ALSA layer, which 
is only possible if no other application occupies the sound system. So before 
selecting ALSA as your driver, make sure you stop playback of all other sound 
applications. Also check the KDE/Gnome system tray for minimized instances of 
amarok, XMMS, etc. Back in Traverso's driver configuration dialog set the 
driver to \emph{ALSA}, the rate to 44100, and leave the latency. Then press 
\emph{OK} and check if the entry in the menu bar has switched to \emph{ALSA}. 
If it refuses to load the new driver, your sound card may still be occupied by 
another application, so check again if you correctly stopped all multimedia 
applications and make sure that the sound daemon (e.\,g. aRTs) shuts down 
automatically when not used. Then try again to set the driver to ALSA. If it 
was accepted as a valid driver, the sound driver is set up correctly.
 
 \subsection{Jack}
-Traverso can also connect to the jack soundserver, which provides advanced 
routing features and zero-latency connections between clients. If you don't 
want to use these features and ALSA works for you, there's no advantage in 
using jack. We recommend to use \emph{qjackctl}, which allows to easily setup 
jack for your system. Start the jack daemon by pressing \emph{Start} in 
qjackctl. When it is running, set the driver in Traverso's configuration dialog 
(\FigB\ \ref{fig_driverconf}) to \emph{jack} and press \emph{Save} and 
\emph{Apply}. The menu bar should display \emph{jack} if the driver was loaded 
correctly. Now go back to qjackctl and open the \emph{Connect} dialog. 
\emph{Important:} You must set up the connection manually, otherwise you won't 
hear any sound. Select the Traverso entry in the left part (``Readable 
Clients''), and alsa\_pcm in the right part (``Writable Clients''), then press 
\emph{connect}. If a line connecting the two clients is drawn, the sound system 
is set up correctly.
+\includegraphics[height=\baselineskip]{images/tux.png}
+\includegraphics[height=\baselineskip]{images/mac.png}
+\\
+Traverso can also connect to the jack soundserver, which provides advanced 
routing features and zero-latency connections between clients. If you don't 
want to use these features and ALSA works for you, there's no advantage in 
using jack. We recommend to use \emph{qjackctl}, which allows to easily setup 
jack for your system. Start the jack daemon by pressing \emph{Start} in 
qjackctl. When it is running, set the driver in Traverso's configuration dialog 
(\FigB\ \ref{fig_driverconf}) to \emph{jack} and press \emph{OK}. The menu bar 
should display \emph{jack} if the driver was loaded correctly. Now go back to 
qjackctl and open the \emph{Connect} dialog. \emph{Important:} You must set up 
the connection manually, otherwise you won't hear any sound. Select the 
Traverso entry in the left part (``Readable Clients''), and alsa\_pcm in the 
right part (``Writable Clients''), then press \emph{connect}. If a line 
connecting the two clients is drawn, the sound system is set up correctly.
 
 \begin{figure}
  \centering\includegraphics[width=0.5\textwidth]{images/sshot02.png}
@@ -35,7 +44,10 @@
 \end{figure}
 
 \subsection{Port Audio}
-Port audio is the only driver backend available on Mac OS X and Microsoft 
Windows. It connects to the system's native sound system (CoreAudio on OS X, 
WMME on Windows). Simply select ``PortAudio'' in the driver configuration 
widget, the samplerate you wish to use, and a latency that works for you.
+\includegraphics[height=\baselineskip]{images/mac.png}
+\includegraphics[height=\baselineskip]{images/win.png}
+\\
+Port audio is the recommended driver backend on Mac OS X and Microsoft 
Windows. It connects to the system's native sound system (CoreAudio on OS X, 
WMME on Windows). Simply select ``PortAudio'' in the driver configuration 
widget, the samplerate you wish to use, and a latency that works for you.
 
 \section{Recording file format}
-From the menu ,,Settings $\rightarrow$ Recording file format'' you can set the 
file format used for recorded audio. \emph{Wave} has been the standard audio 
format in the computer world for years. It is uncompressed, and Traverso stores 
all audio data in 32~bit floating point precision, no matter what bit depth the 
driver backend was set to. Wave files, however, are limited to a size of 2~GB. 
For a mono recording in 44100~Hz 32~bit resolution this gives a maximum 
recording time of approximately 3 hours 20 minutes. For a stereo recording it 
is only half of that time. If you plan to record longer you should use the 
\emph{Wave-64} format instead, which can write much larger files. The third 
format \emph{WavPack} uses a lossless compression algorithm to shrink your 
files without affecting the quality of the audio data. However, since the 
encoding is done in real time, more CPU power is required while recording. If 
you are short of disk space but have a decent CPU, this format is certainly a 
good choice.
+From the menu ,,Settings $\rightarrow$ Recording file format'' you can set the 
file format used for recorded audio. \emph{Wave} has been the standard audio 
format in the computer world for years. It is uncompressed, and Traverso stores 
all audio data in 32~bit floating point precision, no matter what bit depth the 
driver backend was set to. Wave files, however, are limited to a size of 2~GB. 
For a mono recording in 44100~Hz 32~bit resolution this gives a maximum 
recording time of approximately 3 hours and 20 minutes. For a stereo recording 
it is only half of that time. If you plan to record longer you should use the 
\emph{Wave-64} format instead, which can write much larger files. The third 
format, \emph{WavPack}, uses a lossless compression algorithm to shrink your 
files without affecting the quality of the audio data. However, since the 
encoding is done in real time, more CPU power is required while recording. If 
you are short of disk space but have a decent CPU, this format is certainly a 
good choice.

Index: traverso-manual01.pdf
===================================================================
RCS file: /sources/traverso/docs/manual/en/traverso-manual01.pdf,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
Binary files /tmp/cvsMxcuhI and /tmp/cvsOib1Z9 differ

Index: images/mac.png
===================================================================
RCS file: images/mac.png
diff -N images/mac.png
Binary files /dev/null and /tmp/cvsbxxjmR differ

Index: images/tux.png
===================================================================
RCS file: images/tux.png
diff -N images/tux.png
Binary files /dev/null and /tmp/cvs6vKoTR differ

Index: images/win.png
===================================================================
RCS file: images/win.png
diff -N images/win.png
Binary files /dev/null and /tmp/cvs9a4M7R differ