%% LyX 2.3.2 created this file.  For more info, see http://www.lyx.org/.
%% Do not edit unless you really know what you are doing.
\documentclass[english]{scrartcl}
\usepackage[osf]{libertineRoman}
\usepackage[osf]{biolinum}
\renewcommand{\ttdefault}{cmtt}
\usepackage[libertine]{newtxmath}
\usepackage[T1]{fontenc}
\usepackage[latin9]{inputenc}
\setcounter{tocdepth}{2}
\usepackage{color}
\usepackage{babel}
\usepackage{booktabs}
\usepackage{textcomp}
\usepackage{url}
\usepackage{microtype}
\usepackage[unicode=true,
 bookmarks=true,bookmarksnumbered=false,bookmarksopen=false,
 breaklinks=false,pdfborder={0 0 0},pdfborderstyle={},backref=false,colorlinks=false]
 {hyperref}

\makeatletter

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% LyX specific LaTeX commands.
\newcommand{\noun}[1]{\textsc{#1}}
\newcommand*\LyXZeroWidthSpace{\hspace{0pt}}
%% Because html converters don't know tabularnewline
\providecommand{\tabularnewline}{\\}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% User specified LaTeX commands.
\usepackage{chordbox}
\usepackage{filecontents}

\newcommand\TikZ{Ti\emph{k}Z}
\newcommand\version{v1.0}
\hypersetup{
	pdftitle={Chordbox \version\ Documentation},
	pdfauthor={Steven Franzen}
}
\setkomafont{descriptionlabel}{\ttfamily\color{red}}
\makeatletter
\newcommand\namedlabel[2]{\begingroup
   \def\@currentlabel{#2}%
   \label{#1}\endgroup
}
\makeatother
\begin{filecontents}{chordbox.bib}
@software{leadsheets,
 	author = {Clemens Niederberger},
  	title = {leadsheets},
  	url = {https://ctan.org/pkg/leadsheets/},
  	version = {0.5b},
  	date = {2017-09-26},
}
@software{guitarchordschemes,
 	author = {Clemens Niederberger},
  	title = {guitarchordschemes},
  	url = {https://ctan.org/pkg/guitarchordschemes/},
  	version = {0.7},
  	date = {2016-08-16},
}
@software{gchords,
 	author = {Kasper Peeters},
  	title = {gchords},
  	url = {https://ctan.org/pkg/gchords/},
  	version = {1.20},
  	date = {2008-02-03},
}
@software{xifthen,
 	author = {Josselin Noirel},
  	title = {xifthen},
  	url = {https://ctan.org/pkg/xifthen/},
  	version = {1.4.0},
  	date = {2015-11-05},
}
@software{xstring,
 	author = {Christian Tellechea},
  	title = {xstring},
  	url = {https://ctan.org/pkg/xstring/},
  	version = {1.7c},
  	date = {2013-10-13},
}
@manual{pgfmanual,
   author    = {Till Tantau},
   title     = {The TikZ and PGF Packages},
   subtitle  = {Manual for version 3.0.1a},
   url       = {http://sourceforge.net/projects/pgf/},
   date      = {2015-08-29},
}
\end{filecontents}

\makeatother

\usepackage[bibstyle=standard,citestyle=authortitle-comp]{biblatex}
\addbibresource{chordbox.bib}
\begin{document}
\titlehead{\centering\chordbox[3]{G\sharp^{maj7}}{4,x,6,5,4,3}}
\title{Chordbox}
\subtitle{A \LaTeX{} package for drawing string instrument chord diagrams}
\author{Steven Franzen}
\date{\version\quad\today}
\publishers{\url{https://github.com/sfranzen/chordbox}}

\maketitle
\tableofcontents{}

\clearpage{}

\section{Package introduction}

This package is the result of a search similar to the one undertaken
by Clemens Niederberger for his \texttt{leadsheets} \autocite{leadsheets}
package: over the years I have collected many textual guitar tabs
and chord sheets that I finally wanted to put together and typeset
properly using \LaTeX , including guitar chord diagrams. The first
part of my requirements is now more than fulfilled by \texttt{leadsheets},
which provides all the tools for putting together chords and lyrics.
For the second part I found that there were only two relevant existing
packages: \texttt{guitarchordschemes}\autocite{guitarchordschemes}
and \texttt{gchords}\autocite{gchords}. Neither of these achieved
exactly what I wanted, so this package is my own attempt at providing
that tool.

Note that I am far from a \TeX{} guru; I know a bit of \LaTeX{} and
also have some familiarity with \TikZ{}, so I have gratefully used
the higher level interfaces provided by said package as well as \texttt{xifthen}\autocite{xifthen}
and \texttt{xstring}\autocite{xstring} for inspecting arguments.
The \noun{pgf}/\TikZ{} packages provide a powerful and versatile
framework for creating vector graphics using \LaTeX{} commands paired
with a special drawing syntax. One advantage of this is that you can
fully integrate graphics into your document that will always look
great: they will use the document fonts and can be rendered at any
size you desire, avoiding some issues associated with the use of external
images. This does not come without a cost, however; although the syntax
introduced by \TikZ{} is concise and easy to read, composing images
will require some thought, multiple commands and adjustments and can
be labour-intensive. Also, there is simply so much functionality that
the official manual\autocite{pgfmanual} currently spans almost 1200
pages of dense, though amply illustrated information.

The main aim of the present package is therefore to provide a way
of typesetting chord diagrams using \TikZ{}, while sparing the user
from the need to plough through its documentation to learn the required
drawing syntax. It does this by defining two commands that require
only a few arguments and encapsulate the necessary drawing instructions.
Their basic usage is introduced in Section \ref{sec:Usage}, along
with examples illustrating the various possibilities. Further information
needed by the drawing algorithm is stored using \noun{pgf}/\TikZ{}'
native key-value management system, which also makes it quite easy
to expose settings for modification by the user, allowing you to influence
the appearance of the resulting chord boxes. These are documented
in Section \ref{sec:Settings}, with some examples of the commands
you can use to change them.

\subsection{Loading the package}

\texttt{chordbox} currently does not support \LaTeX{} options, so it
is loaded simply by putting

\texttt{\textbackslash usepackage\{chordbox\}}\\
in your document's preamble.

\subsection{License}

This file is part of chordbox. Chordbox 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 \url{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.

Chordbox has the \noun{lppl} maintenance status `maintained'. The
Current Maintainer of chordbox is Steven Franzen.

\section{Usage\label{sec:Usage}}

The package provides two similar commands, \texttt{\textbackslash chordbox}
and \texttt{\textbackslash bchordbox}. The latter extends the former
to draw barred chords.

\subsection{The \texttt{\textbackslash chordbox} command}

Syntax: \texttt{\textbackslash chordbox{[}}\textlangle \emph{base
fret}\textrangle \texttt{{]}\{}\textlangle \emph{chord name}\textrangle\texttt{\}\{}\textlangle \emph{fret
positions}\textrangle\texttt{\}}

The simplest form of the command requires you to specify only the
\textlangle \emph{chord name}\textrangle{} and \textlangle \emph{fret
positions}\textrangle . The former can contain any text and math symbols
(see below), the latter should be a comma-separated list of elements,
one for each string, which may take the following values:
\begin{itemize}
\item \textlangle \emph{fret number}\textrangle {[}:\textlangle \emph{fingering
text}\textrangle {]}\\
A (positive) \textlangle \emph{fret number}\textrangle{} marks the
current string as fretted at that position. It may optionally be followed
by a colon and a \textlangle \emph{fingering text}\textrangle{} that
can be displayed on the fret symbol or below the chord box.
\item \emph{0} (zero)\\
Marks the current string as open (unfretted).
\item \emph{Anything else}\\
An empty element or one starting with anything other than a number
marks the current string as muted (not played).
\end{itemize}
It draws a grid resembling vertical strings crossing horizontal frets,
with a black bar at the top figuring as the instrument's nut. The
number of strings drawn is determined by the number of \textlangle \emph{fret
positions}\textrangle{} passed to the command, so generating chord
diagrams for different instruments is no problem:
\begin{center}
\begin{tabular}{ccc}
Ukulele & 5-string banjo & 6-string guitar\tabularnewline
\texttt{\small{}\textbackslash chordbox\{Am\}\{2,0,0,0\}} & \texttt{\small{}\textbackslash chordbox\{Am\}\{x,2,2,1,2\}} & \texttt{\small{}\textbackslash chordbox\{Am\}\{x,0,2,2,1,0\}}\tabularnewline
\chordbox{Am}{2,0,0,0} & \chordbox{Am}{x,2,2,1,2} & \chordbox{Am}{x,0,2,2,1,0}\tabularnewline
\end{tabular}
\par\end{center}

The number of frets drawn is initially 4, but this can be changed
through the configuration key \texttt{\ref{key:numfrets}}.

As mentioned, you can optionally provide fingering information for
a chord, which is particularly useful for writing chord charts and
other training materials. Because text on the fret symbol has to be
scaled to fit inside it and the default scale is small, \texttt{chordbox}
is initially configured to put this text below the strings, where
it can be rendered at a larger size. However, the other option may
be more appealing for larger diagrams, so both options can be used,
see \texttt{\ref{key:textbelow}} and \texttt{\ref{key:textonnode}}.
They are illustrated below, where the letter T is used for the thumb
and the digits for the other fingers, starting at 1 for the index
finger. The larger chord box on the right has been given a scale of
2.5 times the default.
\begin{center}
\begin{tabular}[t]{cc}
\multicolumn{2}{c}{\texttt{\small{}\textbackslash chordbox\{F\}\{1:T,3:3,3:4,2:2,1:1,x\}}}\tabularnewline
\chordbox{F}{1:T,3:3,3:4,2:2,1:1,x} & \pgfkeys{/chordbox/.cd,text on node=fingering,text below=none}
\tikzset{chordbox/.append style={scale=2}}
\chordbox{F}{1:T,3:3,3:4,2:2,1:1,x}\tabularnewline
\end{tabular}
\par\end{center}

By default, the \textlangle \emph{chord name}\textrangle{} is processed
by a command that typesets it in math mode and roman type (see \texttt{\nameref{key:name}}).
This allows the use of math symbols like \texttt{\textbackslash flat}
and \texttt{\textbackslash sharp} as well as the \textasciicircum{}
(superscript) operator to typeset decorated chord names:
\begin{center}
\begin{tabular}{cc}
\texttt{\small{}\textbackslash chordbox\{B\textbackslash flat m\}\{x,x,x,3,2,1\}} & \texttt{\small{}\textbackslash chordbox\{F\textbackslash sharp\textasciicircum\{maj7\}\}\{2,x,3,3,2,x\}}\tabularnewline
\chordbox{B\flat m}{x,x,x,3,2,1} & \chordbox{F\sharp^{maj7}}{2,x,3,3,2,x}\tabularnewline
\end{tabular}
\par\end{center}

For best results, make sure to select the same typeface for both text
and math typesetting. Of course, if you are also using the \texttt{leadsheets}
package, you could opt to use its \texttt{\textbackslash writechord}
command for typesetting chord names, see also subsection \ref{subsec:Other-keys}.

The \textlangle \emph{base fret}\textrangle{} is the number that,
although formally an optional argument, must be provided for chords
extending past the number of frets in the chord box. It is used to
position the box and fretted notes relative to this fret, for example
\texttt{\textbackslash chordbox{[}6{]}\{D\textbackslash sharp m\textasciicircum\{7\textbackslash flat
5\}\}\{x,6,7,6,7,x\}}:

\chordbox[6]{D\sharp m^{7\flat 5}}{x,6,7,6,7,x}

As can be seen, the nut is not drawn in these cases.

Finally, \texttt{chordbox} can also display the pitch of each note
in a chord, although the default is not to. The pitches do not need
to be specified manually, but are determined from the fret positions
given to the command and the configured tuning (\texttt{\ref{key:tuning}}).
Just like fingering information, you may choose to display it inside
the symbols or underneath the chord box, or combine both types of
information:
\begin{center}
\begin{tabular}{rccc}
Command & \multicolumn{3}{c}{\texttt{\small{}\textbackslash chordbox\{D\}\{x,x,0,2:1,3:3,2:2\}}}\tabularnewline
\midrule
Scale & default & 2.5 $\times$ larger & 2.5 $\times$ larger\tabularnewline
\texttt{text on node} & \texttt{none} & \texttt{pitch} & \texttt{fingering}\tabularnewline
\texttt{text below} & \texttt{pitch} & \texttt{none} & \texttt{pitch}\tabularnewline
\midrule
Result & \pgfkeys{/chordbox/text below=pitch}
\chordbox{D}{x,x,0,2,3,2} & \pgfkeys{/chordbox/text on node=pitch}
\tikzset{chordbox/.append style={scale=2.5}}
\chordbox{D}{x,x,0,2,3,2} & \pgfkeys{/chordbox/.cd,text on node=fingering,text below=pitch}
\tikzset{chordbox/.append style={scale=2.5}}
\chordbox{D}{x,x,0,2:1,3:3,2:2}\tabularnewline
\bottomrule
\end{tabular}
\par\end{center}

Chords may of course feature accidentals on some or all of their notes,
depending on their associated musical key. Typesetting such pitches
clearly in limited space is more challenging than just single characters,
such as finger positions. With \TikZ{}, text is most conveniently
positioned using so-called \emph{nodes}, which can also be scaled
to display their contents at any size. This leads to the following
two possible choices:
\begin{enumerate}
\item Scale the nodes to the chord box, so they are always as large as possible
without overlapping;
\item Do not scale the nodes, but choose a fixed font size for the text,
small enough to avoid overlap at the chosen scale.
\end{enumerate}
The first option has the advantage that overlap is precluded entirely,
but the node text is scaled as well and will therefore need to be
changed to a size near that of the unscaled node. Additionally, the
scaling operation is a purely graphical transformation, which yields
worse results than selecting a similar font size in the first place.
This is because a well-designed font has different (namely slightly
thicker) glyphs for smaller sizes to maintain readability. The second
option instead has the disadvantage that a font size must be chosen
manually and calibrated to the size of the chord boxes one wishes
to render. However, because documents will not usually contain chord
boxes of many different sizes, I consider this to be a minor point
and have, at least for now, chosen the second option. The font size
initially configured specifically for pitch names below the strings
is \texttt{\textbackslash tiny}, which should produce readable results
even for the default chord box size.

\subsection{The \texttt{\textbackslash bchordbox} command}

Syntax: \texttt{\textbackslash bchordbox{[}}\textlangle \emph{base
fret}\textrangle \texttt{{]}\{}\textlangle \emph{chord name}\textrangle\texttt{\}\{}\textlangle \emph{fret
positions}\textrangle\texttt{\}\{}\textlangle \emph{barre frets}\textrangle\texttt{\}}

As mentioned, this command is for drawing barre chords, for which
it requires an additional comma-separated list of fret numbers. A
thick line is drawn over the string symbols at these frets. The other
arguments are identical to those of \texttt{\textbackslash chordbox},
see for example \texttt{\textbackslash bchordbox\{Bm\textasciicircum 7\}\{x,2,4,2,3,2\}\{2\}}
and \texttt{\textbackslash bchordbox{[}3{]}\{C\}\{x,3,5,5,5,3\}\{3,5\}}:

\bchordbox{Bm^7}{x,2,4,2,3,2}{2} \bchordbox[3]{C}{x,3,5,5,5,3}{3,5}

\section{Settings\label{sec:Settings}}

Because \texttt{chordbox} relies on \noun{pgf}/\TikZ{} for drawing,
it makes sense to use the powerful \noun{pgf} key management system
that comes with it. Therefore this package stores its code and style
settings as keys, some of which may be modified to customise the output.
This can be done in the preamble or in any part of the document by
means of \texttt{\textbackslash tikzset} and the more generic \texttt{\textbackslash pgfkeys}
command. Some examples of usage will be given below, but for more
reading about \noun{pgf} keys and their handling please refer to Section
82 of the \noun{pgf} manual\autocite{pgfmanual} where everything
is documented in full detail. In any case, modifying a key stores
its value for the \LaTeX{} group where the command is issued and its
child groups, which can override it again, but it does not propagate
up to parent groups.

\subsection{\TikZ{} keys}

The items described in this section are called \emph{styles} in \TikZ{}
terminology and contain (lists of) keys and values that can be applied
to various drawing commands. Most importantly, the \texttt{chordbox}
style applies to the whole \texttt{\{tikzpicture\}} environment of
every chord box produced. The default setting is to scale all coordinates
by a quarter, because the drawing is done in \noun{pgf}'s ``natural''
units that, though convenient to use, result in an impractically large
picture. Note that this scaling only influences the \TikZ{} coordinates;
in particular, fonts are not affected by default\footnote{This is because text is put in nodes, which are scaled independently
of the picture and require the \texttt{scale} and/or \texttt{transform
shape} options to be supplied.}.

Because these keys are all stored in the \texttt{/tikz} path, it is
most convenient to change them using the \texttt{\textbackslash tikzset}
command, for example \texttt{\textbackslash tikzset\{chordbox/.style=\{scale=0.4,
thick\}\}}. Setting options like this through the \texttt{.style}
\emph{key handler}, as it is called, replaces any previous contents.
Other handlers, like \texttt{.prefix style} and \texttt{.append style},
can be used to insert additional keys before or after the existing
style, respectively. For example, calling \texttt{\textbackslash tikzset\{chordbox/.append
style=\{scale=2\}\}} results in an effective \texttt{chordbox} style
of \texttt{\{baseline, scale=0.5\}}, because the \texttt{scale} factor
was set twice. These are special in that multiple values are multiplied
together, whereas for most other keys only the last occurrence applies.
\begin{description}
\item [{/tikz/chordbox}] \hfill{}(style, initially \texttt{\{baseline,
scale=0.25\}})\\
This style is applied to every \texttt{\{tikzpicture\}} environment
produced by this package. The \texttt{baseline} key sets the base
line of the picture at a height of 0 pt, which is the top of the grid
and the bottom of the nut (if drawn). It ensures that multiple chord
boxes in a row align properly.
\item [{/tikz/fret~node~text}] \hfill{}(style, initially \texttt{\{font=\textbackslash Large\textbackslash bfseries,text=white\}})\\
This style is applied to text drawn on fretted or open string nodes,
with the colour switched to black for the latter. It aims to make
the text as clear and as big as possible without increasing the node
size, which will occur if the text is too tall or wide.
\item [{/tikz/pitch~text~below}] \hfill{}(style, initially \texttt{\{font=\textbackslash tiny\}})\\
This affects only pitch names typeset below the chord box. The initial
setting is \texttt{\textbackslash tiny} to keep neighbouring notes
with accidentals from overlapping each other at the default scale.
\end{description}
The rest of the styles define the three symbol shapes used for the
fretted (\tikz[chordbox,above]\coordinate[string=fretted];), open
(\tikz[chordbox]\coordinate[string=open];) and muted (\tikz[chordbox]\coordinate[string=muted];)
string positions.
\begin{description}
\item [{/tikz/string/base}] \hfill{}(style, initially \texttt{\{circle,
draw, inner sep=0, minimum size=20, transform shape\}})\\
Common options for all three symbols. The \texttt{transform shape}
option is required to correctly scale the symbols, which are implemented
as \TikZ{} nodes, with the rest of the picture.
\item [{/tikz/string/fretted}] \hfill{}(style, initially \texttt{\{string/base,
fill\}})
\item [{/tikz/string/open}] \hfill{}(style, initially \texttt{\{string/base,
above\}})
\item [{/tikz/string/muted}] \hfill{}(style, initially \texttt{\{string/open,
cross out, minimum size=19\}})
\end{description}

\subsection{Other keys\label{subsec:Other-keys}}

The following keys are not passed directly to \TikZ{} commands, but
used to store various other settings and code. They are all in the
\texttt{/chordbox} path and should be set using the \texttt{\textbackslash pgfkeys}
command, for example \texttt{\textbackslash pgfkeys\{/chordbox/name/.code=\textbackslash writechord\{\#1\}\}}.
Keys that execute code, like this example, produce output with occurrences
of \texttt{\#1} replaced by the relevant value. If you want to change
more than one of these settings at once, it is shorter to issue a
command like the following: \texttt{\textbackslash pgfkeys\{/chordbox/.cd,
numfrets=5, fingering text=on node\}}.
\begin{description}
\item [{/chordbox/numfrets\texttt{\textcolor{black}{\small{}=\textlangle }}\texttt{\textcolor{black}{\emph{\small{}number}}}\texttt{\textcolor{black}{\small{}\textrangle }}\namedlabel{key:numfrets}{/chordbox/numfrets}}] \hfill{}(initially
\texttt{4}) \\
The number of frets drawn in each chord box.
\item [{/chordbox/base~fret}] \hfill{}(initially \texttt{\{fr\textbackslash raisebox\{.5ex\}\{\textbackslash scriptsize\#1\}})\\
This key stores the code used to typeset the base fret position of
a chord box, if provided and greater than 1.
\item [{/chordbox/name\label{key:name}}] \hfill{}(initially \texttt{\textbackslash ensuremath\{\textbackslash mathrm\{\#1\}\}})\\
The code that is used to typeset the name of the chord.
\end{description}
The next two keys govern the placement of extra information in the
chord box. In both cases, the \texttt{fingering} text is only displayed
if actually present in the input.
\begin{description}
\item [{/chordbox/text~below\texttt{\textcolor{black}{\small{}=none|fingering|pitch}}\namedlabel{key:textbelow}{/chordbox/text below}}] \hfill{}(initially
\texttt{fingering})\\
Selects what to display below each string.
\item [{/chordbox/text~on~node\texttt{\textcolor{black}{\small{}=none|fingering|pitch}}\namedlabel{key:textonnode}{/chordbox/text on node}}] \hfill{}(initially
\texttt{none})\\
Selects what to display inside the string symbols.
\end{description}
The remaining keys determine how pitch information is calculated and
displayed. Pitches should be given enclosed in quotation marks and
accidentals should be specified as \texttt{b} (flat) or \texttt{\textbackslash\#}
(sharp); these will be replaced by their respective symbols.
\begin{description}
\item [{/chordbox/flat~symbol\texttt{\textcolor{black}{\small{}=\textlangle }}\texttt{\textcolor{black}{\emph{\small{}symbol}}}\texttt{\textcolor{black}{\small{}\textrangle{}}}}] \hfill{}(initially
\texttt{\textbackslash flat})
\item [{/chordbox/sharp~symbol\texttt{\textcolor{black}{\small{}=\textlangle }}\texttt{\textcolor{black}{\emph{\small{}symbol}}}\texttt{\textcolor{black}{\small{}\textrangle{}}}}] \hfill{}(initially
\texttt{\textbackslash sharp})
\item [{/chordbox/pitch~names\texttt{\textcolor{black}{\small{}=\textlangle }}\texttt{\textcolor{black}{\emph{\small{}list~of~pitches}}}\texttt{\textcolor{black}{\small{}\textrangle{}}}}] \hfill{}(initially
\texttt{\{\textquotedbl A\textquotedbl ,\textquotedbl A\textbackslash\#\textquotedbl ,\textquotedbl B\textquotedbl ,\textquotedbl C\textquotedbl ,\textquotedbl C\textbackslash\#\textquotedbl ,\LyXZeroWidthSpace\textquotedbl D\textquotedbl ,\textquotedbl D\textbackslash\#\textquotedbl ,\textquotedbl E\textquotedbl ,\textquotedbl F\textquotedbl ,\textquotedbl F\textbackslash\#\textquotedbl ,\textquotedbl G\textquotedbl ,\textquotedbl G\textbackslash\#\textquotedbl\}})\\
The names of the pitches to be used for display. The list need not
start at A, but it must contain twelve sequential semitones.
\item [{/chordbox/tuning\texttt{\textcolor{black}{\small{}=\textlangle }}\texttt{\textcolor{black}{\emph{\small{}list~of~pitches}}}\texttt{\textcolor{black}{\small{}\textrangle }}\namedlabel{key:tuning}{/chordbox/tuning}}] \hfill{}(initially
\texttt{\{"E","A","D","G","B","E"\}})\\
The tuning of the instrument for which chord boxes are to be drawn.
It is used to determine the pitches of the chord and must consist
of elements present in \texttt{pitch names}.
\end{description}

\appendix
\printbibliography[heading=bibintoc]

\end{document}