summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/leadsheets/leadsheets_en.tex
blob: dbf744685c24cf6348b5021929f35e485cc79553 (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
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
% arara: pdflatex: { shell: on , action: nonstopmode }
% arara: biber
% arara: pdflatex: { action: nonstopmode }
% arara: pdflatex: { action: nonstopmode }
% --------------------------------------------------------------------------
% the LEADSHEETS package
% 
%   typesetting leadsheets and songbooks
%
% --------------------------------------------------------------------------
% Clemens Niederberger
% E-Mail: contact@mychemistry.eu
% --------------------------------------------------------------------------
% Copyright 2014--2019 Clemens Niederberger
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
% of this license or (at your option) any later version.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3 or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
% The Current Maintainer of this work is Clemens Niederberger.
% --------------------------------------------------------------------------
\documentclass[load-preamble+]{cnltx-doc}
\usepackage{leadsheets,bookmark}
\setcnltx{
  package = leadsheets ,
  info    = Typesetting leadsheets and songbooks ,
  authors = Clemens Niederberger ,
  email   = contact@mychemistry.eu ,
  url     = https://github.com/cgnieder/leadsheets/ ,
  add-cmds = {
    choir , chord , chordname ,
    definesongtitletemplate ,
    defineversetypetemplate , 
    expandcode ,
    ifallsongproperties ,
    ifanysongproperty ,
    ifobeylines ,
    ifsongmeasuring ,
    ifsongpropertiesequal ,
    ifsongproperty ,
    ifversenamed ,
    ifversenumbered ,
    ifversestarred ,
    includeleadsheet ,
    instruction ,
    leadsheetstranslate ,
    lsenparen ,
    mkchoir ,
    mkinstruction ,
    mklsenparen ,
    mklsenparens ,
    newversetype ,
    printsongpropertylist ,
    setchords ,
    setleadsheets ,
    songproperty ,
    useleadsheetslibraries ,
    useleadsheetslibrary ,
    verseafterlabel ,
    verselabel ,
    verselabelformat ,
    versename ,
    versenumber ,
    writechord
  } ,
  add-silent-cmds = {
    @itemdepth ,
    arraybackslash ,
    endmdframed ,
    mdframed ,
    newfontfamily ,
    newrobustcmd ,
    musejazz
  } ,
  add-envs = {
    bridge ,
    chorus , chorus* ,
    flushleft ,
    flushright ,
    info ,
    interlude ,
    intro , intro* ,
    outro , outro * ,
    prechorus , prechorus* ,
    solo , solo* ,
    song ,
    verse
  } ,
  index-setup = { othercode=\footnotesize, level=\section , noclearpage } ,
  makeindex-setup = {  columns=3, columnsep=1em }
}

\defbibheading{bibliography}{\section{References}}
\addbibresource{\jobname.bib}

\usepackage{filecontents}
\begin{filecontents}{\jobname.bib}
@book{book:realbook,
  author    = {Various} ,
  title     = {The Real Book} ,
  volume    = {I} ,
  subtitle  = {C Edition} ,
  publisher = {Hal Leonard Publishing Corporation} ,
  isbn      = {978-0634060380} ,
  date      = {2000-01-01} ,
  edition   = {6th edition}
}
@book{book:newrealbook,
  author    = {Various} ,
  title     = {The New Real Book} ,
  volume    = {I} ,
  subtitle  = {C Edition} ,
  publisher = {Ama Verlag} ,
  isbn      = {978-0961470142} ,
  date      = {2009-02-12} ,
  edition   = {1st edition}
}
\end{filecontents}

\usepackage{booktabs}

\newidxcmd\library{\code{#1}}[ (library)]
\AtEndPreamble{%
  \pdfstringdefDisableCommands{%
    \def\library*#1{``#1''}%
  }%
}
\newrobustcmd*\musicsymbols{\library{musicsymbols}}
\newrobustcmd*\chords{\library{chords}}
\newrobustcmd*\musejazz{\library{musejazz}}

\setchords{format=\libertineLF}

\makeatletter
\colorlet{property}{cnltxgreen}
\newenvironment{properties}
  {%
    \def\prop{\@cnltx@option@item\propval}%
    \cnltxlist
  }
  {\endcnltxlist}

\newrobustcmd*\propval{\@ifstar{\cnltx@prop@star}{\cnltx@prop@nostar}}

\newrobustcmd*\cnltx@prop@star{%
  \cnltx@ifdash
    {\cnltx@prop@aux*\meta}
    {\cnltx@prop@aux*\marg}%
}
\newrobustcmd*\cnltx@prop@nostar{%
  \cnltx@ifdash
    {\cnltx@prop@aux{}\meta}
    {\cnltx@prop@aux{}\marg}%
}
\newcommand*\cnltx@prop@aux[4]{%
  \code{\property#1{#3}\cnltx@isvalue#2{#4}}%
}
\makeatother

\newidxcmd\property{\code{\textcolor{property}{#1}}}

\newrobustcmd*\symarg[1]{\textcolor{argument}{\code{#1}}}

\newidxcmd\titletemplate{\textit{\sffamily#1}}[\ (songtitle template)]
\newidxcmd\versetemplate{\textit{\sffamily#1}}[\ (verse-type template)]
\newidxcmd\shortcut{\code{#1}}[ (shortcut)]
\newidxcmd\pkgopt{\code{#1}}[ (package option)]
\newnote*\packageoption[1]{Package option: \pkgopt{#1}}

\newrobustcmd*\barsymbol{|}

\AfterPackage{hyperref}{%
\pdfstringdefDisableCommands{%
  \def\property#1{#1}%
}}

\renewcommand*\dictumauthorformat[1]{#1}
\renewcommand*\raggeddictumtext{}

\begin{document}

\part{About the Package}
\dictum[Tom Waits]{%
  I like beautiful melodies telling me terrible things.%
}

\section{License and Requirements}

\license

\leadsheets{} requires the bundles \bnd{l3kernel}~\cite{bnd:l3kernel} and
\bnd{l3packages}~\cite{bnd:l3packages}  to be available.  It also needs the
package \pkg{translations}~\cite{pkg:translations}.

\section{Background}

Over the years I repeatedly wanted to typeset simple leadsheets of songs, \ie,
song lyrics and the corresponding chords\footnote{I also have had the need (or
  let's say: wish) to typeset leadsheets in the style of the
  \citetitle{book:realbook} -- but this is a task where other software than
  \LaTeX{} usually is far easier.}.  This is not too hard with standard
\LaTeX{} commands and environments but it is not very convenient\ldots{} so
looking for existing packages is the logical next step and I found two very
promising packages: \pkg{songs}~\cite{pkg:songs} and
\pkg{songbook}~\cite{pkg:songbook}.  However, both were note \emph{quite} what
I wanted.  Just a bit too inflexible in the wrong places, needing tweaking
here and there, and so on.  On the other hand I had quite some code lying on
my hard drive with various attempts of typesetting leadsheets.  This package
is now the attempt to have a clean, documented and customisable version of my
code\footnote{Plus new things!}.

\section{The Structure of the Package}
\leadsheets{} is a modular package and consists of several
libraries\footnote{This did seem like a good idea for maintenance when I first
  came up with it.  Now I'm not so sure any more but I am way too lazy to
  change it back.  So here we are\ldots}.  If you just say
\begin{sourcecode}
  \usepackage{leadsheets}
\end{sourcecode}
then the \library{songs} library is loaded\footnote{Which currently means that
  \emph{all} libraries are loaded as the \library{songs} library needs them.}.
If you want to ensure that \emph{every} library is loaded\packageoption{full}
so you don't have to think about it any more you can use
\begin{sourcecode}
  \usepackage[full]{leadsheets}
\end{sourcecode}
This actually loads every library except the \library{musejazz} library.

If you instead use\packageoption{minimal}
\begin{sourcecode}
  \usepackage[minimal]{leadsheets}
\end{sourcecode}
then \emph{no} libraries are loaded.  In this case you have to load the
libraries yourself in order to use the package.
\begin{commands}
  \command{useleadsheetslibraries}[\marg{comma list of libraries}]
    With this command one or several of \leadsheets' libraries can be loaded.
  \command{useleadsheetslibrary}[\marg{library}]
    With this command one of \leadsheets' libraries can be loaded.
\end{commands}

The libraries are divided into two parts: libraries to be loaded by users and
auxiliary libraries loaded by other libraries but not to be loaded directly by
users.

The user-libraries are the following ones:
\begin{description}
  \item[\library{musicsymbols}] \packageoption{musicsymbols}This library makes
    the music symbol font provided by MusiX\TeX{} available as text font.  It
    is described in part~\ref{part:musicsymbols-library}.
  \item[\library{chords}] \packageoption{chords}This library defines a
    few macros for typesetting of chord symbols.  It is described in
    part~\ref{part:chords-library}.  It also loads the
    \library{musicsymbols}library.
  \item[\library{musejazz}] \packageoption{musejazz}extends the \chords\
    library to use MuseScore's \enquote{MuseJazz} font, see
    section~\ref{sec:musejazz-libr}.  It loads the \library{chords}
    library.
  \item[\library{songs}] \packageoption{songs}This is the \emph{main
    library}.  It defines everything necessary for the typesetting of the
    leadsheets.  It currently loads \emph{all other libraries}, \ie, user
    libraries \emph{and} internal libraries, except for the \library{musejazz}
    library.  This library is described in part~\ref{part:leadsheets-songs-library}.
  \item[\library{external}] \packageoption{external}enables to include
    external leadsheet documents using the \cls{leadsheets} class into a main
    document, see part~\ref{part:external-leadsheet} for details.
\end{description}
Those libraries can also be loaded as a package option.  If you say
\begin{sourcecode}
  \usepackage[musicsymbols]{leadsheets}
\end{sourcecode}
then \emph{only} the \library{musicsymbols} library is loaded.  Saying
\begin{sourcecode}
  \usepackage[songs]{leadsheets}
\end{sourcecode}
is the same as using the package \emph{without} any options.  ``Without any''
also means that neither \library{musicsymbols}, \library{chords} nor
\library{songs} has been given as class option!

There is also a number of auxiliary libraries which are all needed by
the \library{songs} library.  The libraries are usually not described in
sections of their own but as part of the \library{songs} library.  However,
the following list gives hints to where some of the concepts are explained:
\begin{description}
  \item[\library{properties}] This is an auxiliary library not meant to be
    loaded directly by users.  It defines the necessary macros for song
    properties.  See section~\ref{sec:song-properties} for more details on the
    concept.
  \item[\library{shorthands}] This is an auxiliary library not meant to be
    loaded directly by users.  It provides means for defining shorthand
    characters.
  \item[\library{transposing}]  This is an auxiliary library not meant to be
    loaded directly by users.  It defines a transposing mechanism for chord
    symbols.  See section~\ref{sec:transposing} for further details.
  \item[\library{chordnames}]  This is an auxiliary library not meant to be
    loaded directly by users.  It defines the necessary macros for printing
    chords.
  \item[\library{templates}] This is an auxiliary library not meant to be
    loaded directly by users.  It defines the necessary macros for
    \leadsheets' template mechanism.  See section~\ref{sec:templates} for
    details on the concept.
  \item[\library{translations}] This is an auxiliary library not meant to be
    loaded directly by users.  It provides a few translations for a number of
    printed strings.  See section~\ref{sec:internationalization} for more
    information.
\end{description}

\part{The \library*{musicsymbols} Library}\label{part:musicsymbols-library}
\dictum[Victor Hugo]{%
  Music expresses that which cannot be said and on which it is impossible to
  be silent.%
}
\vspace*{\baselineskip}\csname @afterheading\endcsname

The \musicsymbols{} library is a very small library that makes the music
symbol font provided by MusiX\TeX{} available as text font and then uses it to
define a number of symbols.  This redefines the macros \cs{sharp}, \cs{flat}
and \cs{natural}.  All defined symbols are listed in
table~\ref{tab:musicsymbols}.

If you want to use the library standalone then you can say:
\begin{sourcecode}
  \usepackage[minimal]{leadsheets}
  \useleadsheetslibraries{musicsymbols}
\end{sourcecode}

\musicsymbols{} defines three further commands, namely \cs{musix},
\cs{textmusix} -- a font switch and a text font command -- and
\cs{musicsymbol}.  Those commands are meant for internal use only which is why
they're not explained here.

\begin{table}[htbp]
  \centering
  \newcommand*\showsymbol[1]{\cs{#1}&\csuse{#1}}
  \caption{Symbols defined by \musicsymbols.}
  \begin{tabular}{llll}
    \toprule
      \bfseries Command & \bfseries Symbol &
      \bfseries Command & \bfseries Symbol \\
    \midrule
      \showsymbol{sharp}       & \showsymbol{flat} \\
      \showsymbol{doublesharp} & \showsymbol{doubleflat} \\
      \showsymbol{natural} \\
    \midrule
      \showsymbol{trebleclef}  & \showsymbol{bassclef} \\
      \showsymbol{altoclef}    \\
    \midrule
      \showsymbol{allabreve}   & \showsymbol{meterC} \\
    \midrule
      \showsymbol{wholerest}   & \showsymbol{halfrest} \\
      \showsymbol{quarterrest} & \showsymbol{eighthrest} \\
      \showsymbol{sixteenthrest} \\
    \midrule
      \showsymbol{Break} \\
    \bottomrule
  \end{tabular}
  \label{tab:musicsymbols}
\end{table}

\musicsymbols{} also defines a number of macros for denoting bars.  Those
macros are listed in table~\ref{tab:bar-symbols}.

\begin{table}[htbp]
  \centering
  \newcommand*\showsymbol[1]{\cs{#1}&\csuse{#1}}
  \caption{Bar symbols.}
  \begin{tabular}{llll}
    \toprule
      \bfseries Macro & \bfseries Symbol &
      \bfseries Macro & \bfseries Symbol \\
    \midrule
      \showsymbol{normalbar}   & \showsymbol{leftrepeat} \\
      \showsymbol{rightrepeat} & \showsymbol{leftrightrepeat} \\
      \showsymbol{doublebar}   & \showsymbol{stopbar} \\
    \bottomrule
  \end{tabular}
  \label{tab:bar-symbols}
\end{table}

There are three macros that can be redefined to adjust the appearance of those
bars:
\begin{commands}
  \command{normalbarwidth}\Default{.02em}
    The thickness of a bar rule as used in \cs{normalbar}.
  \command{thickbarwidth}\Default{.15em}
    The thickness of the thick bar rules as used for example in
    \cs{leftrepeat} or \cs{stopbar}.
  \command{interbarwidth}\Default{.1em}
    The distance between two bar rules as in \cs{doublebar} or \cs{stopbar}.
\end{commands}

Finally \musicsymbols{} provides a macro for adding an abitrary meter:
\begin{commands}
  \command{meter}[\marg{numerator}\marg{denominator}]
    \sinceversion{0.5}For example \verbcode+\meter{6}{8}+: \meter{6}{8}
\end{commands}

\clearpage
\part{The \library*{chords} Library (and the \library*{musejazz}
  Library)}\label{part:chords-library}
\dictum[Wes Montgomery]{%
  I never practice my guitar -- from time to time I just open the case and
  throw in a piece of raw meat.%
}

\begin{figure}
  \centering
  \includegraphics[scale=.5,trim=0 22cm 10cm 2cm,clip]{ring-of-fire.pdf}
  \caption{One possible layout for \leadsheets{} mimicking the typewriter
    style.}
  \label{fig:leadsheet}
\end{figure}

\section{The \cs*{writechord} Command}

\chords{} provides the command \cs{writechord}\marg{chord} for convenient
typesetting of chords:

\begin{example}[side-by-side]
  \writechord{Bb7(#9)} \writechord{Bbb6}
  \writechord{C#7(b9)} \writechord{C##13}
\end{example}

\begin{commands}
  \command{chordname}[\marg{chord}]
    Typesetting chords.  Inside the argument every \code{\#} will be replaced
    by $\sharp$ and every \code{b} is replaced with $\flat$.  Numerals and
    parentheses are typeset as superscripts.  Everything between parentheses
    is always a superscript: \verbcode+\writechord{F#7(#11)}+
    \writechord{F#7(#11)}.
  \command{writechord}[\marg{chord}]
    This command can and actually \emph{should} be used for placing chords
    inline. It transforms the chords according to the options knows the
    options \option{input-notation} and \option{output-notation}.  This
    command also transforms the chord according to the options inside of the
    \env{song} environment \option{transpose} and \option{enharmonic} before
    printing it, see also page~\pageref{cs:writechord}.
\end{commands}

There are several token lists that are treated specially inside \cs{writechord}:
\begin{labeling}[--]{xxxxx}
  \item[\code{\^{}}] This token is replaced by \cs*{textsuperscript}.
  \item[\code{ma}] The symbol for major chords.  Per default this is
    empty. \verbcode+\writechord{Gma}+ \writechord{Gma}.
  \item[\code{mi}] The symbol for minor chords.  Per default this is
    \code{m}.  \verbcode+\writechord{Gmi}+ \writechord{Gmi}.
  \item[\code{o}] The symbol for diminished chords.  Per default this is
    \code{\cs*{textsuperscript}\Marg{o}}.  \verbcode+\writechord{Go}+
    \writechord{Go}.
  \item[\code{+}] The symbol for augmented chords.  Per default this is
    \code{\cs*{textsuperscript}\Marg{+}}.  \verbcode!\writechord{G+}!
    \writechord{G+}.
  \item[\code{/o}] The symbol for half diminished chords.  Per default
    this is \code{\cs*{textsuperscript}\Marg{\cs*{o}\Marg{}}}.
    \verbcode+\writechord{G/o}+ \writechord{G/o}.
  \item[\code{\#}] The \enquote{sharp} symbol.  Per default this is
    \cs{sharp}.  \verbcode+\writechord{F#}+ \writechord{F#}.
  \item[\code{\#\#}] The \enquote{double sharp} symbol.  Per default this is
    \cs{doublesharp}.  \verbcode+\writechord{F##}+ \writechord{F##}.
  \item[\code{b}] The \enquote{flat} symbol.  Per default this is
    \cs{flat}.  \verbcode+\writechord{Eb}+ \writechord{Eb}.
  \item[\code{bb}] The \enquote{double flat} symbol.  Per default this is
    \cs{doubleflat}.  \verbcode+\writechord{Ebb}+ \writechord{Ebb}.
  \item[\code{b\#}] Cancelling flat/sharp combination: this is removed.
  \item[\code{\#b}] Cancelling sharp/flat combination: this is removed.
  \item[\code{add}] This is superscripted: \verbcode+\writechord{Gadd9}+
    \writechord{Gadd9}.
  \item[\code{sus}] This is superscripted: \verbcode+\writechord{Gsus4}+
    \writechord{Gsus4}.
  \item[\code{dim}] This is superscripted: \verbcode+\writechord{Gdim5}+
    \writechord{Gdim5}.
  \item[\code{maj7}] This is superscripted: \verbcode+\writechord{Gmaj7}+
    \writechord{Gmaj7}.
  \item[\code{maj9}] This is superscripted: \verbcode+\writechord{Gmaj9}+
    \writechord{Gmaj9}.
\end{labeling}

How these token lists are treated depends on optional settings:

\begin{example}
  \setchords{
    major-seven = $\Delta$ ,
    major-nine  = $\Delta$\textsuperscript{9}
  }
  \writechord{Gmaj7} \writechord{Gmaj9}
  \writechord{G^6} \writechord{G6}
  \writechord{G7^#5}
\end{example}

If you want to use the library standalone then you can say:
\begin{sourcecode}
  \usepackage[minimal]{leadsheets}
  \useleadsheetslibraries{chords}
\end{sourcecode}
This also loads the \musicsymbols{} library.

\section{Options}

Options are set with the command
\begin{commands}
  \command{setchords}[\marg{options}]
    where \meta{options} is a comma separated list of keyval options.
\end{commands}
Actually there's a second possibility: options can also be set with the
command \cs{setleadsheets} (see section~\ref{sec:options}) if they're preceded
by \code{chords/} (including the slash).

The options allow detailed customization of how chords are printed.  It
doesn't change the input syntax.

\begin{options}
  \keyval{format}{code}\Default
    Code inserted before a chord within the same group. Can be used for
    special formatting of the chords, with \cs*{sffamily}, say.
  \keyval{sharp}{code}\Default{\cs{sharp}}
    The sharp symbol.
  \keyval{flat}{code}\Default{\cs{flat}}
    The flat symbol.
  \keyval{double-sharp}{code}\Default{\cs{doublesharp}}
    The double sharp symbol.
  \keyval{double-flat}{code}\Default{\cs{doubleflat}}
    The double flat symbol.
  \keyval{aug}{code}\Default{+}
    The augmented symbol.
  \keyval{half-dim}{code}\Default{\cs*{o}\Marg{}}
    The half-diminished symbol.
  \keyval{full-dim}{code}\Default{o}
    The diminished symbol.
  \keyval{dim}{code}\Default{\cs*{textsuperscript}\Marg{dim}}
    The token list \code{dim}.
  \keyval{add}{code}\Default{\cs*{textsuperscript}\Marg{add}}
    The token list \code{add}.
  \keyval{sus}{code}\Default{\cs*{textsuperscript}\Marg{sus}}
    The token list \code{sus}.
  \keyval{major}{code}\Default
    The token list \code{ma}.
  \keyval{minor}{code}\Default{m}
    The token list \code{mi}.  This option knows a special value.  If you set
    \keyis{minor}{lowercase} then minor chords are converted to lowercase
    letters.  This means an input \code{Dmi} becomes \code{d}.
  \keyval{major-seven}{code}\Default{\cs*{textsuperscript}\Marg{maj7}}
    The token list \code{maj7}.
  \keyval{major-nine}{code}\Default{\cs*{textsuperscript}\Marg{maj9}}
    The token list \code{maj9}.
\end{options}

There are further options which concern the different notations of the pitches
\writechord{B} and \writechord{Bb} in German (and a few other European
countries) and English.
\begin{options}
  \keychoice{input-notation}{german,english}\Default{english}
    If\changedversion{0.2} set to \code{german} B should be input as \code{H}
    and B~flat as \code{B}. If set to \code{english} B should be input as
    \code{B} and B~flat as \code{Bb}.
  \keychoice{output-notation}{german,english}\Default{english}
    \setchords{output-notation=german}If\changedversion{0.2} set to
    \code{german} B is output as \writechord{B} and B-flat as \writechord{Bb}.
  \keyval{german-B}{code}\Default{B}
    Customize\sinceversion{0.2} the output of B~flat when
    \keyis{output-notation}{german}.
  \keyval{german-H}{code}\Default{H}
    Customize\sinceversion{0.2} the output of B when
    \keyis{output-notation}{german}.
\end{options}

Let's see a few examples for the \option{input-notation} and
\option{output-notation} options.

\begin{example}
  input and output English:\par
  \writechord{Bb} \writechord{B} \writechord{B#}\par
  \writechord{B} \writechord{H} \writechord{H#}\par
  \medskip

  \setchords{input-notation=german}
  input German and output English:\par
  \writechord{Bb} \writechord{B} \writechord{B#}\par
  \writechord{B} \writechord{H} \writechord{H#}\par
  \medskip

  \setchords{output-notation=german}
  input and output German:\par
  \writechord{Bb} \writechord{B} \writechord{B#}\par
  \writechord{B} \writechord{H} \writechord{H#}\par

  \medskip
  \setchords{input-notation=english}
  input English and output German:\par
  \writechord{Bb} \writechord{B} \writechord{B#}\par
  \writechord{B} \writechord{H} \writechord{H#}
\end{example}

\section{The \library*{musejazz} Library}\label{sec:musejazz-libr}

The \musejazz\ library extends the \chords\ library to use
MuseScore's\footnote{\url{http://musescore.com/}} font \enquote{MuseJazz} for
the chord symbols.  The library contains the two lines which explains why it
requires \LuaLaTeX\ or \XeLaTeX.  Well, and the font, obviously.

\begin{sourcecode}
  \RequirePackage{fontspec}
  \newfontfamily\musejazz{MuseJazz}
\end{sourcecode}

Here is a small example of it's usage and the outcome:

\begin{example}[compile,program=xelatex,max-pages=1,add-frame=false]
  % compile with LuaLaTeX or XeLaTeX
  \documentclass[margin=4mm]{standalone}
  \usepackage{leadsheets}
  \useleadsheetslibrary{musejazz}
  \begin{document}
  \Huge\writechord{Bb7(#9)}\space\writechord{F##9}
  \end{document}
\end{example}

\clearpage
\part{The \library*{songs} Library}\label{part:leadsheets-songs-library}
\dictum[Jeff Beck]{%
  I don't care about the rules. If I don't break the rules at least ten
  times every song then I'm not doing my job.%
}

\section{Background}

The \leadsheets{} package allows for easy creation of leadsheets but it also
can be used to create complete songbooks. The basic idea is that songs are
typeset in the \env{song} environment.  Each song gets a number of properties
(see section~\ref{sec:song-properties}) that determine how the title of the
song is typeset.  For the typesetting of the titles a template mechanism is
used (see section~\ref{sec:title-templates}).  Songs can also be tagged.  The
tags then allow to typeset only songs matching a list of tags that is
specified via an option.

\begin{figure}
  \centering
  \includegraphics[width=.9\linewidth]{liederbuechlein.jpg}
  \caption{Even before officially publishing this bundle I used it for
    typesetting a small songbook!}
  \label{fig:liederbuch}
\end{figure}

\section{The \env*{song} Environment}

\begin{environments}
  \environment{song}[\oarg{options}\marg{properties}]
    The main environment used to typeset songs.  It has a mandatory argument
    where the song's properties are set
    (\cf\ section~\ref{sec:song-properties}).  It also has an optional
    argument for setting options specific to the song.
\end{environments}

\subsection{A First Example}
First let's take a look at an example:

\begin{example}[
  compile,
  graphics={trim={2cm 18cm 2cm 2cm},clip},
  add-sourcecode-options={literate=}]
  \documentclass{article}
  \usepackage{leadsheets}
  \begin{document}

  \begin{song}{title={Mary Had A Little Lamb}, music={Stevie Ray Vaughan},
      lyrics={traditional}, tags={srv,blues}}
  \begin{verse}
    Mary had a little lamb \\
    Its fleece was white as snow, yea \\
    Everywhere the child went \\
    The little lamb was sure to go, yea
  \end{verse}
  \begin{verse}
    He followed her to school one day \\
    And broke the teacher's rule \\
    What a time did they have \\
    That day at school
  \end{verse}
  \end{song}
  
  \end{document}
\end{example}

Per default the songtitle simply is a \cs{section}\sarg{} without any other
additions.  This is the songtitle template \titletemplate{minimal}, see
section~\ref{sec:title-templates} for more details on those templates and how
to create your own.

\subsection{Using the \env*{song} Environment}

Inside the \env{song} environment a number of additional environments are used
to specify the different parts of a song.  They all are basically the same
kind of environment, namely an \env*{itemize} environment internally where the
only \cs*{item} has the name of the environment as option.  The \env{verse}
environment is a little bit different since verses can be numbered.  If they
are then each usage of \env{verse} inside \env{song} will step a vers number
and print it (as option to the internal \cs*{item}).

\begin{environments}
  \environment{verse}[\oarg{options}]
    An environment for specifying the verses of a song.
  \environment{chorus}[\oarg{options}]
    An environment for specifying the chorus of a song.\\
    This is the same as \beginenv*\Marg{verse}\Oarg{type=chorus,\meta{options}}.
  \environment{intro}[\oarg{options}]
    An environment for specifying the intro of a song.\\
    This is the same as \beginenv*\Marg{verse}\Oarg{type=intro,\meta{options}}.
  \environment{interlude}[\oarg{options}]
    An environment for specifying an interlude of a song.\\
    This is the same as \beginenv*\Marg{verse}\Oarg{type=interlude,\meta{options}}.
  \environment{bridge}[\oarg{bridge}]
    An environment for specifying a bridge of a song.\\
    This is the same as \beginenv*\Marg{verse}\Oarg{type=bridge,\meta{options}}.
\end{environments}

These environments and their options are described in more detail in
sections~\ref{sec:envverse-environment} and~\ref{sec:other-envverse-like}.

\subsection{Options}\label{sec:options}

The options to the \env{song} environment are the same as the general options
of \leadsheets.  This means you can set the following options either local to
a song or global for the whole document with this command:

\begin{commands}
  \command{setleadsheets}[\marg{options}]
    Setup command for \leadsheets.
\end{commands}

Although I used the word \enquote{global} above \emph{all options are local to
  the current scope}!

\begin{options}
  \keyval{title-template}{template name}\Default{minimal}
    The songtitle template, see section~\ref{sec:title-templates} for
    details.
  \keyval{chord-cs}{cs}\Default{\cs*{chordname}}
    The command that is used to parse the chords.  See
    section~\ref{sec:placing-chords} for details.  \meta{cs} needs to be a
    command that takes a mandatory argument.
  \keyval{song-format}{code}\Default
    \meta{code} is inserted \emph{before} the song title at the
    beginning of the \env{song} environment.
  \keyval{text-format}{code}\Default
    \meta{code} is inserted \emph{after} the song title at the
    beginning of the \env{song} environment.
  \keyval{before-song}{code}\Default
    \meta{code}\sinceversion{0.3} is inserted at the beginning of a song
    \emph{before} the title!
  \keyval{after-song}{code}\Default
    \meta{code}\sinceversion{0.3} is inserted after the whole song.
  \keyval{after-title}{code}\Default
    \meta{code}\sinceversion{0.3} is inserted after the title of the song but
    before the body of the environment.
  % \keybool{numbered}\Default{false}
  %   Determines wether verses are numbered or not.
  \keyval{print-tags}{list of tags}
    A comma separated list of tags. When specified a song will only be printed
    if it is tagged with at least one of the tags in \meta{list of tags}.
  \keyval{add-to-reset}{list of counters}
    A\sinceversion{0.3} comma separated list of counters which should be
    reset for each song.
  \keybool{obey-lines}\Default{false}
    An experimental option.  Use at your own risk!  If set to \code{true} then
    inside the \env{verse} like environments end-of-lines will be obeyed and
    start a new line.  This comes with a price when using chords, see
    section~\ref{sec:placing-chords:caveat}.
  \keybool{bar-shortcuts}\Default{false}
    Makes the characters \shortcut{:} and \shortcut{\barsymbol} active inside
    the \env{song} environment.  See sections~\ref{sec:special-characters}
    and~\ref{sec:typesetting-bars} for more details.
  \keybool{disable-measuring}\Default{false}
    \sinceversion{0.4}This option turns of the song height measuring.  This
    makes song title template definitions easier (see section~\ref{sec:title-templates} for
    details).  \emph{The song property \property{height} will be set to 0pt then!}
\end{options}

\subsection{Song Properties}\label{sec:song-properties}

Songs can have a number of properties which basically are used in songtitle
templates (see section~\ref{sec:title-templates}).  One specific property,
\property{tags}, plays a different role, though.

\begin{properties}
  \prop{title}{title}
    This is the main title of the song.
  \prop{subtitle}{subtitle}
    A subtitle.
  \prop{short-title}{short song title}
    A short title (may be useful in a template that writes the titles in
    \cs*{section}s for a version to be used in the table of contents).
  \prop{sort-title}{song title}
    If not set explicitly this property holds the same value as
    \property{title}.
  \prop{sort-short-title}{short song title}
    If not set explicitly this property holds the same value as
    \property{short-title}.
  \prop{composer}{composer}
    The composer of the song.  As of now this accepts an arbitrary entry but
    maybe this will not be supported any more when indexing will be
    implemented.  No promises.
  \prop{sort-composer}{composer}
    If not set explicitly this property holds the same value as
    \property{composer}.
  \prop{lyrics}{writer}
    Whoever wrote the lyrics if different from the composer.  As of now this
    accepts an arbitrary entry but maybe this will not be supported any more
    when indexing will be implemented.  No promises.
  \prop{sort-lyrics}{writer}
    If not set explicitly this property holds the same value as
    \property{writer}.
  \prop{arr}{arranger}
    Whoever arranged the song.  As of now this accepts an arbitrary entry but
    maybe this will not be supported any more when indexing will be
    implemented.  No promises.
  \prop{sort-arr}{arranger}
    If not set explicitly this property holds the same value as
    \property{arr}.
  \prop{band}{band}
    The band who plays or played the song.
  \prop{sort-band}{band}
    If not set explicitly this property holds the same value as
    \property{band}.
  \prop{interpret}{interpret}
    The interpret of the song.  As of now this accepts an arbitrary entry but
    maybe this will not be supported any more when indexing will be
    implemented.  No promises.
  \prop{sort-interpret}{interpret}
    If not set explicitly this property holds the same value as
    \property{interpret}.
  \prop{genre}{genre}
    The genre of the song.
  \prop{key}{key}
    The key of the song.  This property is used for transposing and must have
    a specific format then, see section~\ref{sec:transposing}.
  \prop{capo}{fret}
    This property is used for transposing and for the \cs{capo} macro, see
    sections~\ref{sec:capo-information} and~\ref{sec:transposing} .
  \prop{tempo}{tempo}
    The tempo of the song.
  \prop{tags}{tags}
    A comma separated list of tags. Those tags play a role for the option
    \option{print-tags}.  When that option is used a song is only printed if
    it has at least one of the tags specified in the option.
\end{properties}

There are three more properties, \property{counter}, \property{ID} and
\property{height} that cannot be set but are set automatically for each song.
The \property{counter} simply holds the number of the current song starting
from \code{1} for the first song.  The \property{ID} currently always is
\code{song\meta{counter}} where \meta{counter} is the current
\property{counter} value.  The property \property{height} holds the height of
the typeset song in pt.  The height is determined by placing the body of the
respective \env{song} environment in a vertical box and measuring the height
and depth of the box.  This is done in a measuring phase that can and should
be tested in a songtitle template definition, see
section~\ref{sec:title-templates} for details.  \emph{This is important since
  the property \property{height} is not available in the measuring phase but
  only afterwards!}  If the option \option{disable-measuring} has been set the
property \property{height} will have the value~0pt!

In principle all properties can get list of entries where items are separated
with \code{\visualizespaces{ and }}.  Of course this doesn't make sense for
each property -- a song does only have one title.  But a song can very well
have more than one composer: think of the Beatles where most songs were
written by Paul McCartney and John Lennon\footnote{This is not quite true:
  most songs were mostly written either by Paul or John but legally usually
  both are the composers.}.

It is possibly to define further such properties.  For details see
section~\ref{sec:own-templates}.

\subsection{Special Characters}\label{sec:special-characters}
Inside the \env{song} environment several characters don't have their usual
catecory codes:
\begin{labeling}[--]{xxxxx}
  \item[\shortcut{\textasciicircum}] category code 13 (active). It is a
    shortcut for the \cs{chord} command.
  \item[\shortcut{\_}] category code 13 (active). It is a shortcut for the
    \cs{writechord} command.
  \item[\shortcut{\barsymbol}] category code 13 (active).  Used for
    typesetting bars.
  \item[\shortcut{:}] category code 13 (active).  Used for typesetting bars.
  \item[\code{\#}] category code 12 (other).  Used for chord names.
\end{labeling}

Actually the characters \shortcut{\barsymbol} and \shortcut{:} are \emph{not}
changed per default.  In order to do that you have to use the option
\option{bar-shortcuts}.

For details on the usage of the characters \shortcut{\barsymbol} and
\shortcut{:} see section~\ref{sec:typesetting-bars}.  The usage of chords is
explained in section~\ref{sec:placing-chords}.

\subsection{Capo Information}\label{sec:capo-information}
When you set the \property{capo} property the macro \cs{capo} writes
\begin{center}
  \GetTranslation{leadsheets/capo}: IV.~\GetTranslation{leadsheets/fret}
\end{center}
What it writes \emph{exactly} depends on a few settings: the \property{capo}
property obviously, which determines the number that is printed.  The
translations for the \enquote{capo} and \enquote{fret} strings (see
section~\ref{sec:internationalization} for details) and the setting of the
following option:
\begin{options}
  \keychoice{capo-nr-format}{arabic,roman,Roman}\Default{Roman}
    The format of the number printed by the \cs{capo} macro.
  \keyval{capo-nr}{code}\Default{\#1.}
    The code to print the number.  In the code refer to the number with
    \code{\#1}.
\end{options}

\section{The \env*{verse} Environment}\label{sec:envverse-environment}

\begin{environments}
  \environment{verse}[\oarg{options}]
    An environment for specifying the verses of a song.
  \environment{verse*}[\oarg{options}]
    The same as the \env{verse} environment but will always be unnumbered
    regardless of any option settings.
\end{environments}

\begin{example}[
  compile,
  graphics={trim={2cm 18cm 2cm 2cm},clip},
  add-sourcecode-options={literate=}]
  \documentclass{article}
  \usepackage{leadsheets}
  \setleadsheets{verse/numbered=true}
  \begin{document}

  \begin{song}{title=Foo}
  \begin{verse}
    Lorem ipsum dolor sit amet, consetetur sadipscing elitr,\\
    sed diam nonumy eirmod tempor invidunt ut labore et dolore\\
    magna aliquyam erat, sed diam voluptua.
  \end{verse}
  \begin{verse*}
    Lorem ipsum dolor sit amet, consetetur sadipscing elitr,\\
    sed diam nonumy eirmod tempor invidunt ut labore et dolore\\
    magna aliquyam erat, sed diam voluptua.
  \end{verse*}
  \begin{verse}
    Lorem ipsum dolor sit amet, consetetur sadipscing elitr,\\
    sed diam nonumy eirmod tempor invidunt ut labore et dolore\\
    magna aliquyam erat, sed diam voluptua.
  \end{verse}
  \end{song}
  
  \end{document}
\end{example}

\subsection{Options}\label{sec:verses-options}

The \env{verse} environment and all related environments have the following
options:

\begin{options}
  \keyval{format}{code}\Default
    \meta{code} is inserted at the beginning of the environment and can thus
    be used to add formatting, \eg, \keyis{format}{\cs*{itshape}}.
  \keyval{label-format}{code}\Default
    The same for the environment labels.
  \keyval{class}{class-name}\Default{default}
    The\sinceversion{0.2} \env{verse} environment and all related environments
    all belong to a class, the default class is called \code{default}.  This
    is of interest when using the \option{remember-chords} and
    \option{recall-chords} options.\label{option:class}
\end{options}

This can be used either locally, \ie, as option to the corresponding
environment, or for all environments of the same type using the setup command
using the following syntax:

\begin{center}
  \cs{setleadsheets}\Marg{\meta{env name}/format = \meta{code}}
\end{center}

\begin{example}
  \begin{verse}[format=\itshape]
    Lorem ipsum dolor sit amet, consetetur sadipscing elitr,\\
    sed diam nonumy eirmod tempor invidunt ut labore et dolore\\
    magna aliquyam erat, sed diam voluptua.
  \end{verse}
\end{example}

It is also possible so set the formatting for all related environments at
once:
\begin{options}
  \keyval{verses-format}{code}\Default
    Sets the format for all \env{verse} like environments.
  \keyval{verses-label-format}{code}\Default
    Sets the label format for all \env{verse} like environments.
\end{options}
Both options are overwritten if the options for a specific environment are
set.  That is, if you want all environments to have italic shape except for
choruses, then you could do
\begin{sourcecode}
  \setleadsheets{
    verses-format = \itshape ,
    chorus/format =
  }
\end{sourcecode}

\section{Placing Chords}\label{sec:placing-chords}

\subsection{The Commands}
Inside the \env{song} environment the characters \shortcut{\textasciicircum}
and \code{\_} are active characters\footnote{There are more characters with a
  special function, see
  section~\ref{sec:special-characters}}. \shortcut{\textasciicircum} is a
shortcut for the command \cs{chord}, \shortcut{\_} is a shortcut for
\cs{writechord}.  Those commands have the following functions:

\begin{commands}
  \command{chord}[\sarg\symarg{-}\marg{chord}\meta{text}\visiblespace]
    Places \meta{chord} centered above \meta{text}.  The starred version
    gobbles the trailing space while the unstarred version does not.  Like the
    star the dash is optional.  It sets the option \option{smash-next-chord}
    to \code{true}.  \meta{text} may be empty but the trailing space
    \emph{must} be there.  If \meta{text} is empty then the chord is place
    above some horizontal space which can be set with the option
    \option{empty-chord-dim}.
  \command{writechord}[\marg{chord}]
    This command transforms the chord according to the options
    \option{transpose} and \option{enharmonic} before printing it.  This
    command can/should be used for placing chords inline or for typesetting
    the \property{key} property in a template.  The command is used by
    \cs{chord} for the actual printing.  The command also transforms the
    chords according to the options \option{input-notation} and
    \option{output-notation}.\label{cs:writechord}
\end{commands}

\begin{example}[side-by-side]
  Text \chord{E7}text \chord*{B7}lon ger text 
\end{example}

\subsection{Usage}
Note that per default the width of a chord is not ignored:
\begin{example}[side-by-side]
  text \chord{Gbmi7(b5)}text text
\end{example}
However, there is an option which sets the width of a chord to zero:
\begin{options}
  \keybool{smash-chords}\Default{false}
    If set to true the width of the chords set with \cs{chord} is set to
    zero.
  \keybool{smash-next-chord}\Default{false}
    If set to true the width of the next chord set with \cs{chord} is set to
    zero.
\end{options}
\begin{example}[side-by-side]
  \setleadsheets{smash-next-chord=true}
  text \chord{Gbmi7(b5)}text text \par
  text \chord{Gbmi7(b5)}text text \par
  \setleadsheets{smash-chords=true}
  text \chord{Gbmi7(b5)}text text \par
  text \chord{Gbmi7(b5)}text text
\end{example}

Before we forget -- there are more options:
\begin{options}
  \keyval{empty-chord-dim}{dim}\Default{1em}
    The horizontal space that is inserted if the \meta{text} argument of
    \cs{chord} is empty.
  \keyval{align-chords}{col}\Default{c}
    Determines how a chord is aligned with respect to the word it is placed
    above of.  Valid input is any valid \env*{tabular} column identifier.
  \keybool{print-chords}\Default{true}
    If set to false \cs{chord} won't print the chord but will do nothing
    instead.  This options does not affect \cs{writechord}.
\end{options}

While \cs{chord} is available in the whole document the
\code{\textasciicircum} syntax is -- as mentioned before -- only available
inside of the \env{song} environment.

\begin{example}[
  compile,
  graphics={trim={2cm 16cm 2cm 4cm},clip},
  add-sourcecode-options={literate=}]
  \documentclass{article}
  \usepackage{leadsheets}
  \begin{document}

  \begin{song}{title={Mary Had A Little Lamb}, music={Stevie Ray Vaughan},
      lyrics={traditional}, tags={srv,blues}}
  \begin{verse}
    ^{E7} Mary had a little lamb ^{A7} \\
    Its fleece was white as ^{E7}snow, yea \\
    Everywhere the child ^{B7}went ^{A7} \\
    The little lamb was sure to ^{E7}go, yea
  \end{verse}
  \begin{verse}
    ^{E7} He followed her to school one day ^{A7} \\
    And broke the teacher's ^{E7}rule \\
    What a time did they ^{B7}have ^{A7} \\
    That day at ^{E7}school
  \end{verse}
  \end{song}
  
  \end{document}
\end{example}

You've probably noticed: chords are printed with \cs{chordname} in the default
setting.  You can change this with the option \option{chord-cs}.  If you do
then keep in mind that the input syntax will also change.

\subsection{Caveat}\label{sec:placing-chords:caveat}

If you use \keyis{obey-lines}{true} you have to be careful when you place
chords.  If you place a chord over the last word in a line
\begin{sourcecode}
  ^{F#mi} You've been ^*{B}run nin', ^*{E}hid in' much too ^{A}long.
\end{sourcecode}
then the end of line that is used as the mandatory space argument for
\cs{chord} may not be recognized as an end of line.  Even worse: at the end of
a \env{verse} like environment this may cause non-obvious errors.  So if
you're getting in trouble in these cases you should always insert an explicit
space, \eg. by one of the following methods:
\begin{sourcecode}
  ^{F#mi} You've been ^*{B}run nin', ^*{E}hid in' much too ^{A}long. {}
  ^{F#mi} You've been ^*{B}run nin', ^*{E}hid in' much too ^{A}long. \empty
  ^{F#mi} You've been ^*{B}run nin', ^*{E}hid in' much too ^{A}long. \relax
\end{sourcecode}

\subsection{Remembering Chords}\label{sec:remembering-chords}
\leadsheets{} has the option
\begin{options}
  \keybool{remember-chords}\Default{false}
    If set to \code{true} the chords in the \emph{first} appearance of a
    \env{verse} like environment are remembered.  In the next appearances of
    said environment the shortcut \shortcut{\textasciicircum} has changed its
    meaning and inserts a chord automatically.
\end{options}

Let's take at look at an example to see what this means:
\begin{example}
  \definesongtitletemplate{empty}{}
  \begin{song}[verse/numbered,remember-chords,title-template=empty]{title=foobar}
  \begin{verse}
    ^{G}Lorem ipsum ^{C}dolor sit ^{E7}amet, consetetur ^{Bb7(b5)}sadipscing
  \end{verse}
  \begin{verse}
    ^Lorem ipsum ^dolor sit ^amet, consetetur ^sadipscing
  \end{verse}
  \end{song}
\end{example}
In this example the chords used in the first \env{verse} environment have been
remembered and in the second \env{verse} environment the
\shortcut{\textasciicircum} shortcut inserted the corresponding chords in the
order they had been specified the first time.  It is important when using this
that you don't use the \shortcut{\textasciicircum} shortcut in subsequent
environments more often than the first time.  It will produce an error
otherwise.  You can use it less, of course.

The \shortcut{\textasciicircum} shortcut still has the \emph{the same} syntax
as \cs{chord} with one exception: it lacks the mandatory argument
\meta{chord} (since it's obviously not needed).  It has the optional \sarg{}
and \code{-}, though, as well as the mandatory space (\visiblespace)!

\emph{Please note that \shortcut{\textasciicircum} \emph{can't} be the last
  token in a line! It then should be followed by a space an an empty group --
  similar to the caveat in section~\ref{sec:placing-chords:caveat}.}

Each \env{verse} like environment (see section~\ref{sec:other-envverse-like}
for more information) is treated uniquely by this mechanism:

\begin{example}
  \definesongtitletemplate{empty}{}
  \begin{song}[verse/numbered,remember-chords,title-template=empty]{title=foobar}
  \begin{verse}
    ^{G}Lorem ipsum ^{C}dolor sit ^{E7}amet, consetetur ^{Bb7(b5)}sadipscing
  \end{verse}
  \begin{chorus}
    ^{F}Lorem ipsum ^{Gmi}dolor sit amet, consetetur ^{C7}sadipscing
  \end{chorus}
  \begin{verse}
    ^Lorem ipsum ^dolor sit ^amet, consetetur ^sadipscing
  \end{verse}
  \begin{chorus}
    ^Lorem ipsum ^dolor sit amet, consetetur ^sadipscing
  \end{chorus}
  \end{song}
\end{example}

This is important: \env{verse} and \env{verse*} are treated as two different
environments, the same holds for all starred \env{verse} like environments!
If you want to recall the chords of a different type of environment, then you
can use the option \option{recall-chords}:

\begin{example}
  \definesongtitletemplate{empty}{}
  \begin{song}[verse/numbered,remember-chords,title-template=empty]{title=foobar}
  \begin{verse}
    ^{G}Lorem ipsum ^{C}dolor sit ^{E7}amet, consetetur ^{Bb7(b5)}sadipscing
  \end{verse}
  \begin{chorus}
    ^{F}Lorem ipsum ^{Gmi}dolor sit amet, consetetur ^{C7}sadipscing
  \end{chorus}
  \begin{verse}
    ^Lorem ipsum ^dolor sit ^amet, consetetur ^sadipscing
  \end{verse}
  \begin{chorus}[recall-chords=verse-default]
    ^Lorem ipsum ^dolor sit amet, consetetur ^sadipscing
  \end{chorus}
  \end{song}
\end{example}

\section{Transposing}\label{sec:transposing}
Provided a song has the property \property{key} \emph{and} the key is given as
one of the twelve \enquote{usual} keys, \ie, one of the keys given in
table~\ref{tab:key-signatures}, the chords of a song can be transposed.

\begin{options}
  \keyval{transpose}{number}
    Transposes the chords of a song by \meta{number} of semitones.
    \meta{number} can be a negative number, then the chords are transposed
    down.
  \keychoice{enharmonic}{sharp,flat}
    Suppose you transpose a song in the key of \writechord{E} down a semitone.
    \leadsheets{} will then transpose to the key of \writechord{Eb}.  It always
    chooses the key whose signature has less accidentals.  You can force a
    variant, though, by using this option.  With \keyis{enharmonic}{sharp}
    \leadsheets{} would have chosen \writechord{D#} instead of \writechord{Eb}.
  \keybool{transpose-capo}
    When this is set to true chords are transposed down on semitone per capo
    fret.
\end{options}

The transposing mechanism relies on the \chords{} input syntax which means
that if you change \option{chord-cs} horrible things may happen.  \emph{So
  don't change \option{chord-cs} and use \option{transpose} at the same time!}

\begin{table}[htbp]
  \centering
  \catcode`\#=12
  \catcode`\!=6
  \def\showsignature!1{\writechord{!1}&\code{!1}}%
  \caption{Allowed keys for the \property{key} property.}
  \begin{tabular}{*{12}{l}}
    \toprule
      \bfseries Key & \bfseries Input &
      \bfseries Key & \bfseries Input &
      \bfseries Key & \bfseries Input &
      \bfseries Key & \bfseries Input &
      \bfseries Key & \bfseries Input &
      \bfseries Key & \bfseries Input \\
    \midrule
      \showsignature{C}   && &
      \showsignature{Cma} && &
      \showsignature{Ami} \\
    \cmidrule(lr){1-4} \cmidrule(lr){5-8} \cmidrule(lr){9-12}
      \showsignature{G}    & \showsignature{F} &
      \showsignature{Gma}  & \showsignature{Fma} &
      \showsignature{Emi}  & \showsignature{Dmi} \\
      \showsignature{D}    & \showsignature{Bb} &
      \showsignature{Dma}  & \showsignature{Bbma} &
      \showsignature{Bmi}  & \showsignature{Gmi} \\
      \showsignature{A}    & \showsignature{Eb} &
      \showsignature{Ama}  & \showsignature{Ebma} &
      \showsignature{F#mi} & \showsignature{Cmi} \\
      \showsignature{E}    & \showsignature{Ab} &
      \showsignature{Ema}  & \showsignature{Abma} &
      \showsignature{C#mi} & \showsignature{Fmi} \\
      \showsignature{B}    & \showsignature{Db} &
      \showsignature{Bma}  & \showsignature{Dbma} &
      \showsignature{G#mi} & \showsignature{Fbmi} \\
      \showsignature{F#}   & \showsignature{Gb} &
      \showsignature{F#ma} & \showsignature{Gbma} &
      \showsignature{D#mi} & \showsignature{Ebmi} \\
    \bottomrule
  \end{tabular}
  \label{tab:key-signatures}
\end{table}

\begin{example}[
  compile,
  graphics={trim={2cm 16cm 2cm 4cm},clip},
  add-sourcecode-options={literate=}]
  \documentclass{article}
  \usepackage{leadsheets}
  \begin{document}

  \begin{song}[transpose=2]{title={Mary Had A Little Lamb}, music={Stevie Ray
        Vaughan}, lyrics={traditional}, tags={srv,blues},key=E}
  \begin{verse}
    ^{E7} Mary had a little lamb ^{A7} \\
    Its fleece was white as ^{E7}snow, yea \\
    Everywhere the child ^{B7}went ^{A7} \\
    The little lamb was sure to ^{E7}go, yea
  \end{verse}
  \begin{verse}
    ^{E7} He followed her to school one day ^{A7} \\
    And broke the teacher's ^{E7}rule \\
    What a time did they ^{B7}have ^{A7} \\
    That day at ^{E7}school
  \end{verse}
  \end{song}
  
  \end{document}
\end{example}

\section{Other \env*{verse}-like Environments}\label{sec:other-envverse-like}
Songs can have lots of different kinds of parts: verses, choruses, bridges,
intros, outros, and so on.  Typographically they're all more or less the same,
at least for the purpose of this package.  This means we'd ideally have
environments for all of these parts with a distinct name in order to get a
clean source.  At the same time these environments should all behave basically
the same.  This is what the environments described in the following sections
are for.

\subsection{Available Environments}\label{sec:avail-envir}

\begin{environments}
  \environment{chorus}[\oarg{options}]
    An environment for specifying the chorus of a song.
  \environment{chorus*}[\oarg{options}]
    The same as \env{chorus} but does not display the label.
  \environment{intro}[\oarg{options}]
    An environment for specifying the intro of a song.
  \environment{intro*}[\oarg{options}]
    The same as \env{intro} but does not display the label.
  \environment{interlude}[\oarg{options}]
    An environment for specifying an interlude of a song.
  \environment{bridge}[\oarg{bridge}]
    An environment for specifying a bridge of a song.
  \environment{info}[\oarg{options}]
    An environment for specifying arbitrary information.  This environment has
    no label.
  \environment{solo}[\oarg{options}]
    An environment for specifying a solo to a song.
  \environment{solo*}[\oarg{options}]
    The same as \env{solo} but does not display the label.
\end{environments}

\subsection{Own \env*{verse}-like Environments}
All environments mentioned in the previous section were defined with this
command:
\begin{commands}
  \command{newversetype}[\sarg\marg{environment name}\oarg{default options}]
    This defines an environment \meta{environment name}.  This environment
    uses the verse-type template \versetemplate{itemize} (see
    section~\ref{sec:verse-type-templates}) unless specified differently in
    the \meta{default options}.  The starred version defines an environment
    which hides the displayed name.  More precisely: the macro \cs{verselabel}
    that is used in verse-type template definitions prints nothing in an
    environment defined with \cs{newversetype}\sarg.
    
    This also defines a translation string (see
    section~\ref{sec:internationalization}) \code{leadsheets/\meta{environment
        name}} with both an empty translation fallback and English translation
    unless specified differently with the \option{name} option.

    At last this defines a new counter \meta{environment name} and sets
    \cs*{the\meta{environment name}} to \code{\cs*{arabic}\Marg{environment
        name}.}.
\end{commands}

As mentioned before in section~\ref{sec:verses-options} all environments
defined this way have the options \option{format} and \option{label-format}.
They have more options.  Here's a complete list:
\begin{options}
  \keyval{format}{code}\Default
    \meta{code} is inserted at the beginning of the environment and can thus
    be used to add formatting, \eg, \keyis{format}{\cs*{itshape}}.
  \keyval{label-format}{code}\Default
    The same for the environment labels.
  \keyval{after-label}{code}\Default{:}
    \meta{code} is inserted in the label after the label text.
  \keyval{name}{name}\Default
    The translation fallback and English translation of the environment.  This
    should only be used with \cs{newversetype}.  Later changes should be made
    with \cs{DeclareTranslation} (see section~\ref{sec:internationalization}).
  \keyval{template}{template}\Default{itemize}
    The verse-type template used for the environment, see
    section~\ref{sec:verse-type-templates} for details.
  \keybool{numbered}\Default{false}
    If set to \code{true} \cs{verselabel} (used in verse-type template
    definitions, see section~\ref{sec:verse-type-templates}) adds a number
    after the name.
  \keybool{named}\Default{true}
    If set to \code{true} \cs{verselabel} (used in verse-type template
    definitions, see section~\ref{sec:verse-type-templates}) prints the name
    of the current environment (as determined by the translation of the
    corresponding string, see also section~\ref{sec:internationalization}).
  \keylit{recall-chords}{\meta{environment}-\meta{class}}
    An option to be used with the \option{remember-chords} mechanism, see
    section~\ref{sec:remembering-chords} for an example.  If you're not using
    different classes then \meta{class} needs to be \code{default}, see also
    page~\pageref{option:class}. The \option{class} to a \env{verse}-like
    environment allows for example to have verses with different chords which
    are still counted reguarly together with the \option{remember-chords}
    option.
\end{options}

There are also a number of general options for setting the defaults of some
options for all environments:
\begin{options}
  \keyval{verses-format}{code}\Default
    Sets the format for all \env{verse} like environments.
  \keyval{verses-label-format}{code}\Default
    Sets the label format for all \env{verse} like environments.
  \keyval{verses-after-label}{code}\Default{:}
    Defeault \meta{code} that is inserted in the label after the label text of
    \env{verse} like environments.
\end{options}
This options only determine the formatting of an environment if the
corresponding options of the environment hasn't been set.

Let's summarize: the label text of these environments is built of three items
in the following order:
\begin{enumerate}
  \item The \meta{code} set with the corresponding \option{label-format} option.
  \item The label text as defined as second argument to \cs{newversetype} or
    as declared through the corresponding translation.
  \item The \meta{code} set with the corresponding \option{after-label} option.
\end{enumerate}

\begin{example}
  \newversetype{foo}{Foo}
  \setleadsheets{
    foo/label-format = \bfseries ,
    foo/after-label  = ~$\Rightarrow$
  }
  \begin{foo}
    Lorem ipsum dolor sit amet, consetetur sadipscing elitr,\\
    sed diam nonumy eirmod tempor invidunt ut labore et dolore\\
    magna aliquyam erat, sed diam voluptua.
  \end{foo}
\end{example}

And just to give you some more examples here is how some of the existing
environments are defined:
\begin{sourcecode}
  \newversetype{verse}[ name=Verse, named=false, after-label= ]
  \newversetype*{verse*}
  \newversetype{chorus}[ name=Chorus ]
  \newversetype*{chorus*}
\end{sourcecode}

\section{Typesetting Bars}\label{sec:typesetting-bars}

Sometimes it can be useful to typeset the chord scheme of a song.  Then one
should be able to indicate start and beginnings of bars, maybe indicate
repeats and so on.  While this is obviously possible with the macros provided
by the \musicsymbols{} package listed in table~\ref{tab:bar-symbols} it may be
more convenient to have a shorter syntax.  This is why inside the \env{song}
environment some characters can be made (or are) active (see
section~\ref{sec:special-characters}).  For the typesetting of bars this are
the characters \shortcut{:} nor \shortcut{\barsymbol}. Per default they are
not active, though.  If you want to use the shortcut syntax you have to use
the option \option{bar-shortcuts}.  Here's a short example that emulates the
behaviour by setting the characters active explicitly:

\begin{example}[add-sourcecode-options={literate=}]
  \catcode`|=\active
  \catcode`:=\active
  |: repeat | this :|: and | this :| \par
  | this | part | ends | here || \par
  | the | song | is over | now |||
\end{example}

All possibly combinations that have a special definition are shown in the
example above.  The replacements that are done internally are these:
\begin{labeling}[--]{xxxxx}
  \item[\shortcut{\barsymbol}] \cs{normalbar}\cs*{space} (the space is there
    because otherwise it eats following spaces which would be annoying)
  \item[\code{|:}] \cs{leftrepeat}
  \item[\code{:|}] \cs{rightrepeat}
  \item[\code{:|:}] \cs{leftrightrepeat}
  \item[\code{||}] \cs{doublebar}
  \item[\code{|||}] \cs{stopbar}
\end{labeling}

\section{Templates}\label{sec:templates}
\subsection{Title Templates}\label{sec:title-templates}

\subsubsection{Background}
The titles of songs set with the \env{song} environment are displayed
according to the chosen title template.  It is chosen through the option
\option{title-template} which can be set with \cs{setleadsheets} or as option
to a specific \env{song} environment.  \leadsheets{} provides few predefined
templates and an easy mechanism to define own templates.

\subsubsection{Existing Templates}

Currently \leadsheets{} provides two templates:
\begin{description}
  \item[\titletemplate{minimal}] This only typesettes the song title in a
    \cs{section}\sarg.
  \item[\titletemplate{tabular}] This typesets the song title in a
  \cs{section} and prints some song properties in a \env*{tabular} below it.
  This template needs the \pkg{array}~\cite{pkg:array} package loaded.
\end{description}

\subsubsection{Own Templates}\label{sec:own-templates}
The principle is pretty straight forward: templates are defined with the
following command:
\begin{commands}
  \command{definesongtitletemplate}[\marg{name}\marg{code}]
    This defines the template \meta{name}.
\end{commands}
Inside of \meta{code} any code can be used.  The idea is that you use the
commands presented below to insert song properties where you want them.

First there are two commands related to defining new properties:
\begin{commands}
  \command{definesongproperty}[\marg{property}]
    Defines a new property \meta{property}.  All existing properties have been
    defined this way.  The command can only be used in the preamble.
  \command{copysongproperty}[\marg{from}\marg{to}]
    Copies the values of property \meta{from} to property \meta{to} if
    property \meta{to} has not been set but property \meta{from} has been.
    For example all \code{sort-\meta{property}} properties have been treated
    this way so they have the \meta{property} value as fallback.
    The command can only be used in the preamble.
\end{commands}

Then there are a number of commands related to retrieving and using the values
of properties.  All these commands only make sense inside a title template
definition (see section~\ref{sec:title-templates}).  Some of the commands are
expandable which means they can be used in an \cs*{edef} like context, \ie,
they are also suitable for writing the property values to the table of
contents or other auxiliary files.
\begin{commands}
  \expandable\command{songproperty}[\marg{property}]
    Retrieves property \meta{property}.
  \command{printsongpropertylist}[\oarg{code}\marg{property}\marg{between
    two}\marg{between more}\marg{between last two}]\Default{\cs*{@firstofone}}
    Prints a property list \meta{property} separated with \meta{between two}
    if the list contains only two items and separated with \meta{between more}
    and \meta{between last two} if the list contains more than two items.
    \meta{code} is placed directly in front of each item and items are
    surrounded with braces which means that the last token in \meta{code} may
    be a macro with a mandatory argument.
  \command{usesongpropertylist}[\oarg{code}\marg{property}\marg{between}]%
    \Default{\cs*{@firstofone}}
    Like \cs{printsongpropertylist} but separates items with \meta{between}
    regardless of the length of the list.
  \expandable\command{forsongpropertylist}[\marg{property}\marg{code}]
    Places all items of the property list \meta{property} in the input stream,
    each item preceded with \meta{code}.  Items are surrounded with braces
    which means that the last token in \meta{code} may be a macro with a
    mandatory argument.
  \expandable\command{ifsongproperty}[\marg{property}\marg{true}\marg{false}]
    Checks if property \meta{property} has been set.
  \command{ifanysongproperty}[\Marg{csv list of properties}\marg{true}\marg{false}]
    \sinceversion{0.4}Checks if any of the properties in \meta{csv list of
      properties} has been set.
  \command{ifallsongproperties}[\Marg{csv list of properties}\marg{true}\marg{false}]
    \sinceversion{0.4}Checks if all of the properties in \meta{csv list of
      properties} have been set.
  \command{ifsongpropertiesequal}[\marg{property 1}\marg{property
    2}\marg{true}\marg{false}]
    Checks if properties \meta{property 1} and \meta{property 2} have been set
    to the same value.
  \expandable\command{ifsongmeasuring}[\marg{true}\marg{false}]
    \leadsheets{} measures the height of a song body before it typesets it and
    it can often be necessary in a template to know if the measuring phase is
    active or not.  For example the song property \property{height} should
    only be used if \emph{not} in the measuring phase: it's value get's
    determined there and is not yet available.
  \command{expandcode}[\marg{code}]
    Exhaustively expands \meta{code}.  Experienced users won't need this.  It
    is essentially
    
    \cs*{begingroup}\cs*{edef}\cs*{x}\Marg{\cs*{endgroup}\meta{code}}\cs*{x}.

    (More precisely it is a wrapper for the expl3 function \cs*{use:x}.)  This
    means that any \code{\#} needs to doubled.  Inside the argument of this
    commands non-robust macros that should not be expanded need to be prefixed
    with \cs*{noexpand}.
\end{commands}

With the right template definition you can index composers, interprets, song
titles, \ldots{}  You can write tables of contents for properties such as song
titles, and so on, and so on.  \leadsheets{} does not do this for you and it
may require some experience to create templates which do all this.

\subsubsection{Examples}
In order to give you an idea on how to use songtitle templates I'll show you
how the existing ones are defined and one new definition.

\paragraph{The \titletemplate*{minimal} template}
This is quite short and self-explaining.

\begin{sourcecode}
  \definesongtitletemplate{minimal}{\section*{\songproperty{title}}}
\end{sourcecode}

\paragraph{A custom template}
Now let's see an example for a newly defined template.  It's nearly as simple
as the \titletemplate{minimal} template.

\begin{example}[
  compile,
  graphics={trim={2cm 18cm 2cm 2cm},clip},
  add-sourcecode-options={literate=}]
  \documentclass{article}
  \usepackage{leadsheets}
  \definesongtitletemplate{custom}{
    \ifsongmeasuring
      {\section*}
      {\section}{%
      \songproperty{title}%
      \ifsongproperty{music}
        { (music by \printsongpropertylist{music}{ \& }{, }{ \& })}
        {}%
    }
  }
  \setleadsheets{title-template = custom}
  \begin{document}

  \begin{song}{title={Mary Had A Little Lamb}, music={Stevie Ray Vaughan},
      lyrics={traditional}, tags={srv,blues}}
  \begin{verse}
    Mary had a little lamb \\
    Its fleece was white as snow, yea \\
    Everywhere the child went \\
    The little lamb was sure to go, yea
  \end{verse}
  \begin{verse}
    He followed her to school one day \\
    And broke the teacher's rule \\
    What a time did they have \\
    That day at school
  \end{verse}
  \end{song}
  
  \end{document}
\end{example}

\paragraph{The \titletemplate*{tabular} template}
This one is a lot more advanced and demonstrates various of the available
commands.

\begin{sourcecode}
  \definesongtitletemplate{tabular}{
    \ifsongmeasuring
      {\section*}
      {\section}%
      {\songproperty{title}}
    \begingroup\footnotesize
    \begin{tabular}{
        @{}
        >{\raggedright\arraybackslash}p{.5\linewidth}
        @{}
        >{\raggedleft\arraybackslash}p{.5\linewidth}
        @{}
      }
      \ifsongproperty{interpret}
        {\GetTranslation{leadsheets/interpret}}
        {}%
      \ifsongproperty{composer}
        {%
          &
          \GetTranslation{leadsheets/composer}: %
          \printsongpropertylist{composer}{ \& }{, }{ \& }
          \ifsongproperty{lyrics}
            {
              \\ &
              \GetTranslation{leadsheets/lyrics}: %
              \printsongpropertylist{lyrics}{ \& }{, }{ \& }
            }
            {}%
        }
        {}%
      \ifsongproperty{interpret}{\\}{\ifsongproperty{composer}{\\}{}}%
      \ifsongproperty{genre}
        {& Genre: \songproperty{genre} \\}
        {}%
      \ifsongproperty{tempo}
        {& Tempo: \songproperty{tempo} \\}
        {}%
      \ifsongproperty{key}
        {%
          & \setchords{
              major = -\GetTranslation{leadsheets/major} ,
              minor = -\GetTranslation{leadsheets/minor}
            }%
          \GetTranslation{leadsheets/key}: %
          \expandcode{\writechord{\songproperty{key}}} \\%
        }
        {}%
    \end{tabular}
    \par\endgroup
  }
\end{sourcecode}

A song using the \titletemplate{tabular} template:

\begin{example}[
  compile,
  graphics={trim={2cm 18cm 2cm 2cm},clip},
  add-sourcecode-options={literate=}]
  \documentclass{article}
  \usepackage{leadsheets}
  \usepackage{array}
  \setleadsheets{title-template = tabular}
  \begin{document}

  \begin{song}{title={Mary Had A Little Lamb}, interpret={Stevie Ray Vaughan},
      genre={blues}, tags={srv,blues},key=E}
  \begin{verse}
    ^{E7} Mary had a little lamb ^{A7} \\
    Its fleece was white as ^{E7}snow, yea \\
    Everywhere the child ^{B7}went ^{A7} \\
    The little lamb was sure to ^{E7}go, yea
  \end{verse}
  \begin{verse}
    ^{E7} He followed her to school one day ^{A7} \\
    And broke the teacher's ^{E7}rule \\
    What a time did they ^{B7}have ^{A7} \\
    That day at ^{E7}school
  \end{verse}
  \end{song}
  
  \end{document}
\end{example}

\subsection{Verse-type Templates}\label{sec:verse-type-templates}
\subsubsection{Background}
Similar to the songtitles also the \env{verse} like environments are typeset
using templates.  Defining them is just as easy as for the song titles.

\subsubsection{Existing Templates}
Currently \leadsheets{} provides only one template:
\begin{description}
  \item[\versetemplate{itemize}] Uses an \env*{itemize} environment for
    typesetting the corresponding environment.
\end{description}

\subsubsection{Own Templates}
Own templates can be defined using these commands:
\begin{commands}
  \command{defineversetypetemplate}[\marg{name}\marg{begin code}\marg{end code}]
    This defines the template \meta{name}.
  \command{verselabel}
    Used inside \cs{defineversetypetemplate}.  This determines where the label
    of the environment using the template will be displayed.
  \command{verselabelformat}
    Used inside \cs{defineversetypetemplate}.  The format of the current
    environment as set with the corresponding \option{format} option.
  \command{verseafterlabel}
    Used inside \cs{defineversetypetemplate}.  The format of the current
    environment as set with the corresponding \option{after-label} option.
  \command{versename}
    Used inside \cs{defineversetypetemplate}.  This prints the name of the
    current environment.
  \command{versenumber}
    Used inside \cs{defineversetypetemplate}.  Expands to the
    \cs*{the\meta{environment}} command for the current environment.
  \command{ifversestarred}[\marg{true}\marg{false}]
    Can be used inside \cs{defineversetypetemplate} for checking if the
    current environment was defined by the starred version of
    \cs{newversetype}.
  \command{ifversenumbered}[\marg{true}\marg{false}]
    Can be used inside \cs{defineversetypetemplate} for checking if for the
    current environment the option \option{numbered} is true or false.
  \command{ifversenamed}[\marg{true}\marg{false}]
    Can be used inside \cs{defineversetypetemplate} for checking if for the
    current environment the option \option{named} is true or false.
  \command{ifobeylines}[\marg{true}\marg{false}]
    Checks if for the current song the option \option{obey-lines} is true or
    false.
\end{commands}
Since with \cs{defineversetypetemplate} you define a template for an
environment it has two argument for code: one for code at the beginning of the
environment and one for code at the end.  The command \cs{verselabel}
internally uses the conditionals.  Its definition is equivalent to the
following:

\begin{sourcecode}
  \newcommand*\verselabel{%
    \ifversestarred
      {}
      {%
        \verselabelformat
        \ifversenamed
          {%
            \versename
            \ifversenumbered{ }{}%
          }
          {}%
        \ifversenumbered
          {\versenumber}
          {}%
        \verseafterlabel
      }%
  }
\end{sourcecode}

\subsubsection{Examples}
In order to give you an idea on how to use verse-type templates I'll show you
how the existing ones are defined and a few new definitions.

\paragraph{The \versetemplate*{itemize} template}
This is how the \versetemplate{itemize} is defined.
\begin{sourcecode}
  \makeatletter
  \defineversetypetemplate{itemize}
    {%
      \itemize
        \@itemdepth=0
        \ifobeylines
          {%
            \setlength{\parskip}{0pt}%
            \setleadsheets{ obey-lines-parskip = \parsep }%
          }
          {}%
        \item[{\verselabel}]%
    }
    {\enditemize}
  \makeatother
\end{sourcecode}
The most interesting part is probably the \cs{ifobeylines} part.  When the
option \option{obey-lines} is set to true an end of a line inserts a \cs*{par}
token.  So in order not to get a vertical skip after every line the template
sets \cs*{parskip} to zero.  With \keyis{obey-lines}{true} an empty line also
inserts a \cs*{par} token but it also inserts a vertical space according to
the value set with \option{obey-lines-parskip}.  This option can only be set
in a verse-type template definition (which is why it isn't documented
elsewhere).  All \env{verse} like environments initialize the length to the
current value of \cs*{parskip} \emph{before} the template code is inserted.

\paragraph{A \versetemplate*{flushleft} template}
An example for a template \versetemplate*{flushleft} that typesets the label
in the margin:
\begin{example}
  \defineversetypetemplate{flushleft}
    {%
      \noindent\llap{\verselabel\space}%
      \flushleft
      \unskip
      \vspace*{-\baselineskip}
      \ifobeylines
        {%
          \setlength\parskip{0pt}
          \setleadsheets{ obey-lines-parskip = .5\baselineskip }
        }
        {%
          \setlength\parskip{.5\baselineskip}
          \vspace*{-\parskip}
        }%
    }
    {\endflushleft}
  \begin{chorus}[template=flushleft]
    Lorem ipsum dolor sit amet, consetetur sadipscing elitr, \\
    sed diam nonumy eirmod tempor invidunt ut labore et dolore \\
    magna aliquyam erat, sed diam voluptua.

    Lorem ipsum dolor sit amet, consetetur sadipscing elitr, \\
    sed diam nonumy eirmod tempor invidunt ut labore et dolore \\
    magna aliquyam erat, sed diam voluptua.
  \end{chorus}
\end{example}

\paragraph{A \versetemplate*{flushright} template}
An example for a template \versetemplate*{flushright} that typesets the label
in the margin:
\begin{example}
  \defineversetypetemplate{flushright}
    {%
      \noindent\llap{\verselabel\space}%
      \flushright
      \unskip
      \vspace*{-\baselineskip}
      \ifobeylines
        {%
          \setlength\parskip{0pt}
          \setleadsheets{ obey-lines-parskip = .5\baselineskip }
        }
        {%
          \setlength\parskip{.5\baselineskip}
          \vspace*{-\parskip}
        }%
    }
    {\endflushright}
  \begin{chorus}[template=flushright]
    Lorem ipsum dolor sit amet, consetetur sadipscing elitr, \\
    sed diam nonumy eirmod tempor invidunt ut labore et dolore \\
    magna aliquyam erat, sed diam voluptua.

    Lorem ipsum dolor sit amet, consetetur sadipscing elitr, \\
    sed diam nonumy eirmod tempor invidunt ut labore et dolore \\
    magna aliquyam erat, sed diam voluptua.
  \end{chorus}
\end{example}

As you can see it's not entirely easy to define a template that suits both
songs with and without \keyis{obey-lines}{true}.  Personally I would forget
about that option and not care about it at all in my templates.

\paragraph{A \versetemplate*{framed} template}
Last but not least an example using the \pkg{mdframed}
package~\cite{pkg:mdframed} -- just to show you that everything is possible.
The example adapts one of the examples of \pkg{mdframed}'s manual.
\begin{example}
  \defineversetypetemplate{framed}
    {%
      \expandcode{%
        \noexpand\mdframed[
          \ifversestarred{}{%
            frametitle={%
              \noexpand\tikz[baseline=(current bounding box.east),outer sep=0pt]
                \noexpand\node[anchor=east,rectangle,fill=blue!20,rounded corners=2pt]
                {\noexpand\strut\noexpand\verselabel};
            }%
          },
          roundcorner = 5pt ,
          linecolor = blue!20 ,
          linewidth = 2pt,
          topline = true,
          frametitleaboveskip = \dimexpr-\ht\strutbox\relax ,
        ]%
      }%
      \setlength\parindent{0pt}
      \setlength\parskip{\parsep}
      \ifobeylines
        {\setleadsheets{ obey-lines-parskip=\parskip }\setlength\parskip{0pt}}
        {\vspace*{-\parskip}}%
    }
    {%
      \endmdframed
      \addvspace{\baselineskip}%
    }
  \begin{chorus}[template=framed]
    Lorem ipsum dolor sit amet, consetetur sadipscing elitr, \\
    sed diam nonumy eirmod tempor invidunt ut labore et dolore \\
    magna aliquyam erat, sed diam voluptua.

    Lorem ipsum dolor sit amet, consetetur sadipscing elitr, \\
    sed diam nonumy eirmod tempor invidunt ut labore et dolore \\
    magna aliquyam erat, sed diam voluptua.
  \end{chorus}
\end{example}

\section{Internationalization}\label{sec:internationalization}

Th environments described in sections~\ref{sec:envverse-environment}
and~\ref{sec:other-envverse-like} as well as a few other words used in
\leadsheets{} are translated with the help of the \pkg{translations}
package~\cite{pkg:translations}.  All predefined and available translation
strings are listed in table~\ref{tab:translations}. You can change those
translations or add translations for other languages with this command:
\begin{commands}
  \command*{DeclareTranslation}[\marg{language}\marg{string}\marg{translation}]
    The command provided by the \pkg{translations} package for translating
    strings.
\end{commands}
Those translations can be used for example in song title templates (see
section~\ref{sec:title-templates}).  One of the strings listed in
table~\ref{tab:translations} is a little different: the string
\code{leadsheets/interpret} is declared as
\begin{sourcecode}
  \DeclareTranslation{English}{leadsheets/interpret}
    {as interpreted by \printsongpropertylist{interpret}{ \& }{, }{ \& }}
  \DeclareTranslation{German}{leadsheets/interpret}
    {wie von \printsongpropertylist{interpret}{ \& }{, }{ \& } interpretiert}
\end{sourcecode}
which means it uses the song property \property{interpret}.  As a consequence
it only really can be used inside a \env{song} environment.  In other cases as
for example in table~\ref{tab:translations} the property part expands to
nothing (but the spaces around it are of course there).  Also keep in mind
that \cs{printsongpropertylist} is not expandable.

\begin{table}[htbp]
  \centering
  \caption{Predefined translation strings.}
  \newcommand*\showtranslation[1]{%
    \texttt{leadsheets/#1} &
    \GetTranslationFor{English}{leadsheets/#1} &
    \GetTranslationFor{German}{leadsheets/#1}
  }
  \begin{tabular}{lll}
    \toprule
      \bfseries String & \bfseries English & \bfseries German \\
    \midrule
      \showtranslation{major} \\
      \showtranslation{minor} \\
      \showtranslation{chorus} \\
      \showtranslation{verse} \\
      \showtranslation{composer} \\
      \showtranslation{lyrics} \\
      \showtranslation{key} \\
      \showtranslation{capo} \\
      \showtranslation{fret} \\
      \showtranslation{interpret} \\
      \showtranslation{intro} \\
      \showtranslation{interlude} \\
      \showtranslation{bridge} \\
      \showtranslation{solo} \\
    \bottomrule
  \end{tabular}
  \label{tab:translations}
\end{table}

\clearpage
\part{The \library*{external} Library and the \cls*{leadsheet}
  Class}\label{part:external-leadsheet}
\dictum[Thelonious Monk]{%
  Talking about music is like dancing about architecture.%
}

\section{The Idea}

For\sinceversion{0.5} some users -- like myself -- it may be desirable to
create leadsheets that can be reused in another document as a compilation of
songs.  The usual way would be to
\begin{itemize}
  \item either solve this manually by copying the \env{song} environment from
    one document to the other.  This is not ideal, of course.
  \item place the \env{song} in a file of its own and \cs*{input} it in the
    different documents.  This is easy and safe but requires a total of three
    files for two documents.  That's not really a problem, though, so it is a
    valid way.
\end{itemize}

\leadsheets{} now provides a third way.  You write the single leadsheet using
the \cls{leadsheet} class that comes with this package.  Let's call this file
\code{single.tex} for the following discussion:
\begin{sourcecode}
  \documentclass{leadsheet}
  \usepackage[T1]{fontenc}
  \usepackage[utf8]{inputenc}
  
  \begin{document}

  \begin{song}{ ... }
    ...
  \end{song}

  \end{document}
\end{sourcecode}

You can now include this document as is in another file -- let's call it
\code{multiple.tex}:
\begin{sourcecode}
  \documentclass{scrartcl}
  \usepackage{leadsheets}
  \useleadsheetslibraries{external}

  \begin{document}

  \includeleadsheet{single.tex}
  
  \end{document}
\end{sourcecode}

Depending on the settings this removes the complete preamble from
\code{single.tex} and only includes the document body of the file.

\section{The \cls*{leadsheet} Class}\label{sec:leadsheet-class}

The \cls{leadsheet} class is a class file built upon the \cls{scrartcl}
class.  It defines a song title template \titletemplate{leadsheet}, makes a
few setup choices
\begin{sourcecode}
  \setleadsheets{
    title-template = leadsheet ,
    bar-shortcuts ,
    verse/numbered ,
    verses-format = ,
    verses-label-format = \bfseries ,
    info/format = \itshape ,
    chorus/format = \itshape
  }
\end{sourcecode}
and sets the header and the footer of the leadsheet pages.

\begin{example}[
  compile,
  graphics={trim={2cm 18cm 2cm 2cm},clip},
  add-sourcecode-options={literate=}]
  \documentclass{leadsheet}
  \usepackage[T1]{fontenc}
  \usepackage[utf8]{inputenc}
  \usepackage[ngerman]{babel}

  \begin{document}

  \begin{song}{title={Mary Had A Little Lamb}, music={Stevie Ray Vaughan},
    interpret={Stevie Ray Vaughan}, lyrics={traditional}, tags={srv,blues}}
  \begin{verse}
    Mary had a little lamb \\
    Its fleece was white as snow, yea \\
    Everywhere the child went \\
    The little lamb was sure to go, yea
  \end{verse}
  \begin{verse}
    He followed her to school one day \\
    And broke the teacher's rule \\
    What a time did they have \\
    That day at school
  \end{verse}
  \end{song}

  \end{document}
\end{example}

The header contains \enquote{\meta{song title} (\meta{interpret})} if the
leadsheet has more than one page in total.  Otherwise it is empty.

The footer contains \enquote{\meta{page} of \meta{pages}} if the leadsheet has
more than one page in total.  Otherwise it is empty.

The class provides the verse type \env{prechorus}:
\begin{environments}
  \environment{prechorus}[\oarg{options}]
    Environment for marking the pre-chorus of a song.
\end{environments}

\begin{commands}
  \command{instruction}[\marg{text}]
    Short macro to add instructional text.
  \command{mkinstruction}[\marg{text}]
    The formatting macro used by \cs{instruction}.  You can redefine it in
    order to change the appearance.  The default definition is: \\
    \verbcode+\newcommand*\mkinstruction[1]{\emph{#1}}+
  \command{choir}[\marg{text}]
    Short macro to add (background) choir text.
  \command{mkchoir}[\marg{text}]
    The formatting macro used by \cs{choir}.  You can redefine it in
    order to change the appearance.  The default definition is: \\
    \verbcode+\newcommand*\mkchoir[1]{\instruction{\leadsheetstranslate{choir}: #1}}+
  \command{lsenparen}[\marg{text}]
    Short macro to add parentheses around text.  Used internally by
    \cs{instruction}.
  \command{mklsenparens}
    The parentheses setting macro used by \cs{lsenparen}.  You can redefine it
    in order to change the parentheses.  The default definition is: \\
    \verbcode+\newcommand*\mklsenparens{[]}+ \\
    \emph{The definition needs to be expandable and to expand to exactly two
      tokens or braced groups, one for the opening parenthesis and the second
      for the closing parenthesis!}
  \command{mklsenparen}[\marg{openen parenthesis}\marg{closing
    parenthesis}\marg{text}]
    The formatting macro used by \cs{lsenparen}.  You can redefine it in
    order to change the appearance.  The default definition is: \\
    \verbcode+\newcommand*\mklsenparen[3]{\textup{#1}#3\textup{#2}}+
\end{commands}

Here is an example that demonstrates \cs{choir} and \cs{instruction}.  (The
code of the example code has been saved in a file called
\code{single-leadsheet.tex}.  It is used later on again.)\label{single-leadsheet}
\begin{example}[compile,graphics={trim={2cm 18cm 2cm 2cm},clip},
  add-sourcecode-options={literate=}]
  \documentclass{leadsheet}
  \usepackage[T1]{fontenc}
  \usepackage[utf8]{inputenc}

  \begin{document}

  \begin{song}{title=foobar}
  \begin{verse}
    \instruction{keyboard only} \\
    Lorem ipsum dolor sit amet, consetetur sadipscing \\
    \choir{sed diam nonumy eirmod tempor invidunt ut labore et dolore}
  \end{verse}
  \begin{prechorus}
    \instruction{+ band} \\
    Lorem ipsum dolor sit amet, consetetur sadipscing
  \end{prechorus}
  \end{song}

  \end{document}
\end{example}
  
\section{The \library*{external} Library}

Loading the \library{external} library allows to include complete leadsheet
documents (\ie, with preamble) into a main document.  This requires the
included leadsheet to use the \cls{leadsheet} class (see
section~\ref{sec:leadsheet-class}).  When the file is included the whole
preamble of said file will be discarded.  This can be changed with an option
but then \cs*{usepackage} and \cs*{RequirePackage} will still be disabled and
simply do nothing in the included file.

\begin{commands}
  \command{includeleadsheet}[\sarg\oarg{options}\marg{file name}]
    Include the leadsheet \meta{file name}.  \meta{options} apply locally for
    the included file.  The file \meta{file name} may include a complete
    document preamble.
\end{commands}

\begin{filecontents*}{single-leadsheet.tex}
\documentclass{leadsheet}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}

\begin{document}

\begin{song}{title=foobar}
\begin{verse}
  \instruction{keyboard only} \\
  Lorem ipsum dolor sit amet, consetetur sadipscing \\
  \choir{sed diam nonumy eirmod tempor invidunt ut labore et dolore}
\end{verse}
\begin{prechorus}
  \instruction{+ band} \\
  Lorem ipsum dolor sit amet, consetetur sadipscing
\end{prechorus}
\end{song}

\end{document}
\end{filecontents*}
The next example shows the basic usage by inputting the example file mentioned
on page~\pageref{single-leadsheet}.  \emph{Notice that the formatting setup by
  the \cls{leadsheets} is not used}.  Also the title template
\titletemplate{leadsheet} is not defined in this process.
\begin{example}[compile,graphics={trim={2cm 18cm 2cm 2cm},clip},
  add-sourcecode-options={literate=}]
  \documentclass{scrartcl}
  \usepackage{leadsheets}
  \useleadsheetslibraries{external}

  \begin{document}

  \includeleadsheet{single-leadsheet}
  
  \end{document}  
\end{example}
Also notice that the \env{prechorus} environment and the \cs{instruction} and
\cs{choir} macros \emph{are} available!  \emph{All new macros defined in the
  \cls{leadsheet} class and described in section~\ref{sec:leadsheet-class} are
  defined}.  If you do not want this then you can use the starred version of
\cs{includeleadsheet}.  In this process the preamble of the included file is
gobbled.  It may be desirable not to have the preamble gobbled, though --
because of custom macro definitions for example.
\begin{options}
  \keybool{gobble-preamble}\Default{true}
    If set to \code{false} \cs{includeleadsheet} will not gobble the preamble
    of the file it inputs.  Using this is dangerous: for it to work
    \cs*{usepackage} and \cs*{RequirePackage} have to be disabled while the
    file is included.  So including the preamble may lead to more problems
    than it solves.
\end{options}

The included leadsheets do not have to be a complete document -- a standard
tex file only consisting of the \env{song} environments will work just as
nicely.  Files that are complete documents but are using another class than
\cls{leadsheet} will lead to errors, though.

\clearpage
\part{Appendix}
\dictum[Thelonious Monk]{Wrong is right.}
\appendix

\end{document}