Songs LaTeX Package Revision History:

Version 3.0 [2017/06/05]: Fifth CTAN Release

  * Transitioned the songidx program to LuaTeX, eliminating the need for C-compiled programs.  This significant change to the install process warrants the transition to a new major version number.

  * The sbdchk program is being retired, since I don't think anyone is using it and it relies on LaTeX hyphenation algorithms that aren't well suited to the task of chord placement.  If anyone wants it back, let me know and I'll consider porting it to Lua.

  * Corrected a longstanding, elusive bug in the page-builder that occasionally inserted unwanted vertical space between songs.

  * Corrected a bug in the indexer that sometimes incorrectly sorted entries that are strict prefixes of other entries (e.g., entry "Smith" now always precedes entry "Smith, John").

  * Fixed a bug in the chord replaying logic that failed to apply transposition and note renaming to replayed chords within chord-over-ligature macros.

  * Added support for lyric fonts with no hyphen character (usually for non-hyphenated languages).

Version 2.18 [2015/08/18]:

  * Added \echofont for customizing the font of echo parts.

  * Added \meterfont for customizing the font of meter numbers, and fixed a bug that italicized meter numbers within italicized lyric sections. Also added a tiny vertical space between meter numbers and meter bars for improved readability.

  * Bug fix: Customizing \versefont and \chorusfont no longer nullifies custom line spacing via \baselineadj.

  * \includeonlysongs may now specify repeated songs without throwing errors. (Note that this can result in duplicate index entries, however.)

  * Fixed a bug in songidx that caused an infinite loop when the system's locale (conflictingly) classifies certain characters as "digits", but doesn't recognize those same characters as constituting numbers.

  * Documentation improvements (color, reorganization, and clarifications)

  * Experimental: Index sorting now optionally uses ICU collation instead of locale to sort international texts, affording users many new sorting options.  (Separate installation of the ICU library is required.)  Note: ICU support does not yet include ICU-based "bucketing" (grouping of index entries into alphabetic subsections, as in title indexes).  Such support is expected to appear in a future release.

  * Better support for small LaTeX environments with missing packages

  * Compliance with new 2015/01/01 LaTeX release (e-TeX extended registers available by default on newer installations without explicit loading of e-TeX style package).

  * Windows installer now installs native 64-bit songidx and sbdchk programs on 64-bit systems.

Version 2.17 [2013/07/10]:

  * Fixed a major error in the page-builder (introduced in v2.16 by the fix to \sclearpage) which caused the last page of many songs environments to be dropped.  The fix required a significant overhaul of the page-building algorithm, so is given its own release.

  * Fixed a returning bug that caused the first lines of numbered, centered verses to be slightly off-center.

Version 2.16 [2013/07/02]:

  * \pagepreludes now sets \songpos to 0, since otherwise songs could become separated from their preludes.

  * Fixed a bug introduced in v2.15 that caused errors when a song title began with a multinational character encoded by the inputenc package.

  * Fixed a bug introduced in v2.14 that broke the \authsepword, \authbyword, and \authignoreword macros (again).

  * Fixed a bug that caused \sclearpage (and macros that call it) to sometimes output a blank page.  The same bug also caused the \songpos algorithm to occasionally miss the best song placement.

  * Added extra error-checking for macro name-clashes with other packages.

Version 2.15 [2013/02/02]:

  * New page format: In non-slides mode, activating \pagepreludes typesets each song on a fresh page with title spanning the entire page width, but with the rest of the song typeset in multiple columns below the title.

  * New \songtarget and \songlink macros elaborate the nopdfindex option with finer control over PDF bookmark indexes and hyperlinks.  The \ifpdfindex conditional has been retired.

  * Some index-sorting problems related to the inputenc package have been resolved.  (For even better sorting of international alphabets, use a LaTeX version with native Unicode support, such as XeTeX, instead of inputenc.)
 
  * The author indexer now treats everything except spaces, commas, and semicolons not enclosed in braces as parts of words.  This helps to support unusual band names that contain punctuation or numbers.

  * Setting \idxheadwidth to 0pt now suppresses the letter divisions in large indexes entirely.

  * Fixed a bug that caused the author indexer to recognize only the last \authignoreword.

  * Fixed a bug in the title indexer that incorrectly indexed titles beginning with numbers.

  * Updated the Unix installer to bring it into compliance with Gnu autoconf 2.69 standards.  See the README file for new (easier) install instructions.

