gitara 0.5.0 → 0.6.0

data/.gitignore

@@ -3,7 +3,9 @@
 git.bundle
 .geanyprj
 .rvmrc
+.yardoc
 Gemfile.lock
+doc/*
 files/*
 pkg/*
 tmp/*

data/.yardopts

@@ -0,0 +1,5 @@
+lib
+spec
+--files CHANGELOG.markdown
+--no-private
+--plugin yard-rspec

data/CHANGELOG.markdown

@@ -1,3 +1,8 @@
+0.6.0 - 2012-04-01
+------------------
+
+* [#22] I should be able to add repeats and alternatives.
+
 0.5.0 - 2012-03-18
 ------------------
 

data/README.markdown

@@ -1,26 +1,27 @@
 Gitara is a Ruby DSL for generating Lilypond guitar tablatures
 
 
-Installation
-------------
+Usage
+-----
+
+To install,
 
     gem install gitara
 
-You need to have [lilypond](http://lilypond.org) 2.12 or higher to generate pdfs and midis.
+You need [lilypond](http://lilypond.org) 2.12 or higher in order to generate pdfs and midis.
 
-Gitara is tested on 1.9.3 only. Patches are welcome.
+Gitara is tested on Ruby 1.9.3 only. Patches are welcome.
 
 
-Usage
-------
+To run,
 
     gitara export PATH [OPTIONS]...
 
 This will generate a lilypond .ly file and then call lilypond to export the .ly file to pdf and midi. Please see `gitara help export` for the available options.
 
 
-Syntax
-------
+Basic syntax
+------------
 
 Gitara is a Ruby DSL. A typical Gitara file will have the following structure:
 
@@ -36,13 +37,13 @@ Gitara is a Ruby DSL. A typical Gitara file will have the following structure:
       end
     end
 
-You can find examples in the examples directory.
+You can find examples at https://github.com/gsmendoza/gitara/tree/master/examples.
 
 
 Bars
 ----
 
-Bars are the smallest expressions in Gitara, that is, a gitara file must have at least one bar. The notes inside a bar follow [Lilypond syntax](http://lilypond.org/doc/v2.12/Documentation/user/lilypond-learning/Simple-notation).
+Bars are the smallest expressions in Gitara. That is, a gitara file must have at least one bar. The notes inside a bar follow [Lilypond syntax](http://lilypond.org/doc/v2.12/Documentation/user/lilypond-learning/Simple-notation).
 
     Gitara.define do
       bar do
@@ -50,26 +51,31 @@ Bars are the smallest expressions in Gitara, that is, a gitara file must have at
       end
     end
 
-With Gitara, it's easier to write notes using [absolute note names](http://lilypond.org/doc/v2.12/Documentation/user/lilypond/Writing-pitches#Absolute-octave-entry) instead of relative note names. This is because we'll be reusing bars and other Gitara expressions (see Reusing bars below).
+With Gitara, it's easier to write notes using [absolute note names](http://lilypond.org/doc/v2.12/Documentation/user/lilypond/Writing-pitches#Absolute-octave-entry) instead of relative note names. This is because we'll be reusing bars and other Gitara expressions (see Reusing expressions below).
 
-Partial measures
-----------------
 
-To indicate that a bar is a [partial measure](http://lilypond.org/doc/v2.12/Documentation/user/lilypond-learning/Advanced-rhythmic-commands#Partial-measure), call `partial <duration>`:
+### Notes with single quotes and backslashes
 
-    chords :G8, 'r8-"G"'
+In Lilypond syntax, single quotes refer to octaves while backslashes refer to string numbers. So, the c note in the second string is written as
 
-    bar do
-      partial 8
-      notes "<g/3>8"
-      notes "r8"
-      chords :G8
-    end
+    c'\2
+
+Since a Gitara file is a Ruby program, you have to be careful with backslashes when writing notes like the one above. Ruby provides AFAIK two ways to preserve the backslash in the note above:
 
-As shown by the example, the durations of the chords and notes within the bar must also have one-eighth durations in order for the tab to render properly.
+    notes %q|c'\2|
 
-Multiple voices
----------------
+or
+
+    notes "c'\\2"
+
+Gitara provides a third option: it will automatically convert slashes to backslashes. This way, you can write the note above as
+
+    notes "c'/2"
+
+Prettier and easier to search and replace.
+
+
+### Multiple voices
 
 Each line of notes in a bar is a [voice](http://lilypond.org/doc/v2.12/Documentation/user/lilypond-learning/Voices-contain-music):
 
@@ -83,29 +89,47 @@ Each line of notes in a bar is a [voice](http://lilypond.org/doc/v2.12/Documenta
 The tab above will play "c d e f g a b c" and "c' d' e' f' g' a' b' c'" simultaneously, not sequentially.
 
 
-Reusing bars
-------------
+### Partial bars
 
-If you want to repeat a bar, you can name the bar and call it later:
+To indicate that a bar is a [partial measure](http://lilypond.org/doc/v2.12/Documentation/user/lilypond-learning/Advanced-rhythmic-commands#Partial-measure), call `partial <duration>`:
 
-    Gitara.define do
-      score do
-        bar :Intro do
-          notes "c d e f g a b c"
-          notes "c' d' e' f' g' a' b' c'"
-        end
+    bar do
+      partial 8
+      notes "<g/3>8"
+      notes "r8"
+    end
 
-        bar :Intro
-      end
+As shown by the example, the durations of the notes within the bar must also have one-eighth durations in order for the tab to render properly.
+
+Grouping bars together
+----------------------
+
+### Lines
+
+You can group bars in a line:
+
+    line :LineOne do
+      bar :BayangMagiliw
+      bar :PerlasNgSilanganan
+      bar :AlabNgPuso
+      bar :SaDibdibMoyBuhay
     end
 
-This will generate a tab with two Intro bars. It's important to group the two bars inside a score, because...
+Lines are [manually breaked](http://lilypond.org/doc/v2.12/Documentation/user/lilypond/Line-breaking) in Gitara.
+
+### Stanzas
 
+Lines can be grouped in stanzas. The names of a stanza will be displayed at the top of the stanza's first bar.
 
-Only the last expression under Gitara.define will be generated
---------------------------------------------------------------
 
-When writing a tab, oftentimes you want to generate only a part of the tab for testing purposes. Gitara makes this easy by processing only for the last expression under Gitara.define. For example:
+### Score
+
+Finally, stanzas can be grouped in a score. Scores are important in grouping the tab in a single unit because...
+
+
+### Only the last expression under Gitara.define will be generated
+
+When writing a tab, oftentimes you want to generate only a part of the tab for testing purposes. Gitara makes this easy by processing only for the last expression under Gitara.define. For example, in the following tab, only the second bar (notes "g a b c") will be generated.
 
     Gitara.define do
       bar do
@@ -117,7 +141,7 @@ When writing a tab, oftentimes you want to generate only a part of the tab for t
       end
     end
 
-This tab will generate only the second bar (notes "g a b c"). If you want Gitara to generate both bars, group them inside a score.
+If you want Gitara to generate both bars, you must group them inside a score.
 
     Gitara.define do
       score do
@@ -131,7 +155,7 @@ This tab will generate only the second bar (notes "g a b c"). If you want Gitara
       end
     end
 
-If you want to generate a particular bar inside the score, you can copy it after the score:
+If you want to test a particular bar inside the score, you can copy it after the score:
 
     Gitara.define do
       score do
@@ -149,78 +173,78 @@ If you want to generate a particular bar inside the score, you can copy it after
       end
     end
 
-Or you can define the bar to call later:
+Or, as you'll see below, you can give the bar a name so that you can call it later.
+
+
+Reusing expressions
+-------------------
+
+Bars, lines, and other Gitara expressions can be reused. For example, if you want a repeat a bar, you can name the bar and call the name afterwards:
 
     Gitara.define do
-      bar :FirstBar do
-        notes "c d e f"
+      score do
+        bar :Intro do
+          notes "c d e f g a b c"
+          notes "c' d' e' f' g' a' b' c'"
+        end
+
+        bar :Intro
       end
+    end
 
+This will generate a tab with two Intro bars. It's important to group the two bars above inside a score, because otherwise Gitara will only generate the second bar.
+
+You can reuse a Gitara expression as long as it is defined before the call. The definition can even be deeper than the level of the call:
+
+    Gitara.define do
       score do
-        bar :FirstBar
+        bar :testing do
+          notes "c d e f"
+        end
 
         bar do
           notes "g a b c"
         end
       end
 
-      bar :FirstBar
+      bar :testing
     end
 
+In the example above, Gitara will only generate the last :testing bar.
 
-Calling multiple bars
----------------------
-
-You can call multiple bars in a single line:
+Finally, you can call multiple expressions in a single line:
 
     bar :BayangMagiliw, :PerlasNgSilanganan, :AlabNgPuso, :SaDibdibMoyBuhay
 
 
-Lines
------
-
-You can group bars in a line:
-
-    line :LineOne do
-      bar :BayangMagiliw, :PerlasNgSilanganan, :AlabNgPuso, :SaDibdibMoyBuhay
-    end
-
-Lines are manually breaked with [\\break](http://lilypond.org/doc/v2.12/Documentation/user/lilypond/Line-breaking).
-
-Like bars, lines can be named, reused, etc.
-
-
-Stanzas
--------
-
-The names of a stanza will be displayed at the top of the stanza's first bar.
+### Repeats and alternative endings
 
-Chord labels (optional)
------------------------
-
-You can add chord labels to bars:
+You can also group expressions under [repeats](http://lilypond.org/doc/v2.12/Documentation/user/lilypond/Long-repeats) and provide alternative endings:
 
     Gitara.define do
-      chords :FC,   'r4-"F" r r-"C" r'
+      line do
+        repeat 4 do
+          bar do
+            notes "c4 d e f"
+          end
+        end
 
-      bar :BeganIt do
-        notes "/skip 4 <a/3 c'/2 >8 <g/3>8 /skip 4 <g/3 c'/2 >8 <g/3>8"
-        notes "<f/4>4 <f/4>4 <c/5>4 <e/4>4"
-        chords :FC
+        alternative do
+          bar do
+            notes "d2 e"
+          end
+
+          bar do
+            notes "f2 g"
+          end
+        end
       end
     end
 
-`r4-"F" r r-"C" r` is a [lilypond music expression](http://lilypond.org/doc/v2.12/Documentation/user/lilypond-learning/Music-expressions-explained).
-
-* `r` is a rest. `r4` is a rest that is a quarter note long. Succeeding rests have the same duration as the first one.
-* `-"F"` means 'place the text "F" below the rest note'. See http://lilypond.org/doc/v2.12/Documentation/user/lilypond/Writing-text.
-
-When these chord labels are added to the Gitara lilypond output, Gitara hides the rest notes so only the chord labels are visible.
-
 Properties
 ----------
 
-A gitara file can have the following optional properties:
+A gitara file can have the following properties:
 
     Gitara.define do
       title "Wise Up"
@@ -237,34 +261,46 @@ A gitara file can have the following optional properties:
 * arranger - tab's arranger
 * composer - song's composer
 * instrument - description of the instrument used on the tab
-* key - [key signature](http://lilypond.org/doc/v2.12/Documentation/user/lilypond/Displaying-pitches#Key-signature)
+* [key](http://lilypond.org/doc/v2.12/Documentation/user/lilypond/Displaying-pitches#Key-signature)
 * midi_instrument - the type of instrument played in the midi export of the tab. By default, "acoustic guitar (nylon)".
-* string_tunings - see [lilypond](http://lilypond.org/doc/v2.12/Documentation/user/lilypond/Common-notation-for-fretted-strings#Custom-tablatures)
-* tempo - see [lilypond](http://lilypond.org/doc/v2.12/Documentation/user/lilypond/Writing-parts#Metronome-marks) for the format
+* [string_tunings](http://lilypond.org/doc/v2.12/Documentation/user/lilypond/Common-notation-for-fretted-strings#Custom-tablatures)
+* [tempo](http://lilypond.org/doc/v2.12/Documentation/user/lilypond/Writing-parts#Metronome-marks)
 * title - title of the song
 * transposition - adjusts the pitch of the instrument. The default transposition is "c". If you set it to "d", then you have to play the tab two frets higher on the guitar (capo on second fret).
 
-Notes with single quotes and backslashes
-----------------------------------------
 
-In Lilypond syntax, single quotes refer to octaves while backslashes refer to string numbers. So, the c note in the second string is written as
+Chord labels
+------------
 
-    c'\2
+You can add chord labels to bars:
 
-Since a Gitara file is a Ruby program, you have to be careful with backslashes when writing notes like the one above. As far as I know, Ruby provides two ways to preserve the backslash in the note above:
+    Gitara.define do
+      chords :FC,   'r4-"F" r r-"C" r'
 
-    notes %q|c'\2|
+      bar :BeganIt do
+        notes "/skip 4 <a/3 c'/2 >8 <g/3>8 /skip 4 <g/3 c'/2 >8 <g/3>8"
+        notes "<f/4>4 <f/4>4 <c/5>4 <e/4>4"
+        chords :FC
+      end
+    end
 
-or
+`r4-"F" r r-"C" r` is a [lilypond music expression](http://lilypond.org/doc/v2.12/Documentation/user/lilypond-learning/Music-expressions-explained).
 
-    notes "c'\\2"
+* `r` is a rest. `r4` is a rest that is a quarter note long. Succeeding rests have the same duration as the first one.
+* `-"F"` means 'place the text "F" below the rest note'. See http://lilypond.org/doc/v2.12/Documentation/user/lilypond/Writing-text.
 
-Gitara provides a third option: it will automatically convert slashes to backslashes. This way, you can write the note above as
+When these chord labels are added to the Gitara lilypond output, Gitara hides the rest notes so only the chord labels are visible.
 
-    notes "c'/2"
+If the bar is a partial measure, the duration of the chords within the bar must match the bar's duration:
 
-Prettier and easier to search and replace.
+    chords :G8, 'r8-"G"'
 
+    bar do
+      partial 8
+      notes "<g/3>8"
+      notes "r8"
+      chords :G8
+    end
 
 Workflow
 --------

data/examples/tab-with-repeats.ly

@@ -0,0 +1,117 @@
+\version "2.12.3"
+\include "english.ly"
+
+\paper {
+ indent = #0
+}
+
+\header {
+  title = ""
+  composer = ""
+  arranger = ""
+  instrument = ""
+}
+
+%-----------------------------------------------------------------------
+% Chord Sets
+%-----------------------------------------------------------------------
+% Bars
+
+vOneBarTabOneLineOneRepeatOneBarOne = {  c4 d e f }
+cBarTabOneLineOneRepeatOneBarOne = {   }
+sBarTabOneLineOneRepeatOneBarOne = {  r1 }
+
+vOneBarTabOneLineOneAlternativeOneBarOne = {  d2 e }
+cBarTabOneLineOneAlternativeOneBarOne = {   }
+sBarTabOneLineOneAlternativeOneBarOne = {  r1 }
+
+vOneBarTabOneLineOneAlternativeOneBarTwo = {  f2 g }
+cBarTabOneLineOneAlternativeOneBarTwo = {   }
+sBarTabOneLineOneAlternativeOneBarTwo = {  r1 }
+%-----------------------------------------------------------------------
+% Lines
+
+vOneLineTabOneLineOne = { \repeat volta 4 { \vOneBarTabOneLineOneRepeatOneBarOne } \alternative { { \vOneBarTabOneLineOneAlternativeOneBarOne } { \vOneBarTabOneLineOneAlternativeOneBarTwo } } \break }
+cLineTabOneLineOne = { \repeat volta 4 { \cBarTabOneLineOneRepeatOneBarOne } \alternative { { \cBarTabOneLineOneAlternativeOneBarOne } { \cBarTabOneLineOneAlternativeOneBarTwo } } }
+sLineTabOneLineOne = { \repeat volta 4 { \sBarTabOneLineOneRepeatOneBarOne } \alternative { { \sBarTabOneLineOneAlternativeOneBarOne } { \sBarTabOneLineOneAlternativeOneBarTwo } } }
+%-----------------------------------------------------------------------
+% Stanzas
+%-----------------------------------------------------------------------
+% Scores
+%-----------------------------------------------------------------------
+% Voices
+
+vOne = {
+  \vOneLineTabOneLineOne
+}
+%-----------------------------------------------------------------------
+% Stanza Headings
+
+stanzaHeadings = { \sLineTabOneLineOne }
+
+%-----------------------------------------------------------------------
+% Chord Headings
+
+chordHeadings = { \cLineTabOneLineOne }
+
+%-----------------------------------------------------------------------
+
+\score {
+  \new StaffGroup <<
+    \new Staff <<
+      \clef "treble_8"
+
+      \new Voice \with { \remove Rest_engraver } {
+        \stanzaHeadings
+      }
+
+      \new Voice {
+        \voiceOne
+        \vOne
+      }
+    >>
+
+    \new TabStaff <<
+      \new TabVoice {
+        \slurUp
+        \vOne
+      }
+      \new TabVoice {
+        \chordHeadings
+      }
+    >>
+  >>
+
+  \layout {
+    \context { \Staff
+      \override TimeSignature #'style = #'numbered
+      \override StringNumber #'transparent = ##t
+    }
+    \context { \TabStaff
+      \override TimeSignature #'style = #'numbered
+    }
+    \context { \Voice
+      \remove Slur_engraver
+    }
+    \context { \TabVoice
+      \remove Dots_engraver
+      \remove Stem_engraver
+      \remove Rest_engraver
+    }
+  }
+}
+
+% showLastLength = R1*4
+\score {
+  \new Staff \with {midiInstrument = #"acoustic guitar (nylon)"} <<
+    \clef "treble_8"
+
+    \new Voice {
+      \unfoldRepeats {
+        \vOne
+      }
+    }
+  >>
+
+  \midi {}
+}