gly 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 341817505f45deff8e6c9815061fa6cffa571858
-  data.tar.gz: 64ff6cb093190e69c37ed874af5c9b34e1499c3f
+  metadata.gz: a1be7280dd39aa6117888f6779c409359202d8bb
+  data.tar.gz: b5bc60c05106a3472b4fa296cc0787f1c804ab8f
 SHA512:
-  metadata.gz: 41ba343096d37f095b7e9ca1724a8692d7bf4ca6dfcac689e681e9c61c1c95067ec42ba18f6fa8de259f6bf70b1960e5108f1f2503be1044e8df64bb0ec6fa96
-  data.tar.gz: a14a88215832854321ecadff5fd0f0c01a057d3ad991873aede7d91b879da35edfe197bca214144a55a4ad4ff893d0a365505849ce62020b9da7361a5fe9a2e8
+  metadata.gz: d695541f34baae56918b864e062387426889b55dbed9e1636688157c1b4eadec906556be053de0b4da8f3a588c1fe415a12104ae844a5045471bfd91dfcec32c
+  data.tar.gz: 8aab9514701279b9e4ab1f00282e323902924c5f9b38fcf2ab1aa2fd9e534759a8a62220a38fa72d08ec0711eb78fb78c499760b97ea901458bcf93c326d7415

data/lib/gly.rb

@@ -1,5 +1,14 @@
 module Gly; end
 
-%w(parser gabc_convertor parsed_score headers lyrics document string_helpers).each do |mod|
+%w(parser
+gabc_convertor
+parsed_score
+headers
+lyrics
+document
+document_gabc_convertor
+preview_generator
+lister
+string_helpers).each do |mod|
   require "gly/#{mod}"
 end

data/lib/gly/cli.rb

@@ -5,90 +5,37 @@ module Gly
   class CLI < Thor
     desc 'gabc FILE ...', 'convert gly to gabc'
     def gabc(*files)
-      files.each {|f| gabc_convert(parse(f)) }
+      files.each {|f| DocumentGabcConvertor.new(Parser.new.parse(f)).convert }
     end
 
     desc 'preview FILE ...', 'convert to gabc AND generate pdf preview'
     def preview(*files)
-      files.each {|f| make_preview f }
+      files.each {|f| PreviewGenerator.new.process(Parser.new.parse(f)) }
     end
 
-    private
-
-    def parse(gly_file)
-      document = File.open(gly_file) do |fr|
-        Parser.new.parse(fr)
-      end
-    end
-
-    def gabc_convert(doc)
-      doc.scores.each_with_index do |score, si|
-        score_id = score.headers['id'] || si.to_s
-        out_fname = File.basename(doc.path)
-                    .sub(/\.gly\Z/i, "_#{score_id}.gabc")
-        File.open(out_fname, 'w') do |fw|
-          GabcConvertor.new.convert score, fw
-        end
-        yield score, out_fname if block_given?
+    desc 'list FILE ...', 'list scores contained in files'
+    option :recursive, type: :boolean, aliases: :r, banner: 'recursively traverse directories', default: false
+    def list(*files)
+      if files.empty?
+        STDERR.puts 'No file specified.'
+        exit 1
       end
-    end
-
-    def make_preview(gly_file)
-      doc = parse(gly_file)
-
-      tex_header = <<EOS
-% LuaLaTeX
-
-\\documentclass[a4paper, 12pt]{article}
-\\usepackage[latin]{babel}
-\\usepackage[left=2cm, right=2cm, top=2cm, bottom=2cm]{geometry}
-
-\\usepackage{fontspec}
 
