<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd" [
  <!ENTITY kguitar '<application>KGuitar</application>'>
  <!ENTITY kapp "&kguitar;"><!-- replace kguitar here -->
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE"><!-- change language only here -->
  
  
  <!-- Do not define any other entities; instead, use the entities
       from kde-genent.entities and $LANG/user.entities. -->
]>
<!-- kdoctemplate v0.8 October 1 1999 
     Minor update to "Credits and Licenses" section on August 24, 2000
     Removed "Revision history" section on 22 January 2001   -->

<!-- ................................................................ -->

<!-- The language must NOT be changed here. -->

<book lang="&language;">

<!-- This header contains all of the meta-information for the document such
as Authors, publish date, the abstract, and Keywords -->

<bookinfo>
<title>The &kguitar; Handbook</title>

<authorgroup>
<author>
<firstname>Mikhail</firstname>
<surname>Yakshin</surname>
<affiliation>
<address><email>greycat@users.sourceforge.net</email></address>
</affiliation>
</author>
</authorgroup>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

<copyright>
<year>2002-2003</year>
<holder>Mikhail Yakshin</holder>
</copyright>
<!-- Translators: put here the copyright notice of the translation -->
<!-- Put here the FDL notice.  Read the explanation in fdl-notice.docbook 
     and in the FDL itself on how to use it. -->
<legalnotice>&FDLNotice;</legalnotice>

<!-- Date and version information of the documentation
Don't forget to include this last date and this last revision number, we
need them for translation coordination !
Please respect the format of the date (DD/MM/YYYY) and of the version
(V.MM.LL), it could be used by automation scripts.
Do NOT change these in the translation. -->

<date>22/08/2003</date>
<releaseinfo>1.01.00</releaseinfo>

<!-- Abstract about this handbook -->

<abstract>
<para>
&kguitar; is KDE guitarist tabulature environment.
</para>
</abstract>

<!-- This is a set of Keywords for indexing by search engines.
Please at least include KDE, the KDE package it is in, the name
 of your application, and a few relevant keywords. -->

<keywordset>
<keyword>KDE</keyword>
<keyword>kguitar</keyword>
<keyword>guitar</keyword>
<keyword>tabulature</keyword>
<keyword>tab</keyword>
<keyword>editor</keyword>
<keyword>MIDI</keyword>
<keyword>MusicXML</keyword>
</keywordset>

</bookinfo>

<!-- The contents of the documentation begin here.  Label
each chapter so with the id attribute. This is necessary for two reasons: it
allows you to easily reference the chapter from other chapters of your
document, and if there is no ID, the name of the generated HTML files will vary
from time to time making it hard to manage for maintainers and for the CVS
system. Any chapter labelled (OPTIONAL) may be left out at the author's
discretion. Other chapters should not be left out in order to maintain a
consistent documentation style across all KDE apps. -->

<chapter id="introduction">
<title>Introduction</title>

<para>
&kguitar; is basically a guitar tabulature editor for K Desktop
Environment. It's much more than just a tab editor. It's features are:
</para>

<itemizedlist>

<listitem><para>Free GPLed program;</para></listitem>

<listitem><para>K Desktop Environment GUI;</para></listitem>

<listitem><para>Powerful and convenient tabulature editing, including
many effects and classical note score editing for classic instrument
players;</para></listitem>

<listitem><para>Full and very customizable MIDI to tabulature import
and export;</para></listitem>

<listitem><para>Support of extra data formats, such as ASCII
tabulatures, MusicXML or popular programs' format, such as Guitar
Pro's or TablEdit;</para></listitem>

<listitem><para>Chord fingering construction tools - chord finder
&amp; chord analyzer;</para></listitem>

<listitem><para>Many additional facilities to ease tabbing work,
including rhythm and lead construction tools;</para></listitem>