Version 2.14 [2012/03/17]: Fourth CTAN Release

  * Corrected a bug introduced in version 2.13 that broke \titleprefixword, \authsepword, \authbyword, and \authignoreword.  (Turns out this fix contained another bug that left the last three of these macros unfixed until v2.16.  See v2.16 notes above.)

  * Corrected a bug that caused misformatted multiline index entries in single-column indexes.

Version 2.13 [2011/08/08]:

  * New \clineparams macro allows better customization of the vertical space between chords and lyrics.

  * New \afterpreludeskip and \beforepostludeskip skip registers allow customization of the vertical space above and below song bodies.

  * New \gtabtrans macro allows the user to customize what happens when a \gtab macro is supposed to be auto-transposed.  (By default, the chord name is transposed and the tablature diagram is omitted.)

  * Note name conversion is now applied by default to chord names in \gtab macros (even when there is no auto-transposition).

  * New \notrans macro allows transposition to be suppressed within a chord name without suppressing note name conversion (via \notenamesin and \notenamesout).

  * New \sepindexesfalse macro disables automatic page breaks at the end of indexes, and makes every index n-column (where n is specified in the optional argument to \showindex) instead of converting short indexes to centered, single-columns.  This allows the user to put many small indexes on a single page if desired.

  * Declaring a large number of song indexes no longer causes TeX to exceed the write-register limit.

  * Fixed a bug that caused errors when certain fragile macros appeared in \songmark, \versemark, or \chorusmark definitions.

  * Fixed a bug that erased numerators from meter bars that began the first lines of numbered verses.

  * Fixed a bug that inadvertently swapped the meanings of \begin{verse} and \begin{verse*}.

  * Windows installer now supports 64-bit MiKTeX installations.

Version 2.12 [2011/01/09]:

  * The argument to \beginscripture and the sr={} key of \beginsong now support multi-byte unicode input characters.  Surrounding any text in these arguments with braces suppresses any reformatting that would otherwise be applied to that text.

  * All macro pairs of the form \beginX...\endX now have an equivalent environment definition of the form \begin{X}...\end{X}.  This fixes some compatibility problems with other packages.

  * Fixed a bug that caused one-word author names to be preceded by a comma in the author index.

Version 2.11 [2010/06/09]:

  * New intersong environment typesets column-width or page-width displays between songs in a songs environment.

  * New songgroup environment allows scripture quotations or other intersong displays to be included with a nearby song when using \includeonlysongs to generate a partial book.

  * Tablature diagrams can now have any number of strings and from 1 to 9 rows of frets.

  * Colors of textual notes, song number boxes, and index section boxes are now independently configurable by redefining \notebgcolor, \snumbgcolor, and \idxbgcolor.

  * New \sclearpage and \scleardpage macros shift to the next blank page or the next even-numbered blank page, respectively.

  * Songs environments and indexes are no longer followed by a forced \cleardoublepage.  Documents can use \cleardoublepage explicitly if this behavior is desired.

  * \includeonlysongs now works even when the page-builder is disabled.

  * New "--locale" option for songidx and sbdchk overrides the environment default locale setting.

  * Added extra grouping levels for verses, choruses, textual notes, and most other constructs to help users avoid color "bleeding" errors when using the color package.

