summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/guitar/guitar.txt
blob: 149193f26e228d487926a0ffcef2ba24f6fa2928 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300

%%#
%%# Author and copyright 2001,2009,2013:
%%#
%%# M. V\"ath      martin@mvath.de
%%#
%%# The author thanks
%%#     Donald Arseneau <asnd@triumf.ca>
%%#     Dan Luecking    <luecking@uark.edu>
%%#     Heiko Oberdiek  <oberdiek@uni-freiburg.de>
%%# and a colleague who does not want to be named here.

%%# The package may be distributed and/or modified under the conditions of
%%# the LaTeX Project Public License (version 1.3c or later).

%%#############################################################################
%%#
%%#  guitar.sty - typesetting guitar chords over song texts.
%%#
%%#############################################################################

%%#
%%# This package should run with plain TeX, LaTeX 2.09, and LaTeX 2e.
%%# Actually, it should 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 implemented 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'.