File: doc.html

package info (click to toggle)
songwrite 0.12b-4
links: PTS
area: main
in suites: sarge
size: 984 kB
ctags: 989
sloc: python: 6,321; xml: 850; makefile: 10
file content (790 lines) | stat: -rw-r--r-- 34,504 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD><TITLE></TITLE>

<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.06">
</HEAD>
<BODY >
<!--HEVEA command line is: hevea -o ./doc/en/doc.html /tmp/@3609.0.hva ./doc/en/doc.tex -->
<!--HTMLHEAD-->
<!--ENDHTML-->
<!--PREFIX <ARG ></ARG>-->
<!--CUT DEF section 1 -->


<H1 ALIGN=center>Songwrite documentation</H1>

<H3 ALIGN=center><FONT COLOR=navy>Jean-Baptiste ``Jiba'' LAMY (jiba@tuxfamily.org)</FONT></H3>
Copyright (c) 2002-2003 Lamy Jean-Baptiste.<BR>
<BR>
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation; with
the Invariant Sections being this foreword part.<BR>
<BR>
<!--TOC section Table of Contents-->

<H2>Table of Contents</H2><!--SEC END -->

<UL><LI>
<A HREF="#htoc1">1&nbsp;&nbsp;Introduction</A>
<UL><LI>
<A HREF="#htoc2">1.1&nbsp;&nbsp;Supported file formats</A>
<LI><A HREF="#htoc3">1.2&nbsp;&nbsp;Mailing list</A>
<LI><A HREF="#htoc4">1.3&nbsp;&nbsp;Historical stuff about GTablature</A>
<LI><A HREF="#htoc5">1.4&nbsp;&nbsp;Future direction</A>
</UL>
<LI><A HREF="#htoc6">2&nbsp;&nbsp;Configuration</A>
<LI><A HREF="#htoc7">3&nbsp;&nbsp;Creating a song</A>
<UL><LI>
<A HREF="#htoc8">3.1&nbsp;&nbsp;Song properties</A>
<LI><A HREF="#htoc9">3.2&nbsp;&nbsp;Rhythm</A>
<LI><A HREF="#htoc10">3.3&nbsp;&nbsp;Repeat / playlist</A>
<LI><A HREF="#htoc11">3.4&nbsp;&nbsp;File menu</A>
<LI><A HREF="#htoc12">3.5&nbsp;&nbsp;Edit menu</A>
<LI><A HREF="#htoc13">3.6&nbsp;&nbsp;Zoom</A>
</UL>
<LI><A HREF="#htoc14">4&nbsp;&nbsp;Managing partitions</A>
<UL><LI>
<A HREF="#htoc15">4.1&nbsp;&nbsp;Partition properties</A>
<LI><A HREF="#htoc16">4.2&nbsp;&nbsp;Adding new partitions</A>
</UL>
<LI><A HREF="#htoc17">5&nbsp;&nbsp;Using tablatures</A>
<UL><LI>
<A HREF="#htoc18">5.1&nbsp;&nbsp;Adding notes</A>
<LI><A HREF="#htoc19">5.2&nbsp;&nbsp;Notes properties</A>
<LI><A HREF="#htoc20">5.3&nbsp;&nbsp;Special effects</A>
<LI><A HREF="#htoc21">5.4&nbsp;&nbsp;Tuning</A>
<LI><A HREF="#htoc22">5.5&nbsp;&nbsp;Keyboard shortcuts</A>
</UL>
<LI><A HREF="#htoc23">6&nbsp;&nbsp;Staff</A>
<LI><A HREF="#htoc24">7&nbsp;&nbsp;Using drums</A>
<LI><A HREF="#htoc25">8&nbsp;&nbsp;Using lyrics</A>
<UL><LI>
<A HREF="#htoc26">8.1&nbsp;&nbsp;Vocals</A>
<LI><A HREF="#htoc27">8.2&nbsp;&nbsp;Lyrics</A>
<LI><A HREF="#htoc28">8.3&nbsp;&nbsp;Conversion</A>
<LI><A HREF="#htoc29">8.4&nbsp;&nbsp;Drums ``tuning''</A>
</UL>
<LI><A HREF="#htoc30">9&nbsp;&nbsp;Selection and copy/paste</A>
<LI><A HREF="#htoc31">10&nbsp;&nbsp;Printing</A>
<UL><LI>
<A HREF="#htoc32">10.1&nbsp;&nbsp;Configuration</A>
<LI><A HREF="#htoc33">10.2&nbsp;&nbsp;Print!</A>
</UL>
<LI><A HREF="#htoc34">11&nbsp;&nbsp;Songbook</A>
<LI><A HREF="#htoc35">12&nbsp;&nbsp;Songwrite internals</A>
<UL><LI>
<A HREF="#htoc36">12.1&nbsp;&nbsp;Intro to dynamic programming</A>
<LI><A HREF="#htoc37">12.2&nbsp;&nbsp;Data types</A>
<LI><A HREF="#htoc38">12.3&nbsp;&nbsp;Views</A>
</UL>
<LI><A HREF="#htoc39">13&nbsp;&nbsp;How can I help you with Songwrite?</A>
</UL>