Version 2.10 [2010/01/01]:

  * The size of accidentals (sharps and flats) is now relative to the current font size instead of being relative to the document default font size.

  * New \sharpsymbol and \flatsymbol macros can be redefined to change the font symbols used for accidentals.

  * Fixed a bug that forced single column mode whenever \songcols was used within a songs environment.

  * Fixed a bug in which \songpos{1} caused empty pages to be inserted between some songs when used in one-sided documents.

  * Fixed a bug that caused lines in numbered verses to be slightly off-center in slides mode.

  * The current system locale setting is now consulted when alphabetizing song titles that contain non-English letters.  Change the system locale before running songidx to alphabetize according to the conventions of another language.

  * Some missing Vim icon files were re-included into the Unix distribution.

Version 2.9 [2009/08/02]:

  * Song numbering can now be disabled with \nosongnumbers.

  * New \nolyrics macro puts chords on the baseline instead of raised, to better typeset instrumental solos and intros.

  * \brk can be used between songs to force column breaks without introducing the extra vertical space that \nextcol puts at the bottom of the column.

  * \begin...only and \begin...never family of macros have been made obsolete.  Eliminate them from existing documents by replacing \beginXonly with \ifX, replace \beginXnever with \ifX\else, and replace both \endXonly and \endXnever with \fi.

  * \colminheight (which could not be perfectly supported by LaTeX's page-breaking algorithm) has been eliminated in favor of \colbotglue and \lastcolglue.

  * An external page-making package (e.g., multicol) can now be used in place of the songs-provided one by setting the number of columns to zero (with \songcolumns{0}).

  * The song-positioning algorithm, which moves songs to fresh columns or pages to avoid column-breaks, page-breaks, and page-turns within songs, can now be tuned or disabled with \songpos.

  * \interlinepenalty now controls the penalties inserted between consecutive lines of each verse and chorus.

  * The rest of the penalty system has been recalibrated in accordance with the above changes.  The \interlinepenalty now defaults to 1000 and \vvpenalty and friends now default to 200.  \spenalty defaults to 100.

  * Fixed a compatibility issue with Babel that caused \gtab to malfunction when French was the active language

  * Fixed a bug that caused overthick division bars between songs when \sbarheight was set larger than 1pt

  * Fixed a bug that caused the song-positioning algorithm to underestimate the size of songs containing auto-repeated choruses.

  * Re-fixed a returning bug that caused spurious hyphenation when an \echo part ended with a chord longer than its lyric.

Version 2.8 [2009/03/14]:

  * \songnumstyle and \versenumstyle replaced with \thesongnum and \theversenum macros (for compatibility with standard LaTeX counters)

  * \label's within a song or numbered verse can now be used to create automatic references to the song's or the verse's number.

  * Using \showindex with \includeonlysongs now yields a partial index instead of a full index.

  * New \indexsongsas macro can customize indexes to print page numbers instead of song numbers.

  * Index fonts now customizable with \idxheadfont, \idxtitlefont, \idxlyricfont, \idxscripfont, \idxauthfont, and \idxrefsfont.

  * Formatting of scripture index book names is now customizable with \idxbook.

  * \showindex now takes an optional argument to specify the number of columns.

  * Index typesetting logic improved to handle index entries whose left-hand-sides exceed the width of the column

Version 2.7 [2009/01/08]: Third CTAN release

  * Constructions like "\[A]\[B]\[C]lyric" now typeset the same as "\[A B C]lyric", but the chords in the sequence can be replayed separately (e.g., with "^^^lyric").

  * Added support for begin- and end-repeat signs (\lrep and \rrep).

  * Column and page breaks can now be inserted into partial song lists created with \includeonlysongs.

  * Fixed a bug that caused sharp symbols to be doubled within echo parts on eTeX.

Version 2.6 [2008/04/02]:

  * \newchords and \replay macros added, optional argument added to \memorize

  * new "Quick Chords" mode for Vim users to make chord-entry a snap

  * Windows uninstaller reworked to avoid deleting files modified since installation

  * Last pages of multicolumn indexes are now vertically balanced.

  * Fixed a bug that occasionally produced empty pages when \topskip was non-zero

  * Fixed a bug that produced duplicate verse numbers when the first line of a verse was contained in a group

  * \echo macro no longer introduces a spurious line-break on eTeX.

  * \DeclareLyricChar and friends now perform macro-tests based on macro name rather than macro definition.

  * Extended mark register classes are now allocated safely so as to cooperate with other eTeX-aware packages.

Version 2.5 [2008/02/08]:

  * Unix version now uses the GNU automake system to configure and build itself

  * Support for more than two columns added (use \songcolumns to set the number of columns).

  * Chord replaying system now works properly in choruses.

  * Added \stitlefont to allow users to customize the song title font without having to redefine \makeprelude.

  * Added \baselineadj to allow users to customize the \baselineskip without having to redefine \everychorus and \everyverse.

  * Superscript ("^") now works again in math mode even when chord replaying system is active. (It can therefore be used to typeset chord names if desired.)

  * hyphchk utility renamed to sbdchk

  * sbdchk utility updated to report column numbers in reports and error messages

  * sbdchk and songidx sources updated to better adhere to GNU coding standards

Version 2.4 [2007/10/09]:  Second CTAN release

  * Added \titleprefixword, \authsepword, \authbyword, \authignoreword, and \idxcont to support automatic index-generation for non-English languages.

  * songidx program now supports piping to/from stdin/stdout (specify a filename of "-" to use this feature) and will infer an output filename when none is specified on the command line.

  * Unix makefiles and Windows batch files for the sample books have been updated to allow users to add new indexes without changing any of the make/batch files.

Version 2.3 [2007/09/23]:

  * \indexentry and \indextitleentry now accept an optional argument specifying which indexes to add the new entry to (overriding the defaults for the current songs environment)

  * \ch and \mch macros can now replay chords by using "^" as the chord name

  * Renamed the .dat and .tex intermediate files produced during index generation to .sxd (Song indeX Data) and .sbx (Song Book indeX), respectively, to avoid conflicts with other software. Unix users can now write Makefiles that recognize these unique file extensions.

Version 2.2 [2007/08/09]:

  * The page-layout algorithm now honors \maxdepth, fixing a bug that occasionally produced overfilled vbox warnings during output.

  * Fixed compiler warnings for systems that won't implicitly cast between integer and wide-characters.

Version 2.1 [2007/08/02]:

  * "Overheads" mode renamed to "slides" to reflect some substantial changes to that mode (see below).

  * \sepverses can now be used in slides mode to put each verse and chorus on a separate slide. This seems to be the norm in churches that use a digital projector, since it allows worship leaders to repeat previous verses or choruses without having extraneous lyrics up on the screen.

  * Choruses in slides mode are no longer surrounded by vertical rules, but are instead italicized by default. The rules looked nice, but they made it impossible to correctly break large choruses that couldn't fit on a single slide.

  * To make echo parts stand out in italicized choruses, \echo now toggles between oblique and upright shapes (like \emph) instead of forcing the former.

  * \repchoruses can now be used to repeat choruses automatically in songs that span more than one slide. This is very useful when creating foils for an overhead projector.

  * \versemark and \chorusmark added to allow page headers that match the current verse or chorus rather than just the current song.

  * \everyverse and \everychorus added so that users can make choruses begin with "Chorus:" and the like if they wish. (Personally I think that wastes too much space, but it's a common style.)

  * \ifvnumbered conditional added to allow code that checks to see if the current verse is numbered or not.

  * New \begin...only and \begin...never conditionals introduced that are just like \if... and \if...\else except that they avoid certain "runaway argument" errors raised by the latter.

  * Added \versefont, \chorusfont, \versejustify, and \chorusjustify to allow users to customize font and/or justification of verses and choruses all independently. This reduces slides mode to a set of customizations that can all be manually duplicated (or undone) by the user.

  * \baselineskip logic improved to better handle large fonts.

  * Indexes now work properly when using \includeonlysongs to generate a partial list.

  * \brk can now be used in vertical mode to suggest column- and page-breaks in verses and choruses that are too long to fit on a single slide.

  * Added \DeclareNonLyric and \DeclareNoHyphen for better support of \inputenc.

  * \tablature macro shortened to \gtab and with only two mandatory arguments instead of four.

  * Automatic transposition now recognizes alternate note names, such as solfedge note names.

Version 2.0 [2007/06/20]:

  * Introduced keyval syntax for \beginsong.

  * Added chord-replaying system (^, \memorize, \[^...]).

  * Removed in-package code that loads hyperref. Users must now load hyperref manually.

  * \songsection and \songchapter now support optional arguments like \section and \chapter do.

  * Non-output-producing tokens (like \relax) can now appear between the last \Acolon or \Bcolon line and the \endscripture line without messing up the scripture citation that gets appended to the last line.

  * Fewer macros are declared \outer, allowing authors to embed them within their own macro definitions.

  * Lyric-scanner code is now faster.

  * songidx was not recognizing apostrophes as intra-word characters.

  * When a guitar tablature diagram with a fret number appeared above a lyric, subsequent chords that did not include tablature diagrams were being spaced incorrectly (as if they had invisible fret numbers).

  * Fixed a bug that caused songs environments to occasionally generate pages slightly larger than \textheight.

Version 1.22 [2007/05/15]:  First CTAN release

  * \chordson and \chordsoff modified to update interline spacing, so that they can now be used within a song.

  * \MultiwordChords added to allow spaces to be included under chords.

  * \DeclareLyricChar added to allow user-specified macros to be treated as lyric characters.

  * Added support for UTF-8 encoded source files.

Version 1.21 [2006/09/17]:

  * Changed \rep so that it does not enter math mode when making the "times" symbol. (This helps quell missing font size warnings.)

  * \echo now preserves existing font selection and merely italicizes it.

Version 1.20 [2006/03/12]:

  * Added \noversenumbers to turn off automatic verse numbering

Version 1.19 [2005/10/24]:

  * Added book sectioning commands (\songchapter and \songsection).

  * Fixed song numbering so that it now starts at 1 by default in each song section.

Version 1.18 [2005/09/29]:

  * Automatic verse numbering added.

Version 1.17 [2005/09/24]:  First release as a style package instead of a class

  * Code massively reorganized to function as a .sty package instead of a .cls class.

  * Added \songmark so that users can add marks to affect page headers/footers

Version 1.16 [2005/07/23]:

  * First rollout of the new \[] syntax for producing chords. Lyrics are parsed as an implicit second argument.

Version 1.15 [2005/05/26]:

  * Added song title iterators: \songtitle, \songtitletoks, \nexttitle, \foreachtitle, \resettitles

  * Added \makeprelude and \makepostlude to allow users to customize song headers/footers

Version 1.14 [2005/05/15]:

  * Introduced the scripture reference parser, to prevent odd linebreaks in scripture references.

  * Choruses now stretch and shrink like verses do.

Version 1.13 [2005/05/12]:

  * Added kerning correction for double-quote ligatures in the Zaph Chancery font.

  * Added \Acolon, \Bcolon, and \strophe for typesetting biblical poetry.

  * Chords now preserve the \spacefactor so that subsequent text is spaced appropriately.

Version 1.12 [2005/05/10]:

  * Redid intra-song spacing and penalties to eliminate superfluous vbox items. Improved performance.

  * Improved inter-song penalties for better page- and column-breaking.

  * \parindent now controls the amount of indentation for wrapped lines within a song or scripture.

  * Multiline textnotes now work right.

  * Fixed chord macros to avoid introducing hyphenation when lyric ends in punctuation.

Version 1.11 [2005/04/21]: Begin tracking revision history

  * Renamed various macros to avoid naming clashes with other packages.

  * Adjusted the \\ index-separator macro so that its scope is now limited to the indexes.

Version 1.1 [2005/04/03]: First release as a .cls documentclass

  * First release as a self-documenting .dtx file

Version 1.0 [2001/12/01]: Initial release