summaryrefslogtreecommitdiff
path: root/Build/source/utils/songs/songs-2.17/README
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/utils/songs/songs-2.17/README')
-rw-r--r--Build/source/utils/songs/songs-2.17/README200
1 files changed, 200 insertions, 0 deletions
diff --git a/Build/source/utils/songs/songs-2.17/README b/Build/source/utils/songs/songs-2.17/README
new file mode 100644
index 00000000000..049e7d0d591
--- /dev/null
+++ b/Build/source/utils/songs/songs-2.17/README
@@ -0,0 +1,200 @@
+------------------------------------------------------------------------------
+ Songs LaTeX Package Documentation
+------------------------------------------------------------------------------
+
+Table Of Contents:
+ I. Overview
+ II. Copyright Notice
+ III. System Requirements
+ IV. Installation Instructions
+ V. Usage
+ A. LaTeX Package Style File and Documentation
+ B. Sample Song Books
+ C. Creating a New Song Book
+ D. Support Utilities (songidx and sbdchk)
+ VI. Removal / Reinstallation
+ VII. Help and 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) 2013 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. System Requirements
+
+In order to install and run this software, you will need:
+
+1. a C compiler (included on all Unix systems),
+2. a LaTeX2e installation (by default, the installation tries "pdflatex"),
+3. tar and gzip programs (to unpack the songs-x.xx.tar.gz file), and
+4. an installation of GNU Make (to run the Makefile).
+
+
+IV. Installation Instructions
+
+1. Unpack the songs-x.xx.tar.gz file (where x.xx is the version number).
+
+ tar -xzf songs-x.xx.tar.gz
+
+2. Change directory to the songs directory and run the configure script.
+
+ cd songs-x.xx
+ ./configure
+
+3. Run GNU Make (other versions of Make are not supported). To be sure that
+you are using GNU Make and not some other version of Make, use the "gmake"
+command:
+
+ gmake
+
+4. If you only intend to use the software by editing files within the
+songs-x.xx directory tree (i.e., a single-user installation), then you don't
+need to perform the following final step. However, to allow other users to
+access the software or to build song books yourself in other directories, you
+must next install the binary programs, LaTeX style files, index data files,
+and Vim support scripts in appropriate places on your system. To do so, make
+the "install" target and specify a directory prefix equal to a fresh sub-
+directory in your home directory:
+
+ gmake install prefix=~/mysongs
+
+This will create a ~/mysongs directory tree containing the files that need to
+be installed. Here is a summary of what it contains:
+
+ bin: Contains executable programs.
+ share/doc: Contains package documentation.
+ share/texmf: Contains the main LaTeX style file.
+ share/songs: Contains the *.can data files used by songidx when
+ generating scripture indexes.
+ share/vimfiles: Contains support scripts for Vim (optional).
+
+Each of these must be copied to an appropriate place on your system. For
+example, the following commands copy the files to appropriate places in a
+typical /usr/local tree:
+
+ cp ~/mysongs/bin/* /usr/local/bin
+ cp -r ~/mysongs/share/doc/songs /usr/local/share/doc
+ cp -r ~/mysongs/share/songs /usr/local/share
+ cp -r ~/mysongs/share/texmf/tex /usr/local/texmf
+ cp -r ~/mysongs/share/vimfiles/* /usr/local/share/vim/vimfiles
+
+Alternatively, the following copies them to appropriate places in a typical
+single-user home directory structure:
+
+ cp ~/mysongs/bin/* ~/bin
+ cp -r ~/mysongs/share/doc/songs ~/doc
+ cp -r ~/mysongs/share/songs ~/data
+ cp -r ~/mysongs/share/texmf/tex ~/localtexmf
+ cp -r ~/mysongs/share/vimfiles/* ~/.vim
+
+Note: After copying new files into the texmf tree, many LaTeX distributions
+require you to execute the texhash command to update LaTeX's file name
+database. Be sure to do so if your version of LaTeX requires it:
+
+ texhash
+
+
+V. Usage
+
+After running "gmake" from the songs-x.xx directory (step 3 above) you should
+find the following file clusters:
+
+A. LaTeX Package Style File and Documentation
+
+In songs/src/songs you will find:
+* src/songs/songs.sty: If you don't use "gmake install" to install this LaTeX
+ style file in the system's TeX repository tree, then songs.sty must be copied
+ into each directory that has a .tex file that uses the songs package. (This
+ is done automatically by the makefile that generates the sample book, so if
+ you reuse that makefile as recommended in part C below, you don't need to
+ copy it manually.)
+* src/songs/songs.pdf: Comprehensive documentation of the songs package.
+
+B. Sample Song Books
+
+The GNUmakefile in songs/sample generates the sample song books. There are
+four books in total:
+
+* sample/chordbook.pdf: a chord book for musicians,
+* sample/lyricbook.pdf: a lyric book for singers,
+* sample/slidebook.pdf: a book of slides for use with a digital projector, and
+* sample/transparencies.pdf: book of transparencies for an overhead projector
+
+All four books draw upon the song data contained in the file songs.sbd. By
+modifying that file, you can change the content of all four books. To change
+the formatting style of any particular book, change the corresponding
+sample/*.tex file.
+
+C. Creating a New Song Book
+
+You can create a new song book directory by copying the sample directory and
+its contents to a new subdirectory:
+
+ cp -r sample mybook
+ cd mybook
+ gmake clean
+ gmake
+
+If you have used "gmake install" to install the software (see Section III.4)
+then your new "mybook" directory can be located anywhere; otherwise it must be
+in the songs-x.xx directory.
+
+D. Support Utilities (songidx and sbdchk)
+
+* songs/src/songidx/songidx: This program is required for auto-generating song
+ book indexes. The GNUmakefile in songs/sample invokes it automatically as
+ necessary.
+* songs/src/sbdchk/sbdchk: The sbdchk program is a utility that proofs .sbd
+ files for chord placement errors. Chords are misplaced if they fall at an
+ invalid hyphenation point or they break a ligature. To use sbdchk with the
+ sample song books, change to the songs/sample directory and type
+
+ gmake sbdcheck
+
+ This will generate a report file named songs.hyp in the current directory.
+
+
+VI. Removal / Reinstallation
+
+To reverse the behavior of "make install", type:
+
+ gmake uninstall
+
+To merely delete all generated files within the songs directory (without
+deleting the non-generated files), type:
+
+ gmake clean
+
+
+VII. Support and Bug Reporting
+
+For the most current version of this software as well as author contact
+information, see the songs project homepage at:
+
+ http://songs.sourceforge.net
+