-% for gregorio
-\\usepackage{luatextra}
-\\usepackage{graphicx}
-\\usepackage{gregoriotex}
-
-\\title{#{doc.header['title']}}
-
-\\begin{document}
-
-#{doc.header['title'] && '\\maketitle'}
-
-EOS
-
-      tex_fname = File.basename(gly_file).sub(/\.gly\Z/i, '.tex')
-      File.open(tex_fname, 'w') do |fw|
-        fw.puts tex_header
-
-        gabc_convert(doc) do |score, gabc_fname|
-          system "gregorio #{gabc_fname}"
-          gtex_fname = gabc_fname.sub /\.gabc/i, ''
-          piece_title = %w(book manuscript arranger author).collect do |m|
-            score.headers[m]
-          end.delete_if(&:nil?).join ', '
-          fw.puts "\\commentary{\\footnotesize{#{piece_title}}}\n" unless piece_title.empty?
-
-          annotations = score.headers.each_value('annotation')
-          begin
-            fw.puts "\\setfirstannotation{#{annotations.next}}"
-            fw.puts "\\setsecondannotation{#{annotations.next}}"
-          rescue StopIteration
-            # ok, no more annotations
+      if options[:recursive]
+        files = files.collect do |f|
+          if File.directory?(f)
+            Dir[File.join(f, '**/*.gly')]
+          else
+            f
           end
-
-          fw.puts "\\includescore{#{gtex_fname}}\n\\vspace{1cm}"
         end
-
-        # tagline
-        fw.puts "\n\\vfill\n\\begin{center}"
-        fw.puts "\\texttt{gly preview https://github.com/igneus/gly}"
-        fw.puts "\\end{center}\n"
-        fw.puts "\n\\end{document}"
+        files.flatten!
       end
 
-      system "lualatex #{tex_fname}"
+      lister = Lister.new(files)
+      lister.list(STDOUT, STDERR)
+
+      exit(lister.error? ? 1 : 0)
     end
   end
 end

data/lib/gly/document_gabc_convertor.rb

@@ -0,0 +1,34 @@
+module Gly
+  class DocumentGabcConvertor
+    def initialize(document)
+      @doc = document
+    end
+
+    def convert
+      each_score_with_gabcname do |score, out_fname|
+        File.open(out_fname, 'w') do |fw|
+          GabcConvertor.new.convert score, fw
+        end
+        yield score, out_fname if block_given?
+      end
+    end
+
+    # iterates over document scores,
+    # yields score and filename of it's generated gabc file
+    def each_score_with_gabcname
+      @doc.scores.each_with_index do |score, si|
+        yield score, output_fname(score, si)
+      end
+    end
+
+    private
+
+    def output_fname(score, score_index=nil)
+      score_id = score.headers['id'] || score_index.to_s
+      score_id = '_' + score_id unless score_id.empty?
+
+      File.basename(@doc.path)
+        .sub(/\.gly\Z/i, "#{score_id}.gabc")
+    end
+  end
+end

data/lib/gly/document_gabc_convertor.rb~

@@ -0,0 +1,23 @@
+module Gly
+  class DocumentGabcConvertor
+    def initialize(document)
+      @doc = document
+    end
+
+    def convert
+      @doc.scores.each_with_index do |score, si|
+        score_id = score.headers['id'] || si.to_s
+        out_fname = File.basename(doc.path)
+                    .sub(/\.gly\Z/i, "_#{score_id}.gabc")
+        File.open(out_fname, 'w') do |fw|
+          GabcConvertor.new.convert score, fw
+        end
+        yield score, out_fname if block_given?
+      end
+    end
+
+    def output_fname(input_fname, score_id=nil)
+
+    end
+  end
+end

data/lib/gly/gabc_convertor.rb

@@ -1,5 +1,7 @@
+require 'stringio'
+
 module Gly
-  # converts parsed gly to gabc
+  # takes ParsedScore, translates it to gabc
   class GabcConvertor
     def convert(score, out=StringIO.new)
       score.headers.each_pair do |key,value|
@@ -41,7 +43,7 @@ module Gly
     end
 
     def differentia?(chunk)
-      chunk =~ /\A*[,;:]+\Z/ # differentia
+      chunk =~ /\A*[,;:`]+\Z/ # differentia
     end
 
     # is the given music chunk capable of bearing lyrics?

data/lib/gly/lister.rb

@@ -0,0 +1,32 @@
+module Gly
+  class Lister
+    def initialize(files)
+      @files = files
+      @error = false
+    end
+
+    def list(io, errio)
+      @files.each do |f|
+        begin
+          document = Parser.new.parse(f)
+        rescue SystemCallError => err # Errno::WHATEVER
+          errio.puts "Cannot read file '#{f}': #{err.message}"
+          @error = true
+          next
+        end
+
+        io.puts
+        io.puts "== #{f}"
+
+        document.scores.each do |s|
+          l = s.lyrics.readable
+          io.puts l unless l.empty?
+        end
+      end
+    end
+
+    def error?
+      @error
+    end
+  end
+end

data/lib/gly/lister.rb~

@@ -0,0 +1,29 @@
+module Gly
+  class Lister
+    def initialize(files)
+      @files = files
+    end
+
+    def list(io, errio)
+      was_error = false
+
+      files.each do |f|
+        begin
+          document = parse(f)
+        rescue SystemCallError => err # Errno::WHATEVER
+          errio.puts "Cannot read file '#{f}': #{err.message}"
+          was_error = true
+          next
+        end
+
+        puts
+        puts "== #{f}"
+
+        document.scores.each do |s|
+          l = s.lyrics.readable
+          puts l unless l.empty?
+        end
+      end
+    end
+  end
+end

data/lib/gly/lyrics.rb

@@ -23,7 +23,11 @@ module Gly
     end
 
     def_delegator :@words, :each, :each_word
-    def_delegators :@words, :empty?, :<<
+    def_delegators :@words, :<<, :empty?
+
+    def readable
+      @words.collect(&:readable).join ' '
+    end
   end
 
   class Word
@@ -35,5 +39,12 @@ module Gly
 
     def_delegators :@syllables, :<<, :push
     def_delegator :@syllables, :each, :each_syllable
+
+    def readable
+      without_directives = @syllables.collect do |s|
+        s.start_with?('!') ? s[1..-1] : s
+      end
+      without_directives.join
+    end
   end
 end

data/lib/gly/parser.rb

@@ -1,9 +1,37 @@
+require 'stringio'
+
 module Gly
   # parses gly source
   class Parser
-    SYLLABLE_SEP = '--'
+    def initialize(syllable_separator='--')
+      @syllable_separator = syllable_separator
+    end
+
+    def parse(source)
+      if source.is_a? String
+        if File.file? source
+          parse_fname source
+        elsif source == '-'
+          parse_io STDIN
+        else
+          parse_str source
+        end
+      else
+        parse_io source
+      end
+    end
+
+    def parse_fname(str)
+      File.open(str) do |fr|
+        parse_io fr
+      end
+    end
+
+    def parse_str(str)
+      parse_io(StringIO.new(source))
+    end
 
-    def parse(io)
+    def parse_io(io)
       @doc = Document.new
       @score = ParsedScore.new
 
@@ -61,7 +89,7 @@ module Gly
     EXPLICIT_LYRICS_RE = /\A\\l(yrics)?\s+/
 
     def lyrics_line?(str)
-      str =~ EXPLICIT_LYRICS_RE || str.include?(SYLLABLE_SEP) || contains_unmusical_letters?(str)
+      str =~ EXPLICIT_LYRICS_RE || str.include?(@syllable_separator) || contains_unmusical_letters?(str)
     end
 
     def in_header_block?
@@ -83,16 +111,15 @@ module Gly
       # separator
       str
         .sub(EXPLICIT_LYRICS_RE, '')
-        .split(/(?<!#{SYLLABLE_SEP})\s+(?!#{SYLLABLE_SEP})/)
+        .split(/(?<!#{@syllable_separator})\s+(?!#{@syllable_separator})/)
         .each do |word|
-        @score.lyrics << Word.new(word.split(/\s*#{SYLLABLE_SEP}\s*/))
+        @score.lyrics << Word.new(word.split(/\s*#{@syllable_separator}\s*/))
       end
     end
 
     def parse_music(str)
       # music chunks: split by whitespace out of brackets
-      str.split(/\s+/).each do |chunk|
-        chunk.sub!(/\A\((.*?)\)\Z/, '\1') # unparenthesize
+      StringHelpers.music_split(str).each do |chunk|
         @score.music << chunk
       end
     end

data/lib/gly/preview_generator.rb

@@ -0,0 +1,48 @@
+require 'stringio'
+
+module Gly
+  # Takes Gly::Document, builds a pdf preview
+  # (or at least generates all necessary assets)
+  class PreviewGenerator
+    def process(document)
+      tpl_name = File.join(File.dirname(__FILE__), 'templates/lualatex_document.tex')
+      template = File.read(tpl_name)
+
+      doc_body = fw = StringIO.new
+
+      convertor = DocumentGabcConvertor.new(document)
+      convertor.each_score_with_gabcname do |score, gabc_fname|
+        system "gregorio #{gabc_fname}"
+        gtex_fname = gabc_fname.sub /\.gabc/i, ''
+        piece_title = %w(book manuscript arranger author).collect do |m|
+          score.headers[m]
+        end.delete_if(&:nil?).join ', '
+        fw.puts "\\commentary{\\footnotesize{#{piece_title}}}\n" unless piece_title.empty?
+
+        annotations = score.headers.each_value('annotation')
+        begin
+          fw.puts "\\setfirstannotation{#{annotations.next}}"
+          fw.puts "\\setsecondannotation{#{annotations.next}}"
+        rescue StopIteration
+          # ok, no more annotations
+        end
+
+        fw.puts "\\includescore{#{gtex_fname}}\n\\vspace{1cm}"
+      end
+
+      replacements = {
+        title: document.header['title'],
+        maketitle: (document.header['title'] && '\maketitle'),
+        body: doc_body.string
+      }
+      tex = template % replacements
+
+      out_fname = File.basename(document.path).sub(/\.gly\Z/i, '.tex')
+      File.open(out_fname, 'w') do |fw|
+        fw.puts tex
+      end
+
+      system "lualatex #{out_fname}"
+    end
+  end
+end

data/lib/gly/preview_generator.rb~

@@ -0,0 +1,7 @@
+module Gly
+  # Takes Gly::Document, builds a pdf preview
+  # (or at least generates all necessary assets)
+  class PreviewGenerator
+
+  end
+end

data/lib/gly/string_helpers.rb

@@ -1,7 +1,7 @@
 module Gly
   module StringHelpers
     extend self
-    
+
     # splits string by whitespace that is not enclosed
     # in brackets.
     # At the same time removes brackets.
@@ -12,10 +12,16 @@ module Gly
       in_brackets = false
       str.chars.each_with_index do |char, chi|
         if in_brackets
-          next if char != ')'
-
+          if char == ')'
+            in_brackets = false
+            chunks << str[chunk_start .. chi-1]
+            chunk_start = chi + 1
+          end
         else
-          if char =~ /^\s$/
+          if char == '('
+            in_brackets = true
+            chunk_start = chi + 1
+          elsif char =~ /^\s$/
             if chunk_start != chi
               chunks << str[chunk_start .. chi-1]
             end
@@ -24,7 +30,9 @@ module Gly
         end
       end
 
-      chunks << str[chunk_start .. -1]
+      if chunk_start < str.size
+        chunks << str[chunk_start .. -1]
+      end
 
       chunks
     end

data/lib/gly/string_helpers.rb~

@@ -24,9 +24,7 @@ module Gly
         end
       end
 
-      if chunk_start != chi
-        chunks << str[chunk_start .. chi-1]
-      end
+      chunks << str[chunk_start .. -1]
 
       chunks
     end

data/lib/gly/templates/lualatex_document.tex

@@ -0,0 +1,27 @@
+%% LuaLaTeX
+
+\documentclass[a4paper, 12pt]{article}
+\usepackage[latin]{babel}
+\usepackage[left=2cm, right=2cm, top=2cm, bottom=2cm]{geometry}
+
+\usepackage{fontspec}
+
+%% for gregorio
+\usepackage{luatextra}
+\usepackage{graphicx}
+\usepackage{gregoriotex}
+
+\title{%{title}}
+
+\begin{document}
+
+%{maketitle}
+
+%{body}
+
+%% tagline
+\vfill
+\begin{center}
+  \texttt{gly preview https://github.com/igneus/gly}
+\end{center}
+\end{document}

data/lib/gly/templates/lualatex_document.tex~

@@ -0,0 +1,27 @@
+% LuaLaTeX
+
+\documentclass[a4paper, 12pt]{article}
+\usepackage[latin]{babel}
+\usepackage[left=2cm, right=2cm, top=2cm, bottom=2cm]{geometry}
+
+\usepackage{fontspec}
+
+% for gregorio
+\usepackage{luatextra}
+\usepackage{graphicx}
+\usepackage{gregoriotex}
+
+\title{#{doc.header['title']}}
+
+\begin{document}
+
+%{maketitle}
+
+%{body}
+
+% tagline
+\vfill
+\begin{center}
+  \texttt{gly preview https://github.com/igneus/gly}
+\end{center}
+\end{document}

data/tests/string_helpers_test.rb

@@ -8,8 +8,9 @@ class StringHelpersTest < GlyTest
     ['simple_whitespace', 'aa aa', ['aa', 'aa']],
     ['leading_trailing_whitespace', ' a a  ', ['a', 'a']],
     ['bracketted', '(a)', ['a']],
+    ['empty', '()', ['']]
   ]
-  
+
   examples.each do |e|
     name, given, expected = e
     define_method "test_#{name}" do

data/tests/string_helpers_test.rb~

@@ -2,8 +2,18 @@ require_relative 'test_helper'
 
 class StringHelpersTest < GlyTest
   SH = Gly::StringHelpers
+
+  examples = [
+    ['single_chunk', 'a', ['a']],
+    ['simple_whitespace', 'aa aa', ['aa', 'aa']],
+    ['leading_trailing_whitespace', ' a a  ', ['a', 'a']],
+    ['bracketted', '(a)', ['a']],
+  ]
   
-  def test_simple_whitespace_split
-    assert_equal ['aa', 'aa'], SH.music_split('aa aa')
+  examples.each do |e|
+    name, given, expected = e
+    define_method "test_#{name}" do
+      assert_equal expected, SH.music_split(given)
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gly
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Jakub Pavlík
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-12-15 00:00:00.000000000 Z
+date: 2015-12-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -49,23 +49,26 @@ description: "# gly\n\nWriter-friendly Gregorian notation format compiling to ga
   or\n    lyrics alone is possible (useful for a composer)\n  * syllabified lyrics
   entered in a format inspired by LilyPond\n* music and lyrics can be interspersed
   as needed\n* no semicolons in the header\n* custom header fields supported (commented
-  out in the GABC output;\n  as gregorio crashes on headers it doesn't know)\n* several
-  scores per file (when compiled to gabc, each becomes\n  a separate file)\n* compile
-  pdf preview by a single command, without writing any (La)TeX\n\n## Examples\n\nTypical
-  GABC source of an antiphon looks like this:\n\n    name: Nativitas gloriosae;\n
-  \   office-part: laudes, 1. ant.;\n    occasion: In Nativitate B. Mariae Virginis;\n
-  \   book: Antiphonale Romanum 1912, pg. 704;\n    mode: 8;\n    initial-style: 1;\n
-  \   %%\n    \n    (c4) NA(g)TI(g)VI(g)TAS(gd) glo(f)ri(gh)ó(g)sae(g) * (,)\n    Vír(g)gi(g)nis(hi)
-  Ma(gh)rí(gf)ae,(f) (;)\n    ex(f) sé(g)mi(h)ne(h) A(hiwji)bra(hg)hae,(g) (;)\n    or(gh~)tae(g)
-  de(g) tri(g)bu(fe/fgf) Ju(d)da,(d) (;)\n    cla(df!gh)ra(g) ex(f) stir(hg~)pe(hi)
-  Da(h)vid.(g) (::)\n\nCorresponding GLY may look like this:\n\n    name: Nativitas
-  gloriosae\n    office-part: laudes, 1. ant.\n    occasion: In Nativitate B. Mariae
-  Virginis\n    book: Antiphonale Romanum 1912, pg. 704\n    mode: 8\n    initial-style:
-  1\n    \n    c4 g g g gd f gh g g ,\n    g g hi gh gf f ;\n    f g h h hiwji hg
-  g ;\n    gh~ g g g fe/fgf d d ;\n    df!gh g f hg~ hi h g ::\n    \n    NA -- TI
-  -- VI -- TAS glo -- ri -- ósae *\n    Vír -- gi -- nis Ma -- rí -- ae,\n    ex sé
-  -- mi -- ne A -- bra -- hae,\n    or -- tae de tri -- bu Ju -- da,\n    cla -- ra
-  ex stir -- pe Da -- vid.\n\nOr, with music and lyrics interlaced:\n\n    name: Nativitas
+  out in the GABC output,\n  as gregorio doesn't tolerate headers it doesn't know)\n*
+  several scores per file (when compiled to gabc, each becomes\n  a separate file)\n*
+  compile pdf preview by a single command, without writing any (La)TeX\n\n## Real
+  world examples\n\n* [Proper Divine Office chants of Bohemian Premonstratensian houses][opraem_boh]\n\n##
+  Basic examples\n\nTypical GABC source of an antiphon looks like this:\n\n    name:
+  Nativitas gloriosae;\n    office-part: laudes, 1. ant.;\n    occasion: In Nativitate
+  B. Mariae Virginis;\n    book: Antiphonale Romanum 1912, pg. 704;\n    mode: 8;\n
+  \   initial-style: 1;\n    %%\n    \n    (c4) NA(g)TI(g)VI(g)TAS(gd) glo(f)ri(gh)ó(g)sae(g)
+  * (,)\n    Vír(g)gi(g)nis(hi) Ma(gh)rí(gf)ae,(f) (;)\n    ex(f) sé(g)mi(h)ne(h)
+  A(hiwji)bra(hg)hae,(g) (;)\n    or(gh~)tae(g) de(g) tri(g)bu(fe/fgf) Ju(d)da,(d)
+  (;)\n    cla(df!gh)ra(g) ex(f) stir(hg~)pe(hi) Da(h)vid.(g) (::)\n\nCorresponding
+  GLY may look like this:\n\n    name: Nativitas gloriosae\n    office-part: laudes,
+  1. ant.\n    occasion: In Nativitate B. Mariae Virginis\n    book: Antiphonale Romanum
+  1912, pg. 704\n    mode: 8\n    initial-style: 1\n    \n    c4 g g g gd f gh g g
+  ,\n    g g hi gh gf f ;\n    f g h h hiwji hg g ;\n    gh~ g g g fe/fgf d d ;\n
+  \   df!gh g f hg~ hi h g ::\n    \n    NA -- TI -- VI -- TAS glo -- ri -- ósae *\n
+  \   Vír -- gi -- nis Ma -- rí -- ae,\n    ex sé -- mi -- ne A -- bra -- hae,\n    or
+  -- tae de tri -- bu Ju -- da,\n    cla -- ra ex stir -- pe Da -- vid.\n\nOr, with
+  music and lyrics interlaced\n(this arrangement may be handy for larger scores,\nlike
+  full-notated hymns, sequences or nocturnal responsories):\n\n    name: Nativitas
   gloriosae\n    office-part: laudes, 1. ant.\n    occasion: In Nativitate B. Mariae
   Virginis\n    book: Antiphonale Romanum 1912, pg. 704\n    mode: 8\n    initial-style:
   1\n    \n    c4 g g g gd f gh g g ,\n    NA -- TI -- VI -- TAS glo -- ri -- ósae
@@ -73,16 +76,70 @@ description: "# gly\n\nWriter-friendly Gregorian notation format compiling to ga
   g h h hiwji hg g ;\n    ex sé -- mi -- ne A -- bra -- hae,\n    \n    gh~ g g g
   fe/fgf d d ;\n    or -- tae de tri -- bu Ju -- da,\n    \n    df!gh g f hg~ hi h
   g ::\n    cla -- ra ex stir -- pe Da -- vid.\n\nOther arrangements are also possible.
-  Order of music and lyrics\nis actually ignored during processing.\n\n## Usage\n\nThis
-  gem provides executable `gly`. Run `gly help` for full list\nof subcommands. The
-  most important ones are:\n\n`gly gabc FILE1 ...`\n\nconverts given gly file(s) to
-  one or more gabc files (one per score,\ni.e. one gly may spawn a bunch of gabcs).\n\n`gly
+  Order of music and lyrics\nis actually ignored during processing.\n\n## Installation\n\nInstall
+  Ruby (some 2.x version) runtime. Then install as any ruby gem:\n\n`gem install gly`\n\n##
+  Usage\n\nThis gem provides executable `gly`. Run `gly help` for full list\nof subcommands.
+  The most important ones are:\n\n`gly gabc FILE1 ...`\n\nconverts given gly file(s)
+  to one or more gabc files (one per score,\ni.e. one gly may spawn a bunch of gabcs).\n\n`gly
   preview FILE1 ...`\n\nAttempts to create a pdf document with all scores contained
-  in each\ngly file. Expects gregorio and lualatex to be in PATH\nand gregoriotex
-  to be installed and accessible by lualatex.\n\n## Tools\n\n[Emacs mode with syntax
+  in each\ngly file. Expects `gregorio` and `lualatex` to be in PATH\nand `gregoriotex`
+  to be installed and accessible by `lualatex`.\n\n## Tools\n\n[Emacs mode with syntax
   highlighting for gly][elisp]\n\n![Editing gly in emacs](/doc/img/gly_emacs_scr.png)\n\n##
-  Run tests\n\nby executing `tests/run.rb`\n\n## License\n\nMIT\n\n[gregorio]: https://github.com/gregorio-project/gregorio\n[elisp]:
-  /tree/master/elisp\n"
+  Syntax reference\n\nGly syntax is line-based.\nThe interpreter reads the input line
+  by line,\nand depending on context it interprets each line as\ne.g. music, lyrics
+  or header field.\n\nThe syntax is quite permissive, not requiring a lot of delimiters\nor
+  hints for the parser concerning what each line means.\nMostly the parser guesses
+  the meaning correctly.\nWhere not, meaning of each line can be stated explicitly.\n\n###
+  1. Comments\n\nWhen a `%` sign is encountered, everything until the end of line\nis
+  considered a comment and not interpreted.\n(Comment syntax is the same as in gabc.)\n\nPlease
+  note, that when compiling to gabc, comments are dropped\nand don't appear in the
+  resulting gabc file.\n\n### 2. Whitespace\n\nEmpty lines are ignored.\n\n### 3.
+  Scores\n\nA new score begins at the beginning of a file or at a line containing\na
+  single keyword '\\score'.\n\nIt consists of\na header (optional, only permitted
+  at the beginning of a score)\nand music- and lyrics-lines.\nLines with music and
+  lyrics may appear in any order.\n\nScore ends with end of file or with explicit
+  beginning of a new score\nor another top-level element.\n\n#### 3.1 Score header\n\nScore
+  header consists of fields.\n\nEach header field is on it's own (one) line and consists
+  of\nidentifier, colon and value:\n\n`mode: 8`\n\nHeader field identifier may only
+  consist of alphanumeric characters,\nminus-sign and underscore. Value can contain
+  anything.\n\nScore header ends with first non-empty line identified by the parser\nas
+  music or lyrics.\n\nHeader field 'id' is special: if present, it is used as suffix\nof
+  the generated gabc file (instead of the default, which is\nnumeric position of the
+  score in the source document).\n\n#### 3.2 Lyrics\n\nSyntax of lyrics is inspired
+  by LilyPond.\nLyrics have to be manually syllabified. Default syllable delimiter\nis
+  double dash (minus) `--` with optional whitespace around.\n\n`cla -- ra ex stir
+  -- pe Da -- vid.`\n\nThe parser guesses meaning of the line by attempting to find\nsyllable
+  separator in it and by looking if it's alphanumeric\ncharacters contains something
+  that cannot be interpreted as music.\nIf any of these conditions is met, the line
+  is interpreted as lyrics.\n\nIf gly fails to guess your lyrics line correctly and
+  interprets\nit as music, place `\\lyrics` or short `\\l` at the beginning\nof the
+  unhappy line:\n\n`\\l a a a`\n\n#### 3.3 Music\n\nAny line appearing in a score
+  and not identified as header field\nor lyrics is music by default.\n\nMusic line
+  contains one or more music chunks separated by whitespace.\nFor music syntax see
+  [official gabc documentation][gabc] -\ngly doesn't change anything in this respect.\n\nMusic
+  chunks may be enclosed in parentheses as in gabc.\n(Of course you don't like the
+  parentheses and are happy that gly\nlet's you leave them out. But in some special
+  cases they come handy.)\n\n#### 3.4 Matching lyrics to music\n\nWhen processing
+  the gly source and producing gabc, music chunks\nare matched to lyric syllables.\n\nThere
+  are, however, a few special cases, to make it work conveniently:\n\nThese special
+  cases of music chunks don't get lyric syllable:\n\n* clef\n* music chunk containing
+  only a division - i.e. music chunk containing\n  one of `,` , `;` , `:` , `::` alone\n\nException
+  to this rule are 'nonlyrical lyrics chunks'.\nCurrently there is only one built-in
+  nonlyrical lyric chunk:\nasterisk `*`.\nNormally it is treated as any other syllable,\nbut
+  if it meets a division, it is set as it's lyrics, while\na normal syllable wouldn't
+  be.\n\nIf you need to set some other syllable under a division,\nmake it 'nonlyrical'
+  by placing\nan exclamation mark at it's beginning, e.g. `!<i>Ps.</i>`\n\nIn the
+  other direction it is sometimes necessary to set a syllable\nnot matching any music
+  at all. In such cases empty music chunk\n`()` is what you need.\n\n### 4. Document
+  header\n\nEach gly document may optinally contain a document header.\nIt may appear
+  anywhere in the document, but best practice is to place\nit at the very beginning.\n\nDocument
+  header starts with keyword `\\header` and ends\nat the end of file or at the beginning
+  of another top-level element.\nThe syntax of it's content is the same\nas for [Score
+  header][].\n\nField 'title' in the document header is, if present,\nused by `gly
+  preview` as title of the generated pdf.\n\n## Run tests\n\nby executing `tests/run.rb`\n\n##
+  License\n\nMIT\n\n[gregorio]: https://github.com/gregorio-project/gregorio\n[gabc]:
+  http://gregorio-project.github.io/gabc/index.html\n[elisp]: /tree/master/elisp\n\n[opraem_boh]:
+  https://gist.github.com/igneus/1aed0b36e9b23b51526d\n"
 email: jkb.pavlik@gmail.com
 executables:
 - gly
@@ -97,18 +154,26 @@ files:
 - lib/gly/cli.rb~
 - lib/gly/document.rb
 - lib/gly/document.rb~
+- lib/gly/document_gabc_convertor.rb
+- lib/gly/document_gabc_convertor.rb~
 - lib/gly/gabc_convertor.rb
 - lib/gly/gabc_convertor.rb~
 - lib/gly/headers.rb
 - lib/gly/headers.rb~
+- lib/gly/lister.rb
+- lib/gly/lister.rb~
 - lib/gly/lyrics.rb
 - lib/gly/lyrics.rb~
 - lib/gly/parsed_score.rb
 - lib/gly/parsed_score.rb~
 - lib/gly/parser.rb
 - lib/gly/parser.rb~
+- lib/gly/preview_generator.rb
+- lib/gly/preview_generator.rb~
 - lib/gly/string_helpers.rb
 - lib/gly/string_helpers.rb~
+- lib/gly/templates/lualatex_document.tex
+- lib/gly/templates/lualatex_document.tex~
 - tests/examples.rb
 - tests/examples.rb~
 - tests/examples/gly/expected/block_lyrics.gabc