doc 4

git-svn-id: svn://tug.org/texlive/trunk@80 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 296 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/guitar/guitar.txt b/Master/texmf-dist/doc/latex/guitar/guitar.txt
new file mode 100644
index 00000000000..25c0fecd1b9
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/guitar/guitar.txt
@@ -0,0 +1,296 @@
+
+%%#
+%%# Author:
+%%#
+%%# M. V\"ath      vaeth@mathematik.uni-wuerzburg.de
+%%#
+%%# The author thanks
+%%#     Donald Arseneau <asnd@triumf.ca>
+%%#     Dan Luecking    <luecking@uark.edu>
+%%# and a colleague who does not want to be named here.
+
+%%#############################################################################
+%%#
+%%#  guitar.sty - typesetting guitar chords over song texts.
+%%#
+%%#############################################################################
+
+%%#
+%%# This package should run with plain TeX, LaTeX 2.09, and LaTeX 2e.
+%%# Actually, it should actually run with all TeX formats.
+%%#
+
+%%# This is not the only package available for typesetting guitar songs.
+%%# The following packages are also available (and possibly also others:
+%%# I do not claim that this list is complete).
+%%#
+%%# 1. gchords.sty   http://www.damtp.cam.ac.uk/user/kp229/gchords/
+%%# 2. songbook.sty  http://www.rath.ca/Misc/Songbook/
+%%#    or on CTAN:   macros/latex/contrib/supported/songbook/
+%%# 3. guitarTeX (which is not a `pure' (La)TeX solution):
+%%#                  http://rz-home.de/~jmiltz/guitartex/
+%%#
+%%# The packages 1. and 2. have somewhat different intentions.
+%%# It should be possible to combine them with the current package
+%%# without any severe problems.
+
+
+%%# To use guitar, you have to put `guitar.sty' in a path where TeX looks
+%%# for its input files. The TeX documents using guitar need the
+%%# following modifications in their header:
+%%#
+%%# a) If you use LaTeX2.09, use guitar as a style option, e.g.
+%%#      \documentstyle[guitar]{article}
+%%#    or
+%%#      \documentstyle[guitar,12pt]{article}
+%%# b) If you use LaTeX2e, put in the preamble the command
+%%#      \usepackage{guitar}
+%%# c) If you use some other (non-LaTeX) format, you will probably have to
+%%#    insert a line like
+%%#          \catcode`\@=11\input guitar.sty\catcode`\@=12\relax
+%%#
+%%# For TeX-insiders:
+%%# The only LaTeX-specific commands used in `guitar.sty' are:
+%%#
+%%#   \newenvironment
+%%#   \newcommand (only in the form \newcommand{\command}{} to ensure that
+%%#                 \command was not defined before)
+%%#   \newsavebox
+%%#   \newlength
+%%#   \RequirePackage
+%%#   \ProvidesPackage
+%%#   \typeout
+%%#
+%%#   The above commands are used only if they are defined
+%%#   (otherwise, the plainTeX are used).
+%%#
+
+%%#
+%%# Usage:
+%%#
+
+%%# The general usage is very simple:
+%%#
+%%# \guitarChord{Bb}Really. \guitarChord{G#}Oh yes.
+%%#
+%%# This puts the chord "B flat" and "G sharp" over the "R" resp. "O".
+%%# (in the chord, "b" and "#" always translate into "flat" resp. "sharp").
+%%# When you switch into "magic" mode, you can even use [...] instead of
+%%# \guitarChord{...}.
+%%# E.g., in LaTeX, you can just write
+%%#
+%%# \begin{guitar}
+%%# [Cm]This [Bb]is a [G#]very [Gm]simple song.
+%%# You can still use any [\TeX]macros in the chord text.
+%%# Actually, each accord reads a second argument over
+%%# which it is [A]{centered}.
+%%# By default, the linefeeds in the source lead to linebreaks %
+%%# in the output, unless you put a percentage sign at the end of the line. %
+%%# If a single line gets too long, the wrapped lines are right-aligned.
+%%# To force the wrapping use \verb|\newline|\newline like here.
+%%# To stretch the first line, use \verb|\linebreak|\linebreak like here.
+%%#
+%%# Two subsequent linefeeds in the source start a new verse.
+%%#
+%%#
+%%# Three or more subsequent linefeeds in the source start a new verse with a %
+%%# slightly larger space.
+%%#
+%%# Unfortunately, if the chords get too long, they may [Ebm+7]o[G#]verlap.
+%%# To avoid this, the following solutions are supported:
+%%#
+%%# 1. If the token after your chord is a space, like in "[Ebm+7] space",
+%%#    this space is stretched.
+%%#    Note that this is different from the notation "[Ebm+7]{ }space".
+%%# 2. Inside words, put a _ at the end like for [Ebm+7_]O[G#]K.
+%%# 3. Outside words, put a | at the end like for [Ebm+7|]{OK}[G#|].
+%%# If the chord is short enough (compared to its argument) then the symbols
+%%# | and _ do not harm like in [E|]{long} or [E_]{long}er.
+%%#
+%%# You may (and in plainTeX you must) replace "\begin{guitar}" and
+%%# "\end{guitar}" by "\guitarOn" and "\guitarOff", respectively.
+%%#
+%%# If you only want to put the guitar chords as above but do not like the
+%%# feature concerning the linefeeds, you can use the environment
+%%# \begin{guitarMagic}
+%%# \end{guitarMagic}
+%%# or the respective commands \guitarMagicOn and \guitarMagicOff.
+%%# Similarly, you can also use only the linefeed feature by the environment
+%%# \begin{guitarCr}
+%%# \end{guitarCr}
+%%# or the respective commands \guitarCrOn and \guitarCrOff.
+%%#
+%%# As a matter of fact, you can also e.g. use \guitarCrOff *within* a
+%%# {guitar} environment, but then you have to use \guitarCrOn before you
+%%# end the environment to have a proper nesting of modes.
+%%#
+
+%%#
+%%# Customization
+%%#
+
+%%# The output of the "#" and "b" tokens in the chords is generated by the two
+%%# commands
+%%#
+%%#       \guitarSharp
+%%#       \guitarFlat
+%%#
+%%# Thus, for, example the customization
+%%#
+%%#       \def\guitarSharp{$^{\sharp}$}
+%%#
+%%# will make the sharp symbol be written as an upper index.
+
+%%# In a similar way, the macros
+%%#
+%%#       \guitarEndLine
+%%#       \guitarEndPar
+%%#       \guitarEndDoublePar
+%%#
+%%# are expanded when the song text contains one, two, or three (or more)
+%%# linefeeds.\par
+
+%%# After the macro
+%%#
+%%#       \guitarNoChord
+%%#
+%%# has been used, no chords are output anymore. You can make the effect
+%%# local by putting this command in a group. (\guitarNoChord redefines the
+%%# macros which are responsible for the actual output of the chords - see the
+%%# description at the end).
+%%#
+%%# The command
+%%#
+%%#       \guitarPreAccord
+%%#
+%%# is expanded before the actual chord is typeset: You can change this
+%%# definition to e.g. modify the font used for the chord. By default, this
+%%# command contains a \strut which ensures that the lines with chords
+%%# usually all have the same height.
+%%# The macro \guitarPreAccord may also use and modify the macro
+%%#
+%%#       \guitarAccord
+%%#
+%%# which contains the actual chord which is then output (you may use this
+%%# feature to e.g. calculate a modulation in \guitarPreAccord or to
+%%# replace the text of \guitarAccord by some graphic equivalent).
+%%#
+%%# It is guaranteed that the macros \guitarPreAccord and \guitarAccord
+%%# are expanded precisely once.
+%%# In contrast, it might happen that the argument of the chord (i.e. the
+%%# text over which the chord is put) is expanded twice.
+%%# (The doubled expansion could have been avoided, but the price were that
+%%# in some cases the TeX kerning mechanism would then fail if the argument
+%%# is a syllable of some word which is continued afterwards).
+%%#
+%%# Whenever the "guitar" mode or the "linefeed" mode is turned
+%%# on or off, the corresponding macro
+%%#
+%%#       \guitarMagicOnHook
+%%#       \guitarMagicOffHook
+%%#       \guitarCrOnHook
+%%#       \guitarCrOffHook
+%%#
+%%# is expanded (for switching on, the macro is expanded even before the
+%%# necessary catcode changes are done, and for switching off, the macro
+%%# is expanded after the catcodes have been restored).
+%%# In the current defaults, a group is opened and closed in
+%%# \guitarCrOnHook and \guitarCrOffHook: This is the reason why these
+%%# commands must be properly nested.
+%%# (The reason for this group is that"\parindent should be changed locally).
+%%#
+%%# In the current implementation, TeX forgets everything following the magic
+%%# tokens "|" and "_" in the chord (because these symbols are intended to be
+%%# the last one in the chord). If you want to use these tokens within a chord:
+%%# They loose their magic meaning if they occur in a braced context
+%%# (i.e. between { and }). If you regularly have to use these tokens within
+%%# chords, you can change the default choice of this tokens by the respective
+%%# commands
+%%#
+%%#       \toolboxMakeSplit{token}{guitarSplitDist}
+%%#       \toolboxMakeSplit{token}{guitarSplitMerge}
+%%#
+%%# (See the "toolbox" package for details of the command \toolboxMakeSplit
+%%# used here).
+%%# It should be pointed out that {token} may actually be a *sequence*
+%%# of tokens, so that for the `magic tokens' "|" and "_" you may instead use
+%%# whole phrases if you prefer.
+%%#
+%%# Some fine tuning of the spacing can be done by redefining
+%%#
+%%#       \guitarCalcDim
+%%#
+%%# When this macro is called, the skip register
+%%#
+%%#       \guitarDim
+%%#
+%%# contains the width of the chord which should be put over the text.
+%%# After \guitarCalcDim has been expanded, it is ensured that at least
+%%# \guitarDim (horizontal) space is reserved for the chord. Thus, if
+%%# \guitarCalcDim increases e.g. \guitarDim by 2pt (which is the
+%%# default behavior of \guitarCalcDim), then 2pt more space is reserved
+%%# for the chord than its actual size: This ensures that two subsequent
+%%# chords are always separated by some space.
+%%#
+%%# Finally, you can modify the macros which do the actual setting of the
+%%# chords: This setting is done by the commands
+%%#
+%%#       \guitarPut
+%%#       \guitarPutOnSpace
+%%#       \guitarPutDist
+%%#       \guitarPutMerge
+%%#
+%%# which with the exception of \guitarPutOnSpace all expect one argument
+%%# (namely the text on which they should be put). The command
+%%# \guitarPutOnSpace is called, if a space followed the chord argument.
+%%# Similarly, \guitarPutDist and \guitarPutMerge are called if the chord
+%%# argument ended with the magic symbol "|" respectively "_".
+%%# Before one of the above four macros is called, the chord text is stored in
+%%# the macro \guitarAccord (and has not been expanded to this time); also the
+%%# argument has not been expanded to this time. The above four macros are also
+%%# responsible for the appropriate expansion (also of the expansion of the
+%%# macros \guitarCalcDim and \guitarPreAccord, if
+%%# the latter should still keep their meaning).
+%%# The above four macros may freely use the skip register \guitarDim and the
+%%# box register \guitarBox (which are both not used or
+%%# modified by the other macros of this package).
+%%#
+
+%%#
+%%# Possible Problems:
+%%#
+
+%%# The special treatment of [ # b and linefeed is realized by a changing of
+%%# catcodes. This may cause essentially two sorts of problems:
+%%#
+%%# 1. In some cases, you will want to avoid the automatic replacement of '#'
+%%#    and 'b'. For example, in [\textbf{F#}] or in \guitarChord{\textbf{F#}}
+%%#    the "b" of "\textbf" gets replaced which is of course not what you want.
+%%#    To avoid this replacement, there is a  * version of the respective
+%%#    commands, i.e. the above example works in the intended way if you write
+%%#    instead [*\textbf{F\guitarSharp}] or
+%%#    \guitarChord*{\textbf{F\guitarSharp}}
+%%#    (you have to use the command "\guitarSharp", because due to the * also
+%%#    the # would not be replaced).
+%%#
+%%# 2. There are some situations in which catcodes are set too early,
+%%#    e.g. if you use the macros within the argument of certain macros.
+%%#    In this case, these symbols keep their usual \TeX\ meaning
+%%#    (which may either lead to an error in case of "#" (and sometimes "[") or
+%%#    just to a false output). If this happens to you, you have to replace at
+%%#    the corresponding place the above one-symbol shortcuts by their longer
+%%#    macro equivalents. In other words: You might have to replace in
+%%#    certain special situations some occurrences of the symbols according to
+%%#    the following table:
+%%#
+%%#    [...]        ->   \guitarChord{...}
+%%#    #            ->   \guitarSharp
+%%#    b            ->   \guitarFlat
+%%#    linefeed     ->   \guitarEndLine
+%%#    2 linefeeds  ->   \guitarEndPar
+%%#    3+ linefeeds ->   \guitarEndDoublePar
+%%#
+
+\endinput
+%%
+%% End of file `guitar.txt'.