<listitem><para>Highly customizable to suit a lot of possible
instruments (not only 6-stringed guitars, and even not only guitars),
including drum tracks, lyrics and other MIDI events.</para></listitem>

</itemizedlist>
 
<para>
You may always report bugs to &kguitar; developers, using either
SourceForge.net bug tracking services, complaining in one of &kguitar;
maillists on SourceForge, or just directly mailing one of the
developers.
</para>
</chapter>

<chapter id="using-kguitar">
<title>Using &kguitar;</title>

<!-- This chapter should tell the user how to use your app. You should use as
many sections (Chapter, Sect1, Sect3, etc...) as is necessary to fully document
your application. -->

<para>
&kguitar; is a pretty complex software, but if you'll ever used any
musical notation editors, it won't be hard for you to learn &kguitar;.
</para>

<sect1 id="what-is-tab">
<title>What is a tabulature?</title>

<para>
If you're a professional guitarist who uses tabulatures in everyday's
work, then you may skip this section and head straight to <link
linkend="basic-tab-edit">tabulature editing</link>. However, if you've
never used tabulatures before, you should read this section.
</para>

<para>
Tabulatures are pretty ancient form of writing down musical
patterns. The name &quot;tabulature&quot; originates from ancient
latin &quot;tabula&quot;, a word that means &quot;a board for writing
down things&quot; (that's why the <emphasis>right</emphasis> form of
this word is <emphasis>tabulature</emphasis>, not tablature, as most
of modern sources think).
</para>

<para>
Basically, tabulature is a form of music notation for a
specific instrument which tells the performer not what to play
generally, but how to play it just right. That's the biggest
difference between standard note scores and tabulatures. In all other
aspects, they're more or less compatible and comparable.
</para>

