Directory macros/latex/contrib/songs

------------------------------------------------------------------------------
                       Songs LaTeX Package Documentation
------------------------------------------------------------------------------

Table Of Contents:
   I. Overview
   II. Copyright Notice
   III. Manifest
   IV. Installation Instructions
   V. Help & Support


I. Overview

The Songs package is for producing songbooks containing lyrics and chords
(but not sheet music).  Each songs document can produce a lyric-only songbook
for singers, a chorded songbook for musicians, a set of overhead
transparencies, or a set of digital projector slides, all from a single master
document.  It can also automatically generate partial songbooks consisting of
only some songs from the master document in a specified order.  Facilities for
automatic transposition and creation of guitar tablature diagrams are also
included.


II. Copyright Notice

The Songs LaTeX Package is copyright (C) 2018 Kevin W. Hamlen.

It is free software; you can redistribute it and/or modify it under the terms
of the GNU General Public License as published by the Free Software Foundation;
either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
Street, Fifth Floor, Boston, MA  02110-1301, USA.


III. Manifest

This software consists of three main components:

1. The LaTeX2e "Songs" style package for creating songbooks, with source
consisting of:
     songs.dtx  (self-documenting source code)
     songs.ins  (installer script for docstrip)
     Makefile   (makefile for generating songs.sty and songs.pdf)

2. The songidx index-generation script:
     songidx/songidx.lua  (Lua source file)
     songidx/*.can        (text data files used by songidx at runtime)

(Please note that the "makeindex" program that comes standard with LaTeX
is NOT a suitable replacement for songidx.)

3. A sample chord book, lyric book, slide book, and transparency book:
     sample/songs.sbd           (song data for all four books)
     sample/chordbook.tex       (chord book LaTeX source)
     sample/lyricbook.tex       (lyric book LaTeX source)
     sample/slidebook.tex       (slide book LaTeX source)
     sample/transparencies.tex  (transparencies LaTeX source)
     sample/Makefile            (GNU makefile for generating all four books)


IV. Installation Instructions

1. The songs/Makefile file generates the songs package (songs.sty) and its
documentation (songs.pdf). If pdflatex and makeindex are both in your path,
you should be able to invoke Make to generate both:

     cd songs
     gmake

Otherwise you will need to first edit the top three lines of the Makefile
to indicate where pdflatex and makeindex are located on your system. If you
wish to use latex instead of pdflatex you must also change the "TEXOUT"
line to "TEXOUT = dvi".

If desired, copy the resulting songs.sty file to the appropriate place in
your LaTeX tree (usually /usr/local/share/texmf/tex/latex/songs).

     mkdir /usr/local/share/texmf/tex/latex/songs
     cp songs.sty /usr/local/share/texmf/tex/latex/songs

2. The sample books can be compiled using the files in songs/sample.  If
pdflatex is in your path, you should be able to invoke GNU Make to generate
all of them (note that GNU-compatible version of Make is REQUIRED):

     cd ../sample
     gmake

Otherwise you will need to first edit the top line of the Makefile to
indicate where pdflatex is located on your system. If you wish to use
latex instead of pdflatex you must also change the "TEXOUT" line to
"TEXOUT = dvi".


V. Help & Support

The songs.pdf file contains documentation precompiled from the songs.dtx
source code. For more support, including example songbooks, songbook
editing tools, and self-installing executables for Windows, please refer
to the Songs package homepage at:

     http://songs.sourceforge.net