% arara: pdflatex
% arara: biber
% arara: pdflatex
% arara: pdflatex
% --------------------------------------------------------------------------
% the GUITARCHORDSCHEMES package
% 
%   Guitar Chord and Scale Tablatures with TikZ
% 
% --------------------------------------------------------------------------
% Clemens Niederberger
% Web:    https://bitbucket.org/cgnieder/guitarchordschemes/
% E-Mail: contact@mychemistry.eu
% --------------------------------------------------------------------------
% Copyright 2013--2016 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.
% --------------------------------------------------------------------------
% The guitarchordschemes package consists of the files
%  - guitarchordschemes.sty,
%  - guitarchordschemes_en.tex,
%  - guitarchordschemes_en.pdf,
%  - README
% --------------------------------------------------------------------------
% If you have any ideas, questions, suggestions or bugs to report, please
% feel free to contact me.
% --------------------------------------------------------------------------
\documentclass[load-preamble+]{cnltx-doc}
\usepackage{guitarchordschemes}
\usepackage[chords]{leadsheets}

\setcnltx{
  package = guitarchordschemes ,
  authors = Clemens Niederberger ,
  email   = contact@mychemistry.eu ,
  url     = https://bitbucket.org/cgnieder/guitarchordschemes/ ,
  info    = guitar chord schemes and fingering scales with \TikZ ,
  add-cmds = {
    chordscheme,
    setchordscheme,
    setfingering ,
    scales
  } ,
  add-silent-cmds = textsuperscript ,
  abstract = {%
    \centering
    \chordscheme[
      name      = Gmi7 ,
      position  = II ,
      barre     = {2/2-4:3} ,
      show-root = {4/4} ,
      root      = {2/6:2} ,
      mute      = {1,5}
    ]%
  } ,
  index-setup = {
     othercode = \footnotesize ,
     level = \addsec ,
     noclearpage
  } ,
  makeindex-setup = {
     columns = 3 ,
     columnsep = 1em
  }
}