<para>
In particular, when tabulature is written down for guitar or similar
fretted instruments (we'll refer to all them as guitar below),
tabulature contains data on what fret should be touched with one hand
and what strings should be picked with the other.
</para>

</sect1>

<sect1 id="basic-tab-edit">
<title>Basic tabulature editing</title>

<para>
Tabulature editor is a central part of &kguitar; application and
everything else seems to revolve around it.
</para>

<screenshot>
<screeninfo>A screenshot of song view</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="songview.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>Screenshot</phrase>
	  </textobject>
	</mediaobject>
</screenshot>

<para>
Song view consists of several parts: top part with the tabulature
editor itself, and the bottom part with a track manager and
editor. Track manager allows you to create multi-track songs and its
<link linkend="track-edit">track editing</link> functions would be
explained in detail later and this section will concentrate on
features of tabulature editor.
</para>

<para>
In &kguitar; tabulature editor, the most basic unit of a song is a
single column. Column is a group of notes (or rests) that begin at the
same time (well, almost, there's an exception to this rule if
tabulature effects are used) and have same duration (there're also
some exceptions). Such notes (and corresponding fret numbers for them)
are vertically aligned and form a single column of tabulature.
</para>

<para>
Your cursor is shown as an inverted square in tabulature editor. You
can move it inside tabulature column (using <keycap>Up Arrow</keycap>
and <keycap>Down Arrow</keycap> keys) and put fret number in the
column with digit keys <keycap>0</keycap>-<keycap>9</keycap>. To put a
two-digit fret number (for example, 12), just press <keycap>1</keycap>
and then press <keycap>2</keycap> - &kguitar; will detect this and
you'll get that 12 eventually. Use <keycap>Delete</keycap> to delete
entered fret numbers and make rest instead of it in this place on
selected string.
</para>

<para>
One of the very convenient features of &kguitar; is easy
transposing. For example, if you think that playing a note on 2nd
string is not convenient and 3rd string will be a better choice, just
use this function to automatically &quot;pull&quot; fret number from
2nd string to the 3rd and it will get updated accordingly to maintain
the original note pitch. Use key combos
<keycombo><keycap>Ctrl</keycap><keycap>Up Arrow</keycap></keycombo>
and <keycombo><keycap>Ctrl</keycap><keycap>Down
Arrow</keycap></keycombo> to shift fret numbers like that while moving
cursor up or down a string.
</para>

</sect1>

<sect1 id="note-durations">
<title>Note durations</title>

<para>
When transcribing a piece of music, it's essential to be able to
specify durations of notes, i.e. intervals of time they sound.
</para>

<para>
In &kguitar; every column has a duration (that's one of the major
advantages of &kguitar; over ASCII tabulatures, which provide no
rhythmic information), which are notated in normal musical form
relative to current tempo, i.e. 1/1, 1/2, 1/4, etc. You can see
current column's duration as a shape of downward stem and change
either using toolbar's duration buttons or with keys
<keycap>-</keycap> and <keycap>=</keycap> (<keycap>+</keycap>) to
halve or double current duration accordingly.
</para>

<para>
You can also use so-called &quot;dotted&quot; note durations (when
note durations have extra one half of original duration added, thus,
for example, for 1/2, making 1/2+1/4=3/4) and triplets (when note
durations are 2/3 from original, thus it's possible to fit three
triplet columns where there were only two original ones). Use key
<keycap>.</keycap> to toggle dot status of a note and use
<keycap>t</keycap> to toggle triplet status. Triplets would be
automatically shown in groups of 3 when you'll enter sufficient number
of them.
</para>

<para>
Though such column-oriented approach was critiqued a lot because of
it's mythical inflexibility, we advocate for such approache because of
it's natural simplicity in most of frequent situations. Later in this
documentation, we'll demonstrate how it can be used to <link
linkend="advanced-transcribing">transcribe even the most complex
musical figures</link>.
</para>

</sect1>

<sect1 id="bars-beats-time-signature">
<title>Bars, beats and time signature</title>

<para>
Most often, music fits some sort of rhythmic mode. Thus, for
convenience, similar musical phrases that are marked by beats are
separated with bars in musical score. Bars are supported in &kguitar;
automatically. Just fit enough note durations to fill one bar and
&kguitar; will automatically goes to the next. If you're automatical
barring will screw (if you'll delete some column in the middle of the
song, for example), use rearrange bars function, available via
<menuchoice>
<shortcut>
<keycombo><keycap>Shift</keycap><keycap>a</keycap></keycombo>
</shortcut>
<guimenu>Track</guimenu>
<guimenuitem>Arrange Bars</guimenuitem>
</menuchoice>
</para>

<para>
Quantity of beats per bar and value of one beat is called a time
signature. &kguitar; lets you set time signature using 
<menuchoice>
<shortcut>
<keycombo><keycap>Shift</keycap><keycap>t</keycap></keycombo>
</shortcut>
<guimenu>Track</guimenu>
<guimenuitem>Time Signature</guimenuitem>
</menuchoice>.

In the dialog, you'll be presented with an option either to set time
signature for current bar only or to set it from current bar to the
end of song. If you want to reset the time signature for the whole
song, remember to go to the very first bar and use this command with
&quot;to the end&quot; checkbox enabled.
</para>

</sect1>

<sect1 id="tab-effects">
<title>Tabulature Effects</title>

<para>
Tabulature can contain various guitar-specific (and not only guitar)
effects. All these things have special symbols assigned to them. You
can add effects via either pressing a hotkey or clicking on a toolbar
item.
</para>

<para>
Supported effects so far:
</para>

<itemizedlist>

<listitem><para><keycap>h</keycap> - Natural harmonic</para></listitem>
<listitem><para><keycap>r</keycap> - Artifical Harmonic</para></listitem>
<listitem><para><keycap>p</keycap> - Legato (hammer on/pull off)</para></listitem>

</itemizedlist>

</sect1>

<sect1 id="using-clipboard">
<title>Using Clipboard</title>

<para>
You can use all familiar clipboard operations in &kguitar;-edited
tabulature.
</para>

</sect1>

<sect1 id="chord-constructor">
<title>Chord Constructor</title>

<para>
TODO
</para>

</sect1>

<sect1 id="rhythm-constructor">
<title>Rhythm Constructor</title>

<para>
TODO
</para>

</sect1>

<sect1 id="advanced-transcribing">
<title>Advanced Transcribing</title>

<para>
Column-based approach to tabulature transcribing may seem inflexible
for most complex pieces of music, but it's not true. Let's demonstrate
a few examples of some intonational complexity based of note durations.
</para>

<para>
The main principle one should stick to while using column-based approach
is simple: the tabulature is about <emphasis>how</emphasis> music should
be played, not <emphasis>what</emphasis> generally should sound. This
rigidly fixes tabulature on particular instrument, but, nowadays, converting
from one type of tabulature to another is automated task you can delegate
to your computer, rather that comprehending it yourself.
</para>

<sect2 id="example-1">
<title>Example 1: Mixed duration notes</title>

<para>
We need to transcribe two notes that start at the same time, but first one
sounds for 1/8 or a beat and second one lasts for 1/4 (TODO: picture). It seem
to be impossible to do that it in column-based tabulature, as all notes stacked
in a column seem to have same duration.
</para>

<para>
Remembering the main principle mentioned above, let's think about how such a
figure would be played, for example, on a guitar. Naturally, strings are all the
same and we can assume here that they sound infinitely long if not interrupted.
How can a guitarist interrupt string sound? There are two possibilities:
</para>

<itemizedlist>

<listitem><para>He can fret some sort of other note on the same
string, thus ending the tone of previous one;</para></listitem>
<listitem><para>He can just mute the string with his finger or
palm;</para></listitem>

</itemizedlist>

<para>

</para>

<para>
TODO
</para>

</sect2>

</sect1>

<sect1 id="track-edit">
<title>Track Editing</title>

<para>
TODO
</para>

<para>
The Squiggle Tool <guiicon><inlinemediaobject>
	  <imageobject>
	    <imagedata fileref="squiggle.png" format="PNG"/>
	  </imageobject>
	  <imageobject>
	    <imagedata fileref="squiggle.eps" format="EPS"/>
	  </imageobject>
	  <textobject>
	    <phrase>Squiggle</phrase>
	  </textobject>
</inlinemediaobject></guiicon> is used to draw squiggly lines all over
the &kguitar; main window. It's not a bug, it's a feature!
</para>

</sect1>
</chapter>

<chapter id="supported-formats">
<title>Supported Formats</title>

<para>
&kguitar; supports multiple tabulature storage formats and various
options for importing/exporting. Don't seek a separate import/export
menu items, all such operations are done from normal
<menuchoice><guimenu>File</guimenu><guimenuitem>Open</guimenuitem></menuchoice>
and
<menuchoice><guimenu>File</guimenu><guimenuitem>Save</guimenuitem></menuchoice>
menus - just select the file format you want. If conversion requires
special options, you'll be presented with a separate conversion
dialog. This is exactly the same dialog as the one that appears in
&kguitar; settings menu
(<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure
KGuitar</guimenuitem></menuchoice>). If you don't want this dialog to
appear every time and just want to accept default values (which are
saved, by the way), you can uncheck the <guilabel>Show this dialog in
conversion process</guilabel>. Then, if you'll ever need to change it,
it will be accessible in
<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure
KGuitar</guimenuitem></menuchoice> dialog.
</para>

<sect1 id="format-kg">
<title>KG format</title>

<para>
KG is a native &kguitar; format that saves absolutely anything you can
have in the song. Nothing much to tell about. It's a best format if
you just want to use &kguitar; and nothing else.
</para>

</sect1>

<sect1 id="format-mid">
<title>MID format</title>

<para>
MID (MIDI file) format is currently supported for export only. MIDI
file is a file that basically contains MIDI events, i.e. directions
for a synthesizer on which notes to play, how long they should sound,
what effects and instruments should be used, etc.
</para>

<para>
Exporting to MIDI is an excelllent opportunity if you want to show the
tabulature you've created in its sounding form to anyone. Also every
computer now with a sound card has a MIDI synthesizer (or at least
there's a couple of software MIDI synths available), so good chances
are that most of the people would be able to listen to your
transcribed song. However, keep in mind that MIDI doesn't contain
tabulature information at all, i.e. no instrument tuning information
are stored, no fret numbers, nothing like that. Effects and various
guitar techniques are only approximated via special controllers to
sound similar to natural performance.
</para>

<para>
&kguitar; is able only to export MIDI files for now, but MIDI import
with automatic tabulature generation is planned to be added.
</para>

</sect1>

<sect1 id="format-xml">
<title>MusicXML format</title>

<para>
This is a relatively new format, specified by <ulink
url="http://www.recordare.com/">Recordare</ulink> and encouraged to be
used in all music-related programs. This format is based on widely
acclaimed XML and seems to be a new standard for music scores
interchange.
</para>

<para>
MusicXML is recommended if you want to share your tabulature with the
rest of the world. Most of the guitar-specific tabulature information
is preserved in MusicXML. &kguitar; is able to both import and export
MusicXML.
</para>

</sect1>

<sect1 id="format-tab">
<title>ASCII TAB format</title>

<para>
ASCII TAB is the most widely used tabulature format in the Internet,
there are numerous archives that host tabulatures in this format. It
consists of a plain text file in which the tabulature is depicted
using staves (with minus characters), numbers (digit characters) and
effects (with various letters). Among them there could be occasional
texts, playing directions, etc. There's no single standard for ASCII
tabs, so sometimes it may be a hell amount of work to comprehend a
screwed tabulature. Lots of information is often missing from ASCII
tabs, most often - the rhythm and note durations information, that
makes plainly impossible to play that tabulature if you've never heard
the song before (and even if you did, it isn't always very clear how
to do it).
</para>

<para>
&kguitar; now supports only exporting of ASCII tabs. However, if
you're going to distribute your created tabulature, we recommend you
<emphasis>not</emphasis> to do it in ASCII TAB legacy format. Due to
lots of unsaved information, a load of your hard work will be just
lost without any traces. Use <link
linkend="format-xml">MusicXML</link> for tabulature distribution, if
at all possible.
</para>

</sect1>

</chapter>

<chapter id="commands">
<title>Command Reference</title>

<!-- (OPTIONAL, BUT RECOMMENDED) This chapter should list all of the
application windows and their menubar and toolbar commands for easy reference.
Also include any keys that have a special function but have no equivalent in the
menus or toolbars. This may not be necessary for small apps or apps with no tool
or menu bars. -->

<sect1 id="kguitar-mainwindow">
<title>The main &kguitar; window</title>
<para></para>

<sect2>
<title>The File Menu</title>
<para>
<variablelist>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>n</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>New</guimenuitem>
</menuchoice></term>
<listitem><para><action>Creates a new document</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>s</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>Save</guimenuitem>
</menuchoice></term>
<listitem><para><action>Saves the document</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>q</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>Quit</guimenuitem>
</menuchoice></term>
<listitem><para><action>Quits</action> &kguitar;</para></listitem>
</varlistentry>
</variablelist>
</para>

</sect2>

</sect1>
</chapter>

<chapter id="faq">
<title>Questions and Answers</title>

<!-- (OPTIONAL but recommended) This chapter should include all of the silly
(and not-so-silly) newbie questions that fill up your mailbox. This chapter
should be reserved for BRIEF questions and answers! If one question uses more
than a page or so then it should probably be part of the
"Using this Application" chapter instead. You should use links to
cross-reference questions to the parts of your documentation that answer them.
This is also a great place to provide pointers to other FAQ's if your users
must do some complicated configuration on other programs in order for your
application work. -->

&reporting.bugs;
&updating.documentation;

<qandaset id="faqlist">
<qandaentry>
<question>
<para>My Mouse doesn't work. How do I quit &kguitar;?</para>
</question>
<answer>
<para>You silly goose! Check out the <link linkend="commands">Commands
Section</link> for the answer.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Why can't I twiddle my documents?</para>
</question>
<answer>
<para>You can only twiddle your documents if you have the foobar.lib
installed.</para>
</answer>
</qandaentry>
</qandaset>
</chapter>

<chapter id="credits">

<title>Credits and License</title>

<para>
KGuitar team includes developers:

<itemizedlist>
<listitem><para>Mikhail Yakshin AKA GreyCat <email>greycat@users.sourceforge.net</email>
</para></listitem>
<listitem><para>Alexander Brand AKA alinx <email>alinx@users.sourceforge.net</email>
</para></listitem>
<listitem><para>Leon Vinken <email>lvinken@users.sourceforge.net</email>
</para></listitem>
<listitem><para>Matt Malone <email>Marlboro@users.sourceforge.net</email>
</para></listitem>
</itemizedlist>
</para>

<para>
Documentation copyright 2002 Mikhail Yakshin <email>greycat@users.sourceforge.net</email>
</para>

<para>
Translation is done by:

<itemizedlist>
<listitem><para>Wilane Ousmane <email>wilane@users.sourceforge.net</email>
</para></listitem>
<listitem><para>Harri Haataja <email>realblades@users.sourceforge.net</email>
</para></listitem>
<listitem><para>Stephan Borchert <email>sborchert@users.sourceforge.net</email>
</para></listitem>
<listitem><para>Richard G. Roberto <email>robertor@users.sourceforge.net</email>
</para></listitem>
<listitem><para>Riccardo &quot;FeAC&quot; Vitelli <email>feac@users.sourceforge.net</email>
</para></listitem>
</itemizedlist>

</para>

&underFDL;
&underGPL;

</chapter>

<appendix id="installation">
<title>Installation</title>

<sect1 id="getting-kguitar">
<title>How to obtain &kguitar;</title>

<para>
Latest version of &kguitar;, as well as the latest development news
and information can always be obtained from <ulink
url="http://kguitar.sourceforge.net/">&kguitar;'s homepage</ulink>. Or
look for kguitar or similar package in your favorite distribution.
</para>

</sect1>

<sect1 id="requirements">
<title>Requirements</title>

<para>
In order to successfully use &kguitar;, you need KDE 3.x. TSE3 (Trax
Sequencer Engine 3) library is very recommended for all MIDI-related
capabilities of &kguitar;. There are no special hardware requirements,
though having MIDI synthesizer (either full-blown external keyboard or
an internal one, integrated on your sound-card) is a big plus that
will let you use all MIDI features.
</para>

<para>
TSE3 library can be found at <ulink
url="http://tse3.sourceforge.net/">TSE3 home page</ulink>.
</para>

</sect1>

<sect1 id="compilation">
<title>Compilation and Installation</title>

<para>
In order to compile and install &kguitar; on your system, type the
following in the base directory of the &kguitar; distribution:
<screen width="40">
<prompt>%</prompt> <userinput>./configure</userinput>
<prompt>%</prompt> <userinput>make</userinput>
<prompt>%</prompt> <userinput>make install</userinput>
</screen>
</para>

<para>Since &kguitar; uses autoconf and automake you should have not
trouble compiling it. Should you run into problems please report them
to &kguitar; team.</para>

</sect1>

<sect1 id="configuration">
<title>Configuration</title>

<para>Don't forget to tell your system to start the <filename>dtd</filename>
dicer-toaster daemon first, or KApp won't work !</para>

</sect1>

</appendix>

&documentation.index;
</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:
-->