diff options
Diffstat (limited to 'Build/source/utils/songs/songs-2.17/README')
-rw-r--r-- | Build/source/utils/songs/songs-2.17/README | 200 |
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 + |