<?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 & 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 "tabulature" originates from ancient latin "tabula", a word that means "a board for writing down things" (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 "pull" 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 "dotted" 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 "to the end" 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 "FeAC" 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: -->