\addbibresource{\jobname.bib}
\begin{filecontents}{\jobname.bib}
@online{web:pietsch:fonts,
  author  = {Jochen Pietsch} ,
  title   = {Jazz Fonts} ,
  url     = {http://notation.jochenpietsch.de/index_e.html} ,
  urldate = {2012-05-10}
}
@book{leavitt:mmfg:1,
  author    = {William G. Leavitt},
  title     = {A Modern Method for Guitar},
  volume    = {1},
  publisher = {Berklee Press Publications, Boston},
  year      = {1966}
}
\end{filecontents}

\usepackage{ccicons}

\setchordscheme{
  finger-format+ = \biolinumLF ,
  name-format+   = \libertineLF ,
  chord-name-cs  = \chordname
}

\newcommand*\TikZ{Ti\textit{k}Z}

\begin{document}

\section{License and Requirements}

\license

\guitarchordschemes{} loads the packages \TikZ~\cite{pkg:pgf},
\pkg{etoolbox}~\cite{pkg:etoolbox} and \pkg{pgfopts}~\cite{pkg:pgfopts}.  It
also loads the \TikZ{} libraries \code{shapes.misc}, \code{arrows} and
\code{calc}.

% Depending on an option it also loads
% \pkg{realbookchords}~\cite{pkg:realbookchords}.  This package is not yet
% published on \CTAN{} and thus not part of any \TeX{} distribution. Until it is
% you can find it at \url{https://bitbucket.org/cgnieder/realbookchords/}.  See
% section~\ref{sec:realbookchords} for details on this option.

\section{The Commands}
This package mainly provides two commands:
\begin{commands}
  \command{chordscheme}[\oarg{options}]
    Typeset a guitar chord scheme.
  \command{scales}[\oarg{option}]
    Typeset a fingering scale.
\end{commands}
These commands set the frame for the chord and scale tablatures and can be used
to create sheets for manually writing down tablatures:
\begin{example}[side-by-side]
  \chordscheme
\end{example}

Similarly \cs{scales} creates a frame with two more frets:
\begin{example}
  \scales
\end{example}

\subsection{Options for \cs*{chordscheme}}
The \meta{options} argument is where the actual details for a chord
happen. These are the available ones for \cs{chordscheme}:
\begin{options}
  \keyval{fret-number}{number}\Default{4}
    \sinceversion{0.6}The number of frets that are drawn.  This number must be
    at least 4.  The option should be set as first option since it influences
    other options.
  \keyval{name}{chordsymbol}
    Set the chord symbol. This option accepts a comma separated list of
    entries.
  \keyval{position}{position}
    Set the position for the first of the four frets.
  \keychoice{finger}{\meta{fret}/\meta{string}:\meta{label}}
    Specify the finger positions for a chord.  This option accepts a comma
    separated list of entries.  The \code{:\meta{label}} is optional.
  \keychoice{root}{\meta{fret}/\meta{string}:\meta{label}}
    The same as finger but uses a square instead of a circle to indicate that
    this finger is playing the root of the chord.  This option accepts a comma
    separated list of  entries. The \code{:\meta{label}} is optional.
  \keychoice{show-root}{\meta{fret}/\meta{string}}
    Specify positions of the root that are \emph{not} part of the actual chord
    but are somewhere in the vicinity of it on the guitar neck.  This option
    accepts a comma separated list of entries.
  \keychoice{barre}{\meta{fret}/\meta{string range}:\meta{label}}
    Specify a barr\'e position for a chord.  The \meta{string range} part must
    contain a two string numbers separated with a dash.  This option accepts a
    list of entries. The \code{:\meta{label}} is optional.
  \keyval{ring}{string}
    Specify open strings.  This option accepts a comma separatedlist of
    entries.
  \keyval{mute}{string}
    Specify muted/un-played strings.  This option accepts a comma separated
    list of entries.
\end{options}

Let's take a look at a few examples:

\begin{example}[side-by-side]
  \chordscheme[
    name      = G ,
    position  = I ,
    finger    = {2/5:1} ,
    root      = {3/6:2, 3/1:4} ,
    ring      = {2,3,4}
  ]
\end{example}
\makeatletter
\setchordscheme{chord-name-cs=\@firstofone}
\makeatother

Or a more "`jazzy"' chord:
\begin{example}[side-by-side]
  \chordscheme[
    name      = G\textsuperscript{6} ,
    position  = II ,
    finger    = {1/4:1, 3/3:4, 2/2:3} ,
    root      = 2/6:2 ,
    show-root = 4/4 ,
    mute      = {1,5}
  ]
\end{example}

One with a barr\'e:

\begin{example}[side-by-side]
  \chordscheme[
    name      = Gmi\textsuperscript{7} ,
    position  = II ,
    barre     = 2/2-4:3 ,
    show-root = 4/4 ,
    root      = 2/6:2 ,
    mute      = {1,5}
  ]
\end{example}

\subsection{Options for \cs*{scales}}
The \meta{options} argument for \cs{scales} are similar to the ones for
\cs{chordscheme}:
\begin{options}
  \keyval{fret-number}{number}\Default{6}
    \sinceversion{0.6}The number of frets that are drawn.  This number must be
    at least 6.  The option should be set as first option since it influences
    other options.
  \keyval{name}{title}
    Set a title for the scale.
  \keyval{position}{position}
    Set the position for the first of the six frets.
  \keychoice{finger}{\meta{fret}/\meta{string}:\meta{label}}
    Specify the finger positions for the scale.  This option accepts a comma
    separated list of entries.  The \code{:\meta{label}} is optional.
  \keychoice{root}{\meta{fret}/\meta{string}:\meta{label}}
    The same as finger but uses a square instead of a circle to indicate that
    this finger is playing the root of the scale.  This option accepts a comma
    separated list of entries.  The \code{:\meta{label}} is optional.
  \keyval{fret number}{integer}\Default{6}
    The number of frets displayed for a scale.  The minimum number is 6.
  \keychoice{fingering}{type 1,type 1A,type 2,type 3,type 4}
    Set a whole predefined fingering.  The types correspond to ones taught
    in \citeauthor{leavitt:mmfg:1}'s
    \citetitle{leavitt:mmfg:1}~\cite{leavitt:mmfg:1}.  This option assumes an
    ionic scale and places the roots correspondingly.
  \keychoice{fingering*}{type 1,type 1A,type 2,type 3,type 4}
    The same as \option{fingering} but no scale is assumed and no roots are
    indicated.
  \keychoice{fingering?}{type 1,type 1A,type 2,type 3,type 4}
    The same as \option{fingering*} but also no labels for the fingers are given.
\end{options}

Let's see an example:
\begin{example}
  \scales[
    name      = F-major (Fingering Type~1A) ,
    position  = I ,
    fingering = type 1A
  ]
\end{example}

An example for \option{fingering*}:
\begin{example}
  \scales[
    name       = Fingering Type~3 ,
    fingering* = type 3
  ]
\end{example}

Now an example for \option{fingering?}:
\begin{example}
  \scales[
    name       = Fingering Type~2 ,
    fingering? = type 2
  ]
\end{example}

At last an example for an explicitly set scale:
\begin{example}
  \scales[
    finger = {
      2/1:1,               5/1:4,
      2/2:1,               5/2:4,
      2/3:1,        4/3:3, 5/3:4,
      2/4:1,        4/4:3,
      2/5:1, 3/5:2, 4/5:3,      
      2/6:1,               5/6:4
    }
  ]
\end{example}

You can add other predefined fingerings or change the existing ones with the
following command:
\begin{commands}
  \command{setfingering}[\marg{name}\marg{fingers}\marg{roots}]
    \sinceversion{0.7}\marg{name} sets the name as chosen by
    \option{fingering}, \option{fingering*} or \option{fingering?},
    \meta{fingers} is passed to the \option{finger} option and \meta{roots}
    either to the \option{finger} option or the \option{root} option depending
    if the fingering is called by \option{fingering}, \option{fingering*} or
    \option{fingering?}.
\end{commands}
As an example here is how fingering type 1A has been defined:
\begin{sourcecode}
  \setfingering{type 1A}{
                   3/1:2,        5/1:4,
                   3/2:2,        5/2:4,
            2/3:1, 3/3:2,        5/3:4,
            2/4:1,               5/4:4,
    1/5:1s,        3/5:2,        5/5:4,
                   3/6:2,        5/6:4
  }{1/1:1s, 3/4:2, 1/6:1s}
\end{sourcecode}

\section{Options}
There are quite a number of options determining the layout of the tablatures.
They can either be set as package options or via the setup command:
\begin{commands}
  \command{setchordscheme}[\marg{options}]
    The setup command for \guitarchordschemes.
\end{commands}

Below every option and its corresponding default setting is described.
\begin{options}
  \keyval{x-unit}{dim}\Default{.8cm}
    The basic $x$ unit for the \TikZ{} picture the chord scheme is set in.
  \keyval{y-unit}{dim}\Default{.8cm}
    The basic $y$ unit for the \TikZ{} picture the chord scheme is set in.
  \keyval{rotate}{angle}\Default{0}
    \sinceversion{0.7}Rotates the diagram counter-clockwise by \meta{angle}.
  \keyval{finger-format}{\TeX{} code}\Default{\cs*{sffamily}\cs*{small}}
    The format the numbers for the fingers are typeset with.
  \keyval{finger-format+}{\TeX{} code}\Default
    Code to be appended to \option{finger-format}.
  \keyval{position-format}{\TeX{} code}\Default{\cs*{sffamily}}
    The format the number for the position is typeset with.
  \keyval{position-format+}{\TeX{} code}\Default
    Code to be appended to \option{position-format}.
  \keyval{name-format}{\TeX{} code}\Default{\cs*{large}}
    The format the chord name/symbol is typeset with.
  \keyval{name-format+}{\TeX{} code}\Default
    Code to be appended to \option{name-format}.
  \keybool{name-below}\Default{false}
    \sinceversion{0.7}If set to \code{true} the name will be written below
    instead of above the diagram.
  \keyval{name-distance}{dim}\Default{.5em}
    \sinceversion{0.7}The distance between name and chord diagram.
  \keyval{chord-name-cs}{cs}\Default{\cs*{@firstofone}}
    \sinceversion{0.5}The command that is used to parse the chord name.
    \meta{cs} needs to be a command that takes a mandatory argument.
  \keyval{scales-name-cs}{cs}\Default{\cs*{@firstofone}}
    \sinceversion{0.5}The command that is used to parse the scales name.
    \meta{cs} needs to be a command that takes a mandatory argument.
  \keyval{string-name-format}{\TeX{} code}\Default{\cs*{sffamily}\cs*{small}}
    The format the names of the strings are typeset with.
  \keyval{string-name-format+}{\TeX{} code}\Default
    Code to be appended to \option{string-name-format}.
  \keyval{strings}{num}\Default{6}
    \sinceversion{0.7}Sets the number of strings.
  \keyval{chord-frets}{number}\Default{4}
    \sinceversion{0.6}The default number of frets of a chord scheme.
    \meta{number} must be at least 4. 
  \keyval{scales-frets}{number}\Default{6}
    \sinceversion{0.6}The default number of frets of a scales scheme.
    \meta{number} must be at least 6.
  \keyval{line-width}{dim}\Default{1pt}
    The line width used for all lines drawn in the chord scheme.
  \keyval{finger-radius}{num}\Default{.1875}
    The radius of the circles that represent the fingers in multiples of
    \option{x-unit}.  Also determines the size of the root markers and the
    barr\'e.
  \keyval{finger-x-offset}{num}\Default{.375}
    The $x$ offset of the number with respect to the circle in multiples of
    \option{x-unit}.
  \keyval{finger-y-offset}{num}\Default{.375}
    The $y$ offset of the number with respect to the circle in multiples of
    \option{y-unit}.
  \keyval{finger-style}{\TikZ{} style}\Default{fill}
    The \TikZ{} style the circles representing the fingers are drawn with.
    This is equivalent to \cs*{tikzset}\Marg{finger
      style/.style=\{\meta{\TikZ{} style}\}}.
  \keyval{root-style}{\TikZ{} style}\Default{fill}
    The \TikZ{} style the squares representing the roots are drawn with.
    This is equivalent to \cs*{tikzset}\Marg{root style/.style=\{\meta{\TikZ{}
        style}\}}.
  \keyval{show-root-style}{\TikZ{} style}\Default{draw}
    The \TikZ{} style the squares representing the "`ghost roots"' are drawn
    with.  This is equivalent to \cs*{tikzset}\Marg{show root
      style/.style=\{\meta{\TikZ{} style}\}}.
  \keyval{ringing-style}{\TikZ{} style}\Default{draw}
    The \TikZ{} style the circles representing the open string markers are
    drawn with.  This is equivalent to \cs*{tikzset}\Marg{ringing
      style/.style=\{\meta{\TikZ{} style}\}}.
  \keyval{muted-style}{\TikZ{} style}\Default{cross out,draw}
    The \TikZ{} style the nodes representing muted strings are drawn with.
    This is equivalent to \cs*{tikzset}\Marg{muted style/.style=\{\meta{\TikZ{}
        style}\}}.
  \keyval{tuning}{comma separated list of string names}\Default{E,B,G,D,A,E}
    The tuning.  The strings are named from first to sixth string.  If you
    want to remove all names use \keyis{tuning}{,,,,,}.
  \keybool{restrict-bounding-box}\Default{false}
    \sinceversion{0.7}If set to \code{true} the bounding box of the \TikZ{}
    picture is not extended by string names, position labels etc.\@ but
    restricted (more or less) only to the chord scheme diagram itself.
\end{options}

\end{document}