<!--TOC section Introduction-->

<H2><A NAME="htoc1">1</A>&nbsp;&nbsp;Introduction</H2><!--SEC END -->

Songwrite is a tablature editor and player (with Timidity or another
Midi player), destined to Linux-user guitarists. It is written in
Python, and relies on GNU Lilypond (Lilypond <A HREF="http://www.lilypond.org">)</A>
for printing.<BR>
<BR>
See the README file for installation and requirements.<BR>
<BR>
Songwrite is Free Software. It is available under GNU GPL (doc under
GNU FDL).<BR>
<BR>
Pleased the author: do not confound "Free Software"
and "Freeware"! In addition to being "Freeware",
a Free Software is available as source code; it is allowed to modify
and redistribute freely these sources. Thanks to these liberties,
Free Softwares are an alternative to capitalism; respect it and join
the revolution!<BR>
<BR>
<!--TOC subsection Supported file formats-->

<H3><A NAME="htoc2">1.1</A>&nbsp;&nbsp;Supported file formats</H3><!--SEC END -->
<BR>
<TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1>
<TR><TD ALIGN=center NOWRAP>Format</TD>
<TD ALIGN=center NOWRAP>read</TD>
<TD ALIGN=center NOWRAP>write</TD>
<TD ALIGN=center NOWRAP>comments</TD>
</TR>
<TR><TD ALIGN=center NOWRAP>SongWrite format</TD>
<TD ALIGN=center NOWRAP>X</TD>
<TD ALIGN=center NOWRAP>X</TD>
<TD ALIGN=center NOWRAP>XML format</TD>
</TR>
<TR><TD ALIGN=center NOWRAP>Old format</TD>
<TD ALIGN=center NOWRAP>X</TD>
<TD ALIGN=center NOWRAP>&nbsp;</TD>
<TD ALIGN=center NOWRAP>Plain Python serialization (<TT>pickle</TT>)</TD>
</TR>
<TR><TD ALIGN=center NOWRAP>Midi</TD>
<TD ALIGN=center NOWRAP>X</TD>
<TD ALIGN=center NOWRAP>X</TD>
<TD ALIGN=center NOWRAP>&nbsp;</TD>
</TR>
<TR><TD ALIGN=center NOWRAP>Rich Midi Tablature</TD>
<TD ALIGN=center NOWRAP>&nbsp;</TD>
<TD ALIGN=center NOWRAP>E</TD>
<TD ALIGN=center NOWRAP>Midi with meta event for string numbers, ... EXPERIMENTAL</TD>
</TR>
<TR><TD ALIGN=center NOWRAP>Ascii tablature</TD>
<TD ALIGN=center NOWRAP>E</TD>
<TD ALIGN=center NOWRAP>X</TD>
<TD ALIGN=center NOWRAP>Import works with SongWrite Ascci tab, but may not work with other...</TD>
</TR>
<TR><TD ALIGN=center NOWRAP>Guitar pro 3-4</TD>
<TD ALIGN=center NOWRAP>E</TD>
<TD ALIGN=center NOWRAP>&nbsp;</TD>
<TD ALIGN=center NOWRAP>&nbsp;</TD>
</TR>
<TR><TD ALIGN=center NOWRAP>Lilypond</TD>
<TD ALIGN=center NOWRAP>&nbsp;</TD>
<TD ALIGN=center NOWRAP>X</TD>
<TD ALIGN=center NOWRAP>No lyrics</TD>
</TR>
<TR><TD ALIGN=center NOWRAP>L<sup>A</sup>T<sub>E</sub>X and LyliPond</TD>
<TD ALIGN=center NOWRAP>&nbsp;</TD>
<TD ALIGN=center NOWRAP>X</TD>
<TD ALIGN=center NOWRAP>Tablature with Lilypond, lyrics with L<sup>A</sup>T<sub>E</sub>X</TD>
</TR>
<TR><TD ALIGN=center NOWRAP>PostScript</TD>
<TD ALIGN=center NOWRAP>&nbsp;</TD>
<TD ALIGN=center NOWRAP>X</TD>
<TD ALIGN=center NOWRAP>Printable</TD>
</TR></TABLE><BR>
``E'' means EXPERIMENTAL (=not or not enough tested) and ``X''
fully supported.<BR>
<BR>
The Midi importation has been tested on Midi files generated by Songwrite,
GNU Lilypond, Tabledit and NoteWorthy Composer.<BR>
<BR>
Since the 0.9 version, Songwrite uses a new human-readable XML file
format (see file <TT>songwrite.schema.xml</TT>, not tested yet). Files
saved with the old format can be turned to the new XML format by opening
them into Songwrite and then saving them, or with the <TT>convert_to_xml</TT>
script. This script takes as arguments the list of file to convert
(<EM>e.g.</EM> <TT>convert_to_xml /tablatures/*</TT>).<BR>
<BR>
<!--TOC subsection Mailing list-->

<H3><A NAME="htoc3">1.2</A>&nbsp;&nbsp;Mailing list</H3><!--SEC END -->

To subscribe to the Songwrite mailing, send a mail at Songwrite-subscribe@oomadness.tuxfamily.org.
To unsuscribe, send a mail to Songwrite-unsubscribe@oomadness.tuxfamily.org.<BR>
<BR>
<!--TOC subsection Historical stuff about GTablature-->

<H3><A NAME="htoc4">1.3</A>&nbsp;&nbsp;Historical stuff about GTablature</H3><!--SEC END -->

Songwrite was previously known as ``GTablature''. The name has
been changed since it no longer belong to the Gnome project. Gtk is
now replaced by Tk.<BR>
<BR>
GTablature's users will found Songwrite very similar to GTablature,
and the file format is compatible!<BR>
<BR>
To summarize, my reasons for leaving the Gnome project are the following:
<UL><LI>
The new version of Gnome (Gnome 2) has lots of incompatibilities with
the previous one. In particular, the Python binding for Gtk 1 and
2 cannot be installed at the same time.<BR>
As i was not ready to re-design the UI part of my application each
time the Gnome guys decide to make a new release, i switched to Tk.
<LI>The dark spectrum of .net was floating over Gnome. My favorite language
is Python, and contrary to what you may think, Python.net is NOT Python.
It is .net, exactely like C++.net is .net and not C++ (have you ever
seen a C++ without multiple inheritance?).
</UL>
<!--TOC subsection Future direction-->

<H3><A NAME="htoc5">1.4</A>&nbsp;&nbsp;Future direction</H3><!--SEC END -->

See the TODO file for more info.<BR>
<BR>
<!--TOC section Configuration-->

<H2><A NAME="htoc6">2</A>&nbsp;&nbsp;Configuration</H2><!--SEC END -->

The first time you launch Songwrite, the configuration dialog popups.
The default configuration should be right for any Linux distributions;
you may just be interested by using a different Midi player (such
as ``playmidi %s'' if your sound card supports Midi).<BR>
<BR>
To change the configuration later, use the <FONT COLOR=purple>edit&nbsp;<FONT FACE=symbol>|></FONT>&nbsp;preferences...</FONT>
menu.<BR>
<BR>
<!--TOC section Creating a song-->

<H2><A NAME="htoc7">3</A>&nbsp;&nbsp;Creating a song</H2><!--SEC END -->

<!--TOC subsection Song properties-->

<H3><A NAME="htoc8">3.1</A>&nbsp;&nbsp;Song properties</H3><!--SEC END -->

The main document you edit in Songwrite is called a ``song'' (sorry
if you just play guitar without singing :-). When Songwrite is launched,
it creates a new song for you, and display it in a new window.<BR>
<BR>
<IMG SRC="startup.png"><BR>
<BR>
A song is composed of many partitions. The word ``partitions''
should be understood here in a very large meaning: it includes guitar
tablatures, but also lyrics, drums,... and other (in the future).<BR>
<BR>
Obviously the song has also some basic information about it, like
its title or its authors. You can change them in the song properties
dialog box, available through the <FONT COLOR=purple>song&nbsp;<FONT FACE=symbol>|></FONT>&nbsp;properties</FONT>
menu, or clicking on the blue link on the top of the main window.
Notice that the title, the author and the comments are shown at the
top of the main window.<BR>
<BR>
The language property of the song is intended for lyrics; it is given
to L<sup>A</sup>T<sub>E</sub>X when printing. It defaults to your current language.<BR>
<BR>
<IMG SRC="songprop.png"><BR>
<BR>
The song property dialog shows your song properties. The tree view
at the top of the window displays the song's structure and the different
partitions; it can be used to change the currently edited object and
you can click on the violet triangle to show/hide the children items.
The bottom part of the window shows the properties of the current
object (by default, the song).<BR>
<BR>
<!--TOC subsection Rhythm-->

<H3><A NAME="htoc9">3.2</A>&nbsp;&nbsp;Rhythm</H3><!--SEC END -->

The <FONT COLOR=purple>song</FONT> menu offers also different playing functions, and
the <FONT COLOR=purple>song&nbsp;<FONT FACE=symbol>|></FONT>&nbsp;rhythm</FONT> menu can be used to change the
tempo and the rhythm of any bar. The syncope picking option is destined
to finger-picking song, and consists in playing the first half of
each time two time longer than the second one.<BR>
<BR>
If no notes are selected, the rhythm of ALL bars is edited. If some
notes are selected, only the bars with at least one selected note
in it are edited. Only x/4 and y/8 (where y = 3, 6, 9, 12,...) rhythms
are supported.<BR>
<BR>
<!--TOC subsection Repeat / playlist-->

<H3><A NAME="htoc10">3.3</A>&nbsp;&nbsp;Repeat / playlist</H3><!--SEC END -->

Click the <FONT COLOR=purple>song&nbsp;<FONT FACE=symbol>|></FONT>&nbsp;repeat...</FONT> menu to get the repeat
dialog box. To add an item, select the notes of the bars your want
to add (at least one par bar), and click <FONT COLOR=purple>Add...</FONT>. Use the
<FONT COLOR=purple>Remove</FONT>, <FONT COLOR=purple>Up</FONT> and <FONT COLOR=purple>Down</FONT> button to remove or
move the playlist's items. You can also modify an item by selecting
it, and changing its values, or by selecting new bars and then clicking
the <FONT COLOR=purple>Do</FONT> button. The first bar is #0.<BR>
<BR>
<IMG SRC="repeat.png">
<DL COMPACT=compact><DT>
<B>Bug</B><DD>Only playlist which can be translated into musical symbols are
correctly shown and printed.
</DL>
<!--TOC subsection File menu-->

<H3><A NAME="htoc11">3.4</A>&nbsp;&nbsp;File menu</H3><!--SEC END -->

The <FONT COLOR=purple>file</FONT> menu can be used to open or save your work, and
to import or export it in other format (Midi, ...). Click on <FONT COLOR=purple>file&nbsp;<FONT FACE=symbol>|></FONT>&nbsp;create
new window</FONT> to get a new Songwrite window, and edit many songs at
the same time. <FONT COLOR=purple>file&nbsp;<FONT FACE=symbol>|></FONT>&nbsp;new file</FONT> creates a new song
in the current window.<BR>
<BR>
<!--TOC subsection Edit menu-->

<H3><A NAME="htoc12">3.5</A>&nbsp;&nbsp;Edit menu</H3><!--SEC END -->

To finish with, the <FONT COLOR=purple>edit</FONT> menu allows to cancel or redo any
operation, so as you can feel cool when editing tablatures ;-) Multiple
cancelments are supported.<BR>
<BR>
The <FONT COLOR=purple>edit&nbsp;<FONT FACE=symbol>|></FONT>&nbsp;preference...</FONT> menu displays the configuration
dialog.<BR>
<BR>
<!--TOC subsection Zoom-->

<H3><A NAME="htoc13">3.6</A>&nbsp;&nbsp;Zoom</H3><!--SEC END -->

The - and + button on the right of the toolbar allows you to change
the horizontal zoom level.<BR>
<BR>
<!--TOC section Managing partitions-->

<H2><A NAME="htoc14">4</A>&nbsp;&nbsp;Managing partitions</H2><!--SEC END -->

<!--TOC subsection Partition properties-->

<H3><A NAME="htoc15">4.1</A>&nbsp;&nbsp;Partition properties</H3><!--SEC END -->

Songwrite displays the different partitions vertically, just below
the song's title and comments. When launched, Songwrite adds a new
tablature to your song.<BR>
<BR>
Each partition has two parts: a header (the ``guitar'' label)
and the partition itself. The header can be used to display some comments
or information about the partition, about who plays it, ... i guess
you'll find it useful ;-)<BR>
<BR>
Songwrite totally separates the <EM>data</EM> of the partition, <EM>e.g.</EM>
the notes, and the <EM>view</EM> that display them, e.g. the tablature.
This means that it is possible to change the view of a partition.
For example, right click on the partition header, and it uses the
hidden view instead of the tablature view, and collapses in a one-line
bar. Click again to return to the previous view.<BR>
<BR>
Click the blue ``property'' link on the partition header to get
the partition properties dialog box, or click the <FONT COLOR=purple>partition&nbsp;<FONT FACE=symbol>|></FONT>&nbsp;properties</FONT>
menu. The dialog box allows to change different parameters, and may
differ for the different views:
<UL><LI>
volume
<LI>muted
<LI>chorus
<LI>reverb
<LI>header
<LI>instrument: choose the Midi instrument to use for this partition
<LI>tonality
<LI>view: allows to change the partition's view. Mainly used to convert
tablature into staff, or staff into tablature.
</UL>
<!--TOC subsection Adding new partitions-->

<H3><A NAME="htoc16">4.2</A>&nbsp;&nbsp;Adding new partitions</H3><!--SEC END -->

The <FONT COLOR=purple>partition</FONT> menu offers to add new partitions for different
type of instruments. Add some of them to try!<BR>
<BR>
Just Click on a partition to select it. Songwrite displays a pastel
blue box around the selected partition. The <FONT COLOR=purple>partition&nbsp;<FONT FACE=symbol>|></FONT>&nbsp;move
up</FONT>, <FONT COLOR=purple>partition&nbsp;<FONT FACE=symbol>|></FONT>&nbsp;move down</FONT> and <FONT COLOR=purple>partition&nbsp;<FONT FACE=symbol>|></FONT>&nbsp;delete</FONT>
menus can be used to move or delete the current partition.<BR>
<BR>
The number of partition is not limited, though Midi playing is limited
to 16 channels. In Songwrite, each musical partition (<EM>i.e.</EM>
not lyric!) takes one channel, or two if it contains notes with special
effect (see below). So you can have at least 7 instruments.<BR>
<BR>
<!--TOC section Using tablatures-->

<H2><A NAME="htoc17">5</A>&nbsp;&nbsp;Using tablatures</H2><!--SEC END -->

Tablatures are probably the most awaited partitions! A tablature can
be added by the <FONT COLOR=purple>partition&nbsp;<FONT FACE=symbol>|></FONT>&nbsp;new string instrument</FONT>
submenus.<BR>
<BR>
For each tablature, Songwrite displays one line for each string on
the instrument (see below if you want more or less strings or a custom
tuning). As in a real guitar, higher strings are thinner than lower
one. The vertical grey line you can see in the middle is a bar. Don't
bother about it, Songwrite add them automatically if you add a note
after the last bar.<BR>
<BR>
<!--TOC subsection Adding notes-->

<H3><A NAME="htoc18">5.1</A>&nbsp;&nbsp;Adding notes</H3><!--SEC END -->

You can use the mouse (left click) or the cursor's key to move in
the tablature.<BR>
<BR>
To add a note on the tablature, just click were you want to add it,
and type the corresponding fret number (fret number superior to 9
are OK, or even 158! Just type several figures successively, <EM>e.g.</EM>
``1'', ``2'' for 12). If the midi player is well configured,
Songwrite will play the notes when you enter them.<BR>
<BR>
You can change the note duration by clicking on the corresponding
buttons in the tool-bar. The width of the selection corresponds to
the duration. As accentuation is very important in guitar playing,
you can also toggle accentuation with the stressed button. Stressed
notes are played stronger, and displayed in red.<BR>
<BR>
Notice that, when moving the selected position, Songwrite takes the
current note's duration into account. If you want to move with a smaller
step, select a shorter note duration.<BR>
<BR>
The <FONT COLOR=purple>note&nbsp;<FONT FACE=symbol>|></FONT>&nbsp;arrange at fret...</FONT> menu can be used to
organize the selected notes on the strings so as they are played after
the choosen fret. Usefull after a Midi importation!<BR>
<BR>
<!--TOC subsection Notes properties-->

<H3><A NAME="htoc19">5.2</A>&nbsp;&nbsp;Notes properties</H3><!--SEC END -->

Double click on a selected note (or a group of selected notes), or
click the <FONT COLOR=purple>note&nbsp;<FONT FACE=symbol>|></FONT>&nbsp;properties</FONT> menu to get the note
dialog box. This window allows to set different properties:
<UL><LI>
value: the note's pitch (in semi-tons; the note's name is displayed
on the left)
<LI>duration (where 64 is a musical time unit; the note's duration name
is displayed on the right)
<LI>volume (the volume can be controlled with the accentuation button
too)
<LI>special effects (see below)
</UL>
<!--TOC subsection Special effects-->

<H3><A NAME="htoc20">5.3</A>&nbsp;&nbsp;Special effects</H3><!--SEC END -->

Songwrite supports most of the special effects that can be played
on a guitar: hammer/pull, slide, dead notes, bend, tremolo, roll...
are all here! For effects that link two notes (hammers and slides),
the effect must be set on the first note. For rolls, the effect must
be set on <EM>all</EM> the note of the corresponding chord, and not
only the lower one.<BR>
<BR>
<IMG SRC="special.png">
<DL COMPACT=compact><DT>
<B>Bug</B><DD>It is not possible to put more than one special effect on a
single note :-(
<DT><B>Bug</B><DD>Slide and hammer combination of more than 5 semi-tons cannot
be played with Midi.
</DL>
<!--TOC subsection Tuning-->

<H3><A NAME="htoc21">5.4</A>&nbsp;&nbsp;Tuning</H3><!--SEC END -->

The partition properties dialog box (or the song dialog box) allows
to change the guitar tuning, or to add or remove strings. If you play
another string-based instrument (banjo, mandolin, ...), please mail
me the tuning so i can add it in the next release!<BR>
<BR>
<IMG SRC="tuning.png"><BR>
<BR>
Songwrite allows also to choose for each string if the stems and the
beams are drawn at the top or at the bottom of the tablature. By default,
the three upper strings draw their stems and beams at the top, and
the three lower ones at the bottom. To add a new string, select the
partition and then click the <FONT COLOR=purple>Add...</FONT> button. To remove a string,
select it and click the <FONT COLOR=purple>remove</FONT> button. The <FONT COLOR=purple>move up</FONT>
and <FONT COLOR=purple>move down</FONT> button can be used to modify the order of the
strings.<BR>
<BR>
<!--TOC subsection Keyboard shortcuts-->

<H3><A NAME="htoc22">5.5</A>&nbsp;&nbsp;Keyboard shortcuts</H3><!--SEC END -->

<DL COMPACT=compact><DT>
 
 
 
cursor&nbsp;keys<DD>move the current position
<DT>tab,&nbsp;shift&nbsp;tab<DD>go the next or the previous note on the same string
<DT>page&nbsp;up,&nbsp;down<DD>go to the previous or the next measure
<DT>origin,&nbsp;end<DD>go to the beginning or the end of the song
<DT>+,&nbsp;-<DD>increase or decrease the note pitch
<DT>/,&nbsp;*<DD>increase or decrease the note duration
<DT>.<DD>toggle doted duration
<DT>return<DD>toggle accentuation
<DT>del<DD>delete all selected notes
<DT>n<DD>normal (remove special effect)
<DT>s<DD>slide to the following note
<DT>h<DD>hammer, pull or legato
<DT>b<DD>bend
<DT>t<DD>tremolo
<DT>d<DD>dead note
<DT>r<DD>roll
<DT>space<DD>plays from the current position
</DL>
<!--TOC section Staff-->

<H2><A NAME="htoc23">6</A>&nbsp;&nbsp;Staff</H2><!--SEC END -->

In addition to tablature, SongWrite supports staffs too. However,
staff support is quite limited; it may satisfy a guitarist but probably
not a pianist! The <FONT COLOR=purple>partition&nbsp;<FONT FACE=symbol>|></FONT>&nbsp;new staff&nbsp;<FONT FACE=symbol>|></FONT>&nbsp;...</FONT>
menu allows to add a new staff. The partition properties dialog box
allows to choose the tonality.<BR>
<BR>
<IMG SRC="staff.png"><BR>
<BR>
To insert notes, right-click at the right position, or use the ``+''
or ``-'' keys. These keys can also move the selected notes up
or down. To add more lines above or below the staff, put a note at
the top or bottom limit, and press ``+'' or ``-''.<BR>
<BR>
<!--TOC section Using drums-->

<H2><A NAME="htoc24">7</A>&nbsp;&nbsp;Using drums</H2><!--SEC END -->

Drums sets can be added with the <FONT COLOR=purple>partition&nbsp;<FONT FACE=symbol>|></FONT>&nbsp;new
drums&nbsp;<FONT FACE=symbol>|></FONT>&nbsp;new ...</FONT> menus; different drums instruments are proposed.
I DON'T play drums, so any suggestion is welcome. In particular, i'd
like to know what are the ``patch'' provided by a standard drums
set!<BR>
<BR>
The current drums view doesn't use any ``official'' or standard
drums notation (sorry i don't them!), but rather a really easy tablature-like
system. Songwrite display a line (similar to a guitar string) for
each drum patch; the name of the coressponding midi patch is written
on the left of the line. Right click (or press ``+'') on the line
to play a drum; drums are visualized as an ``X'' on the line.
Right click again or press ``-'' to remove the drum.<BR>
<BR>
<IMG SRC="drums.png"><BR>
<BR>
<!--TOC section Using lyrics-->

<H2><A NAME="htoc25">8</A>&nbsp;&nbsp;Using lyrics</H2><!--SEC END -->

<!--TOC subsection Vocals-->

<H3><A NAME="htoc26">8.1</A>&nbsp;&nbsp;Vocals</H3><!--SEC END -->

First, enter the lyrics' vocals, with a staff or, why not, a tablature
(if, like me, you don't know how to read a staff ;-).<BR>
<BR>
<!--TOC subsection Lyrics-->

<H3><A NAME="htoc27">8.2</A>&nbsp;&nbsp;Lyrics</H3><!--SEC END -->

Lyrics can be added through the <FONT COLOR=purple>partition&nbsp;<FONT FACE=symbol>|></FONT>&nbsp;new lyrics</FONT>
menu. They must be placed <EM>just below</EM> the melody. Typically,
one would use a different lyrics set for each verse and refrain.<BR>
<BR>
Then, click on the lyrics' rectangle and type the text. SongWrite
automaticaly aligns the syllabes on the vocals, and moves them correctly
if the melody if changed after that. The following keys has a special
function:
<DL COMPACT=compact><DT>
 
 
 
space,&nbsp;tab<DD>go to the next syllabe
<DT>-<DD>go to the next syllabe, and cut the current word
<DT>_<DD>go to the next syllabe, and continue the previous syllabe on
the current note
<DT>two&nbsp;backslashes<DD>end a line
<DT>return<DD>new sentence on the same vocals. If several sentences must
be sung on the same vocals, don't copy the vocals!
</DL>
The following example summarizes all of that, and shows two verses
of a famous hacker song (you can find it in the demo directory of
SongWrite).<BR>
<BR>
<IMG SRC="lyrics.png"><BR>
<BR>
Finally, as the final print out is done with Lilypond and L<sup>A</sup>T<sub>E</sub>X,
you can use L<sup>A</sup>T<sub>E</sub>X code in the lyrics!<BR>
<BR>
<!--TOC subsection Conversion-->

<H3><A NAME="htoc28">8.3</A>&nbsp;&nbsp;Conversion</H3><!--SEC END -->

Since version 0.8, SongWrite has a new lyric system, which allows
per-note lyrics instead of per-mesure lyrics. A link (in blue) propose
to convert the old lyrics into the new format; however the conversion
is not totally automated :-( In particular you need to cut the word
manually (by typing ``-'').<BR>
<BR>
<!--TOC subsection Drums ``tuning''-->

<H3><A NAME="htoc29">8.4</A>&nbsp;&nbsp;Drums ``tuning''</H3><!--SEC END -->

As guitar strings, the drums lines can be ``tuned'' between the
different patches. The drums's view properties dialog box is very
similar to the tablature one, and allows you to change the patch of
each line, and to add or remove lines.
<DL COMPACT=compact><DT>
<B>Bug</B><DD>Using several times the same drum patch in a drums partition
can give strange results.
</DL>
<!--TOC section Selection and copy/paste-->

<H2><A NAME="htoc30">9</A>&nbsp;&nbsp;Selection and copy/paste</H2><!--SEC END -->

Songwrite has a pretty advanced copy/paste system. You can select
many notes/... by drawing a box with the mouse; ``heterogeneous''
selection are supported, that is to say you can select notes of different
partition, at the same time, in the same selection! Impressive, isn't
it? Then click on one of the selected notes/items to move the selection
horizontally or vertically. Right-click when moving if you want to
cancel.<BR>
<BR>
Songwrite use a Linux-like copy/paste system: anything that is selected
is automatically copied. Then just middle-click to paste the selection;
keep the middle button pressed and move the mouse to adjust the exact
pasting position.<BR>
<BR>
Notice that Songwrite use the current note's duration to align the
pasted notes horizontally.<BR>
<BR>
<!--TOC section Printing-->

<H2><A NAME="htoc31">10</A>&nbsp;&nbsp;Printing</H2><!--SEC END -->

Printing is still an experimental feature, though it can already yield
impressive parts! Tablatures are printed by Lilypond, with the tablature
patch i have written for it, and lyrics are printed with L<sup>A</sup>T<sub>E</sub>X,
but you don't need to know Lilypond or L<sup>A</sup>T<sub>E</sub>X to print with Songwrite!<BR>
<BR>
<!--TOC subsection Configuration-->

<H3><A NAME="htoc32">10.1</A>&nbsp;&nbsp;Configuration</H3><!--SEC END -->

To print your work with Songwrite, you need Lilypond and L<sup>A</sup>T<sub>E</sub>X.
Lilypond is available at <A HREF="www.lilypond.org">.</A> You'll need Lilypond
&gt;= 1.7. At the end of the Lilypond install, don't forget to place
the TeX font intialization script, as demanded. See the end of
the output of Lilypond's ``make install'', reproduced here:
<DIV ALIGN=left><DL COMPACT=compact><DT><DD><TT>
***&nbsp;Before&nbsp;running,&nbsp;buildscripts/out/lilypond-{profile,login}<BR>
<BR>
***&nbsp;must&nbsp;be&nbsp;run.&nbsp;You're&nbsp;advised&nbsp;to&nbsp;source&nbsp;these&nbsp;scripts&nbsp;from&nbsp;your<BR>
<BR>
***&nbsp;login&nbsp;scripts.&nbsp;For&nbsp;more&nbsp;information,&nbsp;see&nbsp;Invoking&nbsp;LilyPond&nbsp;in&nbsp;the&nbsp;manual.
</TT></DL></DIV>
<!--TOC subsection Print!-->

<H3><A NAME="htoc33">10.2</A>&nbsp;&nbsp;Print!</H3><!--SEC END -->

The following things are not yet supported while printing:
<UL><LI>
special effects other than hammers/pulls. Hammers/pulls are rendered
as ``normal'' slurs.
<LI>triplets without 3 notes in it (linked notes are right).
<LI>more than 2 notes at the same time, but not in a chord (=with different
duration). This should never occurs in a real tab.
</UL>
<!--TOC section Songbook-->

<H2><A NAME="htoc34">11</A>&nbsp;&nbsp;Songbook</H2><!--SEC END -->

<IMG SRC="songbook.png"><BR>
<BR>
A song groups many songs in order to print them together or to access
them more easily.<BR>
<BR>
The <FONT COLOR=purple>File&nbsp;<FONT FACE=symbol>|></FONT>&nbsp;New songbook...</FONT> allows to create a new
songbook. Then use the <FONT COLOR=purple>Add...</FONT> button to add song into the
songbook (you can only add songs that are saved on the disk). Be carefull,
SongWrite does not save the songs inside the songbook, but only their
filename, so you must keep your song files!<BR>
<BR>
Click a song in the book to open it in a new window.<BR>
<BR>
To print the songbook, click the <FONT COLOR=purple>(Preview) print</FONT> button.<BR>
<BR>
<!--TOC section Songwrite internals-->

<H2><A NAME="htoc35">12</A>&nbsp;&nbsp;Songwrite internals</H2><!--SEC END -->

<!--TOC subsection Intro to dynamic programming-->

<H3><A NAME="htoc36">12.1</A>&nbsp;&nbsp;Intro to dynamic programming</H3><!--SEC END -->

Songwrite is fully Python written, and use the dynamic features of
the language as much as possible, as well as some technics comming
from aspect-oriented programming<SUP><A NAME="text1" HREF="#note1"><FONT SIZE=2>1</FONT></A></SUP>. Yes, it's full of amazing hacks, but why should i use a dynamic
language if i don't use it fully? In this subsection, i try to explain
why dynamic hackish coding is so great<SUP><A NAME="text2" HREF="#note2"><FONT SIZE=2>2</FONT></A></SUP>.<BR>
<BR>
I do believe that politics, as well as the vision of the ``ideal''
society you have, influences your way of coding. As an anarchist hacker,
it is normal for my code to be so hackish! But it does work, and it
follows it own logic.<BR>
<BR>
Many people try to have a global vision of what they are coding. They
are wrong, because, the bigger your project is, the more difficult
this approach will be! The method i propose is the following: just
design a society of objects, each of which having a specific role
and doing its job. And let the objects be themselves, let them having
their own life. When all objects do their job, the work is done! You
<EM>do not</EM> need to understand how the global work is performed,
but only how each object does its little job. And so, if a project
is twice bigger, it just requires twice as many objects, and so twice
as many work for you. No more!<BR>
<BR>
<!--TOC subsection Data types-->

<H3><A NAME="htoc37">12.2</A>&nbsp;&nbsp;Data types</H3><!--SEC END -->

The <TT>song.py</TT> pure-Python module defines all the data for song,
partitions and notes objects. It is totally independent of the rest
of Songwrite and so can be easily re-used in other (GPL'ed) programs.<BR>
<BR>
The <TT>song</TT> object has a list of partitions called <TT>partitions</TT>.
This list contains partitions, lyrics, ... anything that can be added
to a song; all these classes of objects inherits from the class <TT>TemporalData</TT>
(<EM>e.g.</EM> <TT>Partition</TT>, <TT>Lyrics</TT>, ...). Any <TT>TemporalData</TT>
is composed of a list of sub-items, typically called <TT>notes</TT>
(for <TT>Lyrics</TT>, the list is called <TT>lyrics</TT> and aliased
with <TT>notes</TT>); the class of these sub-items depends on the
<TT>TemporalData</TT> class: <TT>Note</TT> (or subclasses) for <TT>Partition</TT>,
<TT>Lyric</TT> for <TT>Lyrics</TT>, ...<BR>
<BR>
Special effects are treated as different subclasses of <TT>Note</TT>.
The <TT>LinkedNote</TT> class is used for any note that is linked
with another (as a source or as a destination), and <TT>HammerNote</TT>
and <TT>SlideNote</TT> are subclasses of it. Notes that are linked
from another one but doesn't have any effect (e.g. the second note
of a hammer) are <TT>LinkedNote</TT>.<BR>
<BR>
Drums are just <TT>Partition</TT> and <TT>Note</TT> exactely as other.
The only difference is that it use the 128th instruments, which is
out the range of the standard midi instruments, and Songwrite maps
this value to drums.<BR>
<BR>
<!--TOC subsection Views-->

<H3><A NAME="htoc38">12.3</A>&nbsp;&nbsp;Views</H3><!--SEC END -->

Views are defined in the <TT>view.py</TT> module. Importing this module
modify the <TT>TemporalData</TT> class so it now has a <TT>view</TT>
property, with the corresponding methods.<BR>
<BR>
The <TT>view.py</TT> module also defines the <TT>View</TT> and <TT>GraphicNote</TT>
base classes. Songwrite use a view for each partition, and the view
creates a <EM>graphic note</EM> for each note (or lyric, ...) the partition
has. Graphic notes typically creates some Tkinter canvas item in the
Songwrite canvas to represent the corresponding note.<BR>
<BR>
<!--TOC section How can I help you with Songwrite?-->

<H2><A NAME="htoc39">13</A>&nbsp;&nbsp;How can I help you with Songwrite?</H2><!--SEC END -->

<UL><LI>
Send me your suggestions!
<LI>New intrument tunings are welcome too!
<LI>Translate Songwrite to your native language: Songwrite use the standard
GNU Gettext system; just translate the Songwrite.po file in the locale
directory!
<LI>Improve this documentation.
<LI>Port Songwrite to other OS. As it now uses Tk, porting Songwrite should
be really easy. The only real problem is the dependencies: Timidity
and Lilypond. The former can easily be replaced by any other Midi
player, but not the latter...
<LI>Set up a web-based database of free partition for Songwrite!
<LI>Write import/export filter for new format: this is relatively easy
since you only need to look at the <TT>song.py</TT> module.
<LI>Write new views. For advanced coders!
<LI>See the TODO file for more suggestions.</UL>
<!--BEGIN NOTES document-->
<HR WIDTH="50%" SIZE=1><DL><DT><A NAME="note1" HREF="#text1"><FONT SIZE=5>1</FONT></A><DD><A HREF="http://aopd.net">E</A>.g. see how the <TT>view</TT> module adds
a new mother class to the <TT>song.TemporalData</TT> class, or see
the <TT>editobj.eventobj</TT> module (in EditObj).
<DT><A NAME="note2" HREF="#text2"><FONT SIZE=5>2</FONT></A><DD>Hey&nbsp;? What about a book about that&nbsp;? Something like ``the hacker
hackish way of coding''&nbsp;? It would be a graceful change from all
those methodologic books about UML&nbsp;! And maybe the first book that
really learns how to code.
</DL>
<!--END NOTES-->
<!--HTMLFOOT-->
<!--ENDHTML-->
<!--FOOTER-->
<HR SIZE=2>
<BLOCKQUOTE><EM>This document was translated from L<sup>A</sup>T<sub>E</sub>X by
</EM><A HREF="http://pauillac.inria.fr/~maranget/hevea/index.html"><EM>H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A</EM></A><EM>.
</EM></BLOCKQUOTE>
</BODY>
</HTML>