\documentclass[a4paper,12pt]{article}

%%%%%%%%%%%%%%%%
% ``abc.sty'' from: http://abcplus.sourceforge.net/#abclatex
\usepackage[shellescape]{abc}
% PLEASE NOTE -- COMPILE WITH: latex --shell-escape
%%%%%%%%%%%%%%%%

\usepackage{hyperref}

% \usepackage[portuges]{babel}
\usepackage[latin1]{inputenc}
\usepackage{hyphenat}
%%%%%\usepackage{pandora}
\usepackage{graphicx}
\usepackage{verbatim} %%%% \verbatiminput environment
%
%\usepackage{txfonts}
%\usepackage{pxfonts}
%\usepackage{amsfonts}
%\usepackage{ccfonts}
\usepackage{qpalatin}
%\usepackage{qpalatin}
%\usepackage{palatcm}
\usepackage{url}

%\usepackage[left=1.5cm,top=1cm,right=1.5cm,nohead,nofoot]{geometry}
%\usepackage[left=1.5cm,top=1cm,bottom=2cm,right=1.5cm]{geometry}
\usepackage[left=1cm,right=1cm,top=1cm,bottom=2cm]{geometry}

%\newcommand{\dica}[1]{\fbox{\textbf{DICA:} #1}}
\newcommand{\microabc}{\mbox{\textbf{microabc}}}
\newcommand{\abcalias}{\mbox{\textbf{abc2alias}}}
\newcommand{\tclabc}{\mbox{\textbf{tclabc}}}
\newcommand{\tkabc}{\mbox{\textbf{tkabc}}}
\newcommand{\ABC}{\mbox{\texttt{ABC}}}
\newcommand{\abcmidi}{\mbox{\textbf{abc2midi}}}
\newcommand{\barfly}{\mbox{\textbf{BarFly}}}
\newcommand{\abcps}{\mbox{\textbf{abcm2ps}}}
\newcommand{\jcabcps}{\mbox{\textbf{jcabc2ps}}}
\newcommand{\abcpp}{\mbox{\textbf{abcpp}}}
\newcommand{\scala}{\mbox{\textbf{Scala}}}
\newcommand{\timidity}{\mbox{\textbf{timidity++}}}
\newcommand{\PS}{\mbox{\texttt{PostScript}}}
\newcommand{\MIDI}{\mbox{\texttt{MIDI}}}
\newcommand{\code}[1]{\mbox{\texttt{#1}}}

\title{Microtonal music with \ABC{}\\(\microabc{} tutorial)}
%\author{Hudson Lacerda\\\texttt{hfml@brfree.com.br}}
\author{Hudson Lacerda $<$\texttt{hfml@brfree.com.br}$>$}


\begin{document}
\sloppy
%%% \twocolumn

\maketitle
\tableofcontents

\newpage

%\maketitle
%\maketitle
% \hyphenation{ca-sa}

\section{Introduction}

How to make microtonal music using a computer? How to obtain a score
with a special, customised, microtone notation? How to get an audible
``previewing'' of a microtonal composition? Is all that feasible today
with 100\% free software? The answer for the last question is yes,
thanks to some \ABC{} music notation softwares.  Answers for the other
questions will be addressed through this text. \microabc{} was written
to make it easy to get microtonal music scores and \MIDI{} files with
\ABC{} tools.


\section{Software requirements}

First, you will need to obtain some pieces of software:\footnote{URIs
  for the sites from which the programs can be obtained are provided
  at the end of this document.}

\begin{itemize}
\item Get the (free/~libre/~open source) \ABC{} software
  tools:\footnote{Tip for Windows users: download the ``ABC command
    line tools for Windows'' package from
    \url{http://abcplus.sourceforge.net/\#abctools}}
  \begin{itemize}
  \item \abcpp{}, the \ABC{} preprocessor.
  \item \abcmidi{}, an \ABC{} to \MIDI{} converter.
  \item \abcps{}, a music typesetter that generates \PS{} files.
  \end{itemize}
\item Get a program to compute musical scales:
  \begin{itemize}
  \item \scala{} (free of charge).
  \end{itemize}
\item Get a \PS{} interpreter and previewer:
  \begin{itemize}
  \item \textbf{ghostscript}.
  \item\textbf{ghostsview}.
  \end{itemize}
\item Get a \MIDI{} player with Standard \MIDI{} Tuning support:
  \begin{itemize}
  \item \timidity{}.
  \end{itemize}
\item And do not miss \microabc{}, of course!
\end{itemize}

You should be aware that \abcpp{} must be compiled with sufficient
room for the macros generated by \microabc{}. Find the definition of
\texttt{MAX\_MACROS} in the source code and (re)define it as 512 or
like,\footnote{For \abcpp{} version 1.3.2,
  the line 43 of \texttt{abcpp.c} may be changed to, for instance:\\
  \texttt{\#define MAX\_MACROS 512 /* \# of \#defined macros */} }
then compile the program. In order to work with ``normal'' versions of
\abcpp{}, several samples in this tutorial use a limited pitch range.

The sample commands in this tutorial were tested on a Debian GNU+Linux
operating system. For other systems, they may need a few adaptations.

\section{Understanding the basic concepts}

One needs to know a set of concepts, in order to get started to
\microabc{}.\footnote{Basic knowledge of \ABC{} music notation is
  required -- \ABC{} will not described here. Fortunately, \ABC{} is
  easy -- you can learn it in a short time. A good text for
  introduction and reference is ``Making Music With \ABC{} Plus'' by
  Guido Gonzato.  Visit:
  \url{http://abcplus.sourceforge.net/\#ABCGuide}.}

\subsection{\ABC{} and microtones}

There are a few \ABC{} programs with support for microtonalism.
\abcps{} and \abcmidi{} provide rich features to get microtonal \PS{}
scores and \MIDI{} files.\footnote{\jcabcps{} and \barfly{} provide
  some (limited) support for microtonalism. Also, \tclabc{} includes a
  program called \tkabc{}, which is a graphical interface to write
  \ABC{} files -- \tkabc{} supports the same quarter-tone accidentals
  as \abcps{}.}

Both \abcps{} and \abcmidi{} represent microtonal pitches with a
fraction associated to an accidental. It is assumed that the fraction
is a fraction of a conventional tempered semitone. For instance,
\texttt{\^{}1/2C} is the pitch \texttt{C} raised by 1/2 semitone,
while \texttt{\_{14/100}E} is the pitch \texttt{E} lowered by 14
cents.\footnote{\abcmidi{} (since 2006-09-26) also supports
  temperaments of the linear class, thanks to the command
  \texttt{\%\%MIDI~temperamentlinear~octave\_cents~fifth\_cents},
  where octave and fifth sizes are given in cents.}

However, there are limitations in both programs: \abcps{} only
includes glyphs for conventional and quarter-tone accidentals (in a
Tartini-Couper style). Any other accidentals are indefinite, hence the
user should provide the \PS{} definitions for their glyphs. In turn,
\abcmidi{} cannot deal freely with microtonal accidentals in chords,
because normally the notes inside a chord go into a same \MIDI{}
channel, and the pitch bend messages (which assign the tuning to the
notes) are applied to all simultaneous notes sharing a same
channel.\footnote{\label{footchord}Since 2006-10-03, \abcmidi{}
  supports microtonal chords provided that a number of \MIDI{}
  channels be reserved with the command
  \texttt{\%\%MIDI~makechordchannels~n}, where \texttt{n} is the
  number of additional channels to allocate for the current voice.}
Another difference is that \abcps{} only accepts fractions which
numerator and denominator are lesser than 256.

To handle such limitations and differences between \abcps{} and
\abcmidi{}, and to provide shorter ways to represent pitches like
\texttt{\_{}137/1000A}, and also to compute the proper fractions for
each note, it seems to be a good idea to use a preprocessor and a tool
to generate the macro definitions required for a given tuning.

\begin{verbatim}
X:1
T:microabc tutorial
T:abcm2ps built-in microtonal accidentals
M:none
L:1/4
%%stretchlast
K:C
yy __B _3/B _B _/B =B ^/B ^B ^3/B ^^B |
\end{verbatim}

%%\begin{figure}
\begin{abc}[name=builtin]
X:1
T:microabc tutorial
T:abcm2ps built-in microtonal accidentals
M:none
%%stretchlast
L:1/4
K:C
yy __B _3/B _B _/B =B ^/B ^B ^3/B ^^B |
\end{abc}
%%\caption{\abcps{} builtin microtonal accidentals.}
%%\end{figure}

\subsection{Macros and preprocessors}

\microabc{} is a generator of \emph{macros}, that is, a definition of
a character string to be replaced with another character string. A
\emph{preprocessor} is a tool which (among other features) can carry
out macro replacements. This works much like the ``Find/Replace''
feature present in text editors.

For instance, let us suppose that we want to use a short macro name to
be replaced with the string \mbox{\texttt{\%\%begintext}}. For the
\abcpp{} preprocessor, we could define a macro like this:

\begin{verbatim}
#define %%BT %%begintext
\end{verbatim}

Given the definition above, all occurrences of \texttt{\%\%BT} in the
input file will be replaced with \mbox{\texttt{\%\%begintext}}. You
can try with macros just now, by using \abcpp{}.

First, create a text file named \mbox{\texttt{macroin.txt}} with this
content:

\begin{verbatim}
#define SCALE CDEFGABc
#define CHORD  [CEGc]
A C-major scale in written in ABC as:
        SCALE
A C-major tonic chord is written as:
        CHORD
\end{verbatim}

Then, run \abcpp{} on the file \mbox{\texttt{macroin.txt}}, by using
this command:

\begin{verbatim}
abcpp macroin.txt macroout.txt
\end{verbatim}

\abcpp{} will read the file \mbox{\texttt{macroin.txt}}, and convert
it in a new file named \mbox{\texttt{macroout.txt}}, replacing all
defined macro names with their corresponding replacement texts:

\begin{verbatim}
A C major scale in written in ABC as:
        CDEFGABc
A C major tonic chord is written as:
        [CEGc]
\end{verbatim}

\subsection{\microabc{} is a generator of macros}

\microabc{} was primarily intended to be a program to generate macro
definitions to represent microtonal music in \ABC{}. Let us try its
basic features with a few short examples.

Create a file \mbox{\texttt{ex1.txt}} with this content:

\begin{verbatim}
range: -5 7
alias: 0
0
1
2
\end{verbatim}

Now run \microabc{} on that file:

\begin{verbatim}
microabc < ex1.txt
\end{verbatim}

\microabc{} will print on the screen a list of macro definitions based
on the file \mbox{\texttt{ex1.txt}}, including these lines:

\begin{verbatim}
#define [1,,] =G,
#define [2,,] ^G,
#define [0,] =A,
#define [1,] ^A,
#define [2,] =B,
#define [0] =C
#define [1] ^C
#define [2] =D
#define [0'] ^D
#define [1'] =E
#define [2'] =F
#define [0''] ^F
#define [1''] =G
\end{verbatim}

Please note that, by default, the macro names are generated with
square braces, and the replacements are conventional \ABC{} pitches in
a chromatic sequence, with \texttt{=C} as the central pitch (our first
scale degree, named \texttt{[0]}). Such chromatic sequences (mappings)
are useful, for instance, when retuning \MIDI{} files with the program
\scala{}.

Note that there are 5 macros before \texttt{[0]}, and 7 macros after
it. This is the result of the command \mbox{\texttt{range:~-5~7}} of
the input file.

Please note yet that the macros use the given numbers 0, 1 and 2, with
additional commas (\texttt{,}) or apostrophes (\texttt{'}) for lower
or upper instances (normally used for octaves).

Finally, the command \mbox{\texttt{alias:~0}} was used to tell
\microabc{} that the first column (starting from 0) in the input file
contains the strings for the macro names. One can create several macro
definitions (``aliases'') for each pitch (same replacement), thus the
name of the command.

Of course, to use the definitions generated with \microabc{}, we will
want to store the output in a file.  This can be done by either of
these commands:

\begin{verbatim}
microabc < ex1.txt > ex1.abh
microabc -iex1.txt -oex1.abh
\end{verbatim}

\subsection{\microabc{} as a preprocessor}

Although preprocessing was not its initial goal, \microabc{} can be
used as a specialised preprocessor. In special, \microabc{}
preprocessor provides considerable support for the Sagittal Notation
System.\footnote{\url{http://users.bigpond.net.au/d.keenan/sagittal/}}
That feature is presented in the section \ref{sec:sagittal} (page
\pageref{sec:sagittal}).

\subsection{\label{sec:limit}\MIDI{} limitations}

One should be aware that \MIDI{} has severe limitations to represent
microtonal music.

One way to accomplish microtonal pitches is by using Pitch Bend
messages to change the tuning of the note; unfortunately that message
affects \emph{all} notes which share a same \MIDI{} channel. Thus, the
number of differently tuned pitches played simultaneously is limited
by the number of channels in use.  Sophisticated algorithms can
optimise the use of pitch bend messages, redirecting each note to a
suitable \MIDI{} channel. This can be done with \scala{}, when using
its *.seq file format, but there is not currently any \ABC{} program
with such a feature. \abcmidi{} usually outputs each voice to a
different channel, therefore chords in a same voice share a same
channel, so there is no easy way to tune the individual notes in a
chord.\footnote{The program \abcalias{} included in \microabc{}
  package can split \ABC{} chords in a set of temporary voices.
  However it is still somewhat limited understanding \ABC{} syntax, so
  that the user may need to change a bit the \ABC{} source to get the
  proper results. Nonetheless, \abcalias{} can be very useful if used
  with care. See inside the \mbox{\texttt{tools/}} folder.}
\footnote{See also the footnote \ref{footchord} at page
  \pageref{footchord}.}

Another approach is to map every \MIDI{} pitch to a given frequency.
For \MIDI{} devices with such capability, one can have available up to
128 different frequencies. There is not the problem with simultaneous
notes in a same channel. That can be fine in several cases, specially
when the scale has not too many degrees in an octave, for instance:
19-EDO or 24-EDO.\footnote{``EDO'' stands for ``Equal Divisions of
  Octave''.} But with 31 degrees in an octave (e.g. 31-EDO), the range
is reduced to four octaves only ($128/31=4.129$). The frequency
mapping usually is device-specific.  However there is the Standard
\MIDI{} Tuning specification, which set the frequencies by using
System Exclusive messages (those messages can be inserted in a \MIDI{}
file).  Standard \MIDI{} Tuning is not supported by some \MIDI{}
devices, thus it is not recommended to use in \MIDI{} files for
distribution.  An alternative is to use the program \scala{} to retune
files which assume a frequency mapping, converting them to files which
use Pitch Bend messages instead.

One should also know that 14bit \MIDI{} Pitch Bend gives a precision
of $1/4096$ semitone. This corresponds to $0.024414$ cents.

Such \MIDI{} limitations force users of \ABC{} programs to choose
between those two main approaches to obtain micro-tuned \MIDI{} files.
\microabc{} provides the \emph{chromatic} and \emph{diatonic} modes
for frequency mapping (\ABC{} with conventional accidentals or with no
accidentals respectively), and the \emph{microtonal} mode to use pitch
bend messages (\ABC{} with microtonal accidentals).


\section{The steps}

\paragraph{With \abcpp{} ---}

These are the traditional steps to write microtonal music with
\microabc{}:

\begin{enumerate}
\item Define the scale in a \microabc{} text file;
\item Generate the file(s) containing the macros definitions, by
  running \microabc{};
\item Write the music in \ABC{} code with macros;
\item Concatenate or include the macros definitions file(s) with the \ABC{}
   code and generate pure \ABC{} file(s), by running \abcpp{};
 \item Run \abcps{} to get the score as a \PS{} file and/or run
   \abcmidi{} to get a \MIDI{} file.
\end{enumerate}

\paragraph{Without \abcpp{} ---}

To use \microabc{} as preprocessor, the steps are:
 
\begin{enumerate}
\item Define the scale in a \microabc{} text file;
\item Write the music in \ABC{} code with macros;
\item Preprocess the music file with \microabc{} to obtain \ABC{}
  file(s) for \MIDI{} and/or \PS{};
\item Run \abcps{} to get the score as a \PS{} file and/or run
   \abcmidi{} to get a \MIDI{} file.
\end{enumerate}

\paragraph{Sagittal ---}

To use \microabc{} as a preprocessor for Sagittal notation, the steps
are simply these:

\begin{enumerate}
\item Write the music in \ABC{} code with Sagittal pitches (between
  square braces);
\item Preprocess the music file with \microabc{} to obtain \ABC{}
  file(s) for \MIDI{} and/or \PS{};
\item Run \abcps{} to get the \PS{} score file and/or run \abcmidi{}
  to get a \MIDI{} file.
\end{enumerate}

%%%%%%% \verbatiminput{tut.sh}

\section{Examples}

\subsection{Quick start}

Just start doing. This example requires only these programs:

\begin{itemize}
\item \microabc{};
\item \abcps{};
\item \abcmidi{};
\item Any \MIDI{} player;
\item Any \PS{} viewer.
\end{itemize}

\subsubsection{Bach's choral}

Here is the sample music, from a J.~S.~Bach's choral:

%%%%%%%%%%%
\abcinput{bach}
%%%%%%%%%%%

And here is its corresponding code, written as \ABC{} with Sagittal
macros:

\begin{verbatim}
%%format sagittal.fmt
%%format sagittal-mixed.fmt
%%postscript sagmixed
%%continueall
%%maxshrink .8

%%microabc: equaltemp: 19

X:1
T:microabc tutorial
T:Nun lob', mein Seel', den Herren
C:J.S.Bach
L:1/4
M:3/4
K:A exp [F#`][C#`][G#`]   % key signature
%
%%staves {(1 2) (3 4)}
%
V:1 clef=treble % Voice 1
%%MIDI nobeataccents
%%MIDI program 16
%%MIDI trim 1/5
    |: [A] | [A]2 [:G#] | [:F#]2 [E] | [A] [B]2 | [:C#`]2 \
    [:C#`] | [:C#`] [B] [:C#`] | [:C#`]2 [B] | [A] [B]2 | [A]2 :|
V:2 clef=treble % Voice 2
%%MIDI nobeataccents
%%MIDI program 16
%%MIDI trim 1/5
    |: [E] | [:F#]2 [E] | [D][:C#][B,] | [E][:F#][E] | [E]2 \
    [E]/[:F#]/ | [:G#]2 [E#] | [:F#]2 [:G#] | [A]2 [:G#] | [E]2 :|
V:3 clef=bass % Voice 3
%%MIDI nobeataccents
%%MIDI program 16
%%MIDI trim 1/5
    |: [:C#] | [:C#]2 [:C#] | [A,]2 [:G#,] | [A,]2 [:G#,] | [A,]2 \
    [:C#] | [:C#]2 [B,] | [A,]2 [E] | [E] [:F#] [E] | [:C#]2 :|
V:4 clef=bass % Voice 4
%%MIDI nobeataccents
%%MIDI program 16
%%MIDI trim 1/5
    |: [A,] | [:F#,]2 [:C#,] | [D,]2 [D,] | [:C#,] [D,] [E,] | [A,,]2 \
    [A,] | [E#,]2 [:C#,] | [:F#,] [Ee,] [D,] | [:C#,] [D,] [E,] | [A,,]2 :|
\end{verbatim}

The code above (saved as \code{bach.abp}) can be converted to \PS{}
and \MIDI{} with the commands:

\begin{verbatim}
microabc -E -Pbach.abp -obach.abc
microabc -E -Mbach.abp -obach-midi.abc
abcm2ps -O= bach.abc
abc2midi bach-midi.abc
\end{verbatim}

Use the \PS{} viewer and the \MIDI{} player to enjoy the results.

Then start to make changes in the code to learn more\ldots

\subsubsection{Make changes, learn more}

The \MIDI{} file of the Bach's choral was generated in 19-EDO. Note
the line with \verb$%%microabc: equaltemp: 19$.
You may make experiments with various equal temperaments, by replacing
\code{19} with other numbers. Or else disable that command to get
fifths of $3/2$ (Pythagorean just intonation) -- to do this, simply
remove one character \verb$%$ of the start of that line.

You may also get a score in pure Sagittal notation, just removing the
line \verb$%%postscript sagmixed$ or changing \code{sagmixed} to
\code{sagpure}.

Take some time trying to understand the code. Focus the attention on
the lines of notes.  Notice that the accidentals are not shown in the
score for pitches starting with a colon, like in \verb$[:C#]$. Also
notice that a $\natural$ is represented with a small letter
``\code{e}'', in \code{[Ee,]}. Experiment to change the code and see
the effects of your changes.

As an additional exercise, if you know a bit of Sagittal, use
Pythagorean tuning (fifths of $3/2$) and then change some accidentals
to get pure thirds in the chords.

To learn more about how to use Sagittal with \microabc{}, read the
section \ref{sec:sagittal} (page \pageref{sec:sagittal}). See also the
section \ref{sec:sagittal2} (page \pageref{sec:sagittal2}), and the
\microabc{} documentation. To learn more about the Sagittal Notation
System itself, visit
\url{http://users.bigpond.net.au/d.keenan/sagittal/}.

The following sections illustrate in some detail the main features of
\microabc{}.

\subsection{A scale of harmonics --  \microabc{} output modes}

As an example to illustrate the \microabc{} \emph{microtonal},
\emph{chromatic}, \emph{diatonic} and \emph{literal} modes, we will
take the first odd elements of the harmonic series up to 23rd
harmonic, reduced to the range of an octave. That scale can be
obtained by executing the following commands in the program \scala{}:

\begin{verbatim}
harm 1 23
norm
show
\end{verbatim}

Here is the resulting scale:

\begin{verbatim}
  0:          1/1               0.000 unison, perfect prime
  1:         17/16            104.955 17th harmonic
  2:          9/8             203.910 major whole tone
  3:         19/16            297.513 19th harmonic
  4:          5/4             386.314 major third
  5:         21/16            470.781 narrow fourth
  6:         11/8             551.318 undecimal semi-augmented fourth
  7:         23/16            628.274 23rd harmonic
  8:          3/2             701.955 perfect fifth
  9:         13/8             840.528 tridecimal neutral sixth
 10:          7/4             968.826 harmonic seventh
 11:         15/8            1088.269 classic major seventh
 12:          2/1            1200.000 octave
\end{verbatim}

\subsubsection{\label{inputfile}The \microabc{} input file}

We will make the input file for \microabc{} by adding these commands
above the scale data generated by \scala{}:

\begin{verbatim}
alias:0     {column 0 gives the aliases}
scl:1       {column 1 gives the intervals of the scale for microtonal mode}
range:-40 40 {pitch range (ambitus)}
\end{verbatim}

Then, we edit the output of \scala{} accordingly: we will use the
numbers 0--11 as aliases (without the colons of the \scala{} output),
and we will remove the last line (octave, 2/1, which is the pitch
class 0 again, octave up).\footnote{Unlike \scala{} files, the input
  format for \microabc{} starts with pitch 1/1 and ends with the last
  pitch \emph{before} the octave (or other equivalence interval). To
  use a different equivalence interval, insert a
  \texttt{sclmod:<interval>} line.} Let us save this as
\texttt{harmonic.txt}:

\begin{verbatim}
{----------begin----------}
alias:0     {column 0 gives the aliases}
scl:1       {column 1 gives the intervals of the scale for microtonal mode}
range:-40 40 {pitch range (ambitus)}
  0           1/1              0.000 unison, perfect prime
  1          17/16           104.955 17th harmonic
  2           9/8            203.910 major whole tone
  3          19/16           297.513 19th harmonic
  4           5/4            386.314 major third
  5          21/16           470.781 narrow fourth
  6          11/8            551.318 undecimal semi-augmented fourth
  7          23/16           628.274 23rd harmonic
  8           3/2            701.955 perfect fifth
  9          13/8            840.528 tridecimal neutral sixth
 10           7/4            968.826 harmonic seventh
 11          15/8           1088.269 classic major seventh
{-----------end-----------}
\end{verbatim}

\subsubsection{The \ABC{} file with macros}

To try with our example, let us write a music file. Remember, the
pitches are defined as the numbers 0--11 delimited by square braces
(provided by \microabc{}); octaves up or down are represented like in
\ABC{}, with apostrophes or commas.\footnote{The delimiters can be
  changed with the command \texttt{delim:}, and the octave modifiers
  with the command \texttt{updown:}.} Let us save this as
\texttt{harmonic.abp}.

\begin{verbatim}
X:1
T:microabc tutorial
T:harmonics
M:6/8
L:1/8
Q:1/8=90
V:1
%%MIDI program 16
V:2
%%MIDI program 16
K:none
%%continueall
%%maxshrink 0.9
V:1
[0'][1'][2'][3'][4'][5'] | [6'][7'][8'][9'][10'][11'] |
[0][1][2][3][4][5] | [6][7][8][9][10][11] |
[0,][1,][2,][3,][4,][5,] | [6,][7,][8,][9,][10,][11,] |]
V:2
[0,,]6- | [0,,]6 |
[0,,]6- | [0,,]6 |
[0,,]6- | [0,,]6 |]
%
\end{verbatim}

\subsubsection{\emph{Microtonal} mode}

The command \texttt{scl:1} included in the input file (section
\ref{inputfile}, page \pageref{inputfile}) is sufficient to activate
the microtonal mode. To generate the macro definitions for \MIDI{}
files, execute:

\begin{verbatim}
microabc < harmonic.txt > harm4mid.abh
\end{verbatim}

You may be interested in to see inside the generated file
\texttt{harm4mid.abh}, to know the definitions. It will contain lines
like these, where you can see microtonal \ABC{} pitches in the
resolution of 1/4096 semitone:

\begin{verbatim}
#define [9,] _2436/4096A,
#define [10,] ^2819/4096A,
#define [11,] _481/4096B,
#define [0] =C
#define [1] _3893/4096D
#define [2] ^160/4096D
#define [3] ^3994/4096D
#define [4] _561/4096E
#define [5] _1197/4096F
#define [6] ^2102/4096F
#define [7] _2938/4096G
#define [8] ^80/4096G
#define [9] _2436/4096A
#define [10] ^2819/4096A
#define [11] _481/4096B
#define [0'] =c
#define [1'] _3893/4096d
\end{verbatim}

Let us create the \ABC{} code and the \MIDI{}
file:\footnote{DOS/Windows users should use \texttt{type} instead of
  \texttt{cat} in the command line.}

\begin{verbatim}
cat harm4mid.abh harmonic.abp | abcpp > harm4mid.abc
abc2midi harm4mid.abc
\end{verbatim}

To get a score in microtonal mode, we want quantise those accidentals
from 1/4096~semitone to a smaller denominator. \abcps{} supports
quarter-tones (1/2~semitone), but we may choose a finer resolution:
1/4~semitone, once \microabc{} can provide the required glyphs for the
accidentals.

The command below will create a file with the macros for our scale
quantised to eighth-tones (\texttt{harm4ps.abh}). Please note the
command-line options \texttt{den:4}, which sets the denominator to
1/4~semitone, \texttt{abcm2ps:4} which sets the same quantisation for
\abcps{}, and \texttt{psacc:1} which tells \microabc{} to create the
glyphs for the microtonal accidentals:

\begin{verbatim}
microabc den:4 abcm2ps:4 psacc:1 < harmonic.txt > harm4ps.abh
\end{verbatim}

These commands will create the \ABC{} code and the \PS{} score file
from it:

\begin{verbatim}
cat harm4ps.abh harmonic.abp | abcpp > harm4ps.abc
abcm2ps -O= harm4ps.abc
\end{verbatim}

The score should look like this:

%%%%%%%%%%%%%%%%%%
\abcinput{harm4ps}
%%%%%%%%%%%%%%%%%%

\subsubsection{\emph{Chromatic} mode, \timidity{}  and \scala{}}

It was said before (section \ref{sec:limit}, page \pageref{sec:limit})
that the microtonal mode is not suitable to obtain \MIDI{} files with
\abcmidi{} when chords are used. In such circumstances, a solution can
be using the chromatic mode and retune the \MIDI{} file with
\scala{}, or playing it with \timidity{}, or yet creating it with
Standard \MIDI{} Tuning messages.\footnote{Another solution can be
  using the program \abcalias{} (included in \microabc{} package) to
  expand the chords to temporary voices (voice overlay).}

The following commands will create the macro definitions in chromatic
mode, and then generate the \ABC{} and \MIDI{} files:

\begin{verbatim}
microabc chromatic:1 < harmonic.txt > harmchrm.abh
cat harmchrm.abh harmonic.abp | abcpp > harmchrm.abc
abc2midi harmchrm.abc
\end{verbatim}

The option \texttt{chromatic:1} in the command line will cancel the
effect of the \texttt{scl:1} command from the file
\texttt{harmonic.txt}, that is, the microtonal mode will be disabled
and the chromatic mode will be enabled. As a consequence, the tuning
information will be ignored -- but we need using that information to
retune or play the \MIDI{} file.

To play the file with \timidity{}, we need firstly export the scale in
a format suitable for that program. A frequency table will be output
to the file \texttt{harmonic.tbl} with the
command:\footnote{DOS/Windows users should exclude the part
  ``\texttt{>~/dev/null}'' from the commands; some data will be
  printed on the screen.} \footnote{Frequency tables for \timidity{}
  may be also created using \scala{}. For instance, by issuing this command:\\
  \mbox{\texttt{scala harmonic.scl --set synth 117 "--send/file
      \%scl(.tbl)" --exit}}}

\begin{verbatim}
microabc timidity:harmonic.tbl < harmonic.txt > /dev/null
\end{verbatim}

Now we can hear the \MIDI{} file with \timidity{}, using the option
\texttt{-Z} to load the frequencies file:\footnote{Playing the file
  with \timidity{}, using a frequency table, will result in a finer
  tuning, compared with other approaches.}

\begin{verbatim}
timidity harmchrm1.mid -Z harmonic.tbl
\end{verbatim}

Our alternative approach is retuning the \MIDI{} file. We can export
the tuning from the \microabc{} input, in the \scala{} file format:

\begin{verbatim}
microabc scala:harmonic.scl < harmonic.txt > /dev/null
\end{verbatim}

This command calls \scala{} to retune the \MIDI{} file -- supposed to
be named \texttt{harmchrm1.mid} -- as a new file called
\texttt{harm-scl.mid}:

\begin{verbatim}
scala harmonic.scl --example/midi harmchrm1.mid harm-scl.mid --exit
\end{verbatim}

Still using the \ABC{} code generated with the chromatic mode, we
could create a \MIDI{} file with Standard \MIDI{} Tuning messages.
This option is illustrated in the section \ref{sec:19edo} (page
\pageref{sec:19edo}).

\subsubsection{\emph{Diatonic} mode}

The diatonic mode is not necessary in the present example of scale of
harmonics.  Nonetheless, it will be used for the purpose of
illustration.

The following commands will generate a score using a diatonic mapping
of the pitches of our scale (the \microabc{} option
\texttt{diatonic:1} is to set the diatonic mode):

\begin{verbatim}
microabc diatonic:1 < harmonic.txt > harmdiat.abh
cat harmdiat.abh harmonic.abp | abcpp > harmdiat.abc
abcm2ps -O= harmdiat.abc
\end{verbatim}

The resultant score (below) uses only the natural pitches, without any
accidentals. The diatonic mode can be used to create non-conventional
staves. Note that, in this specific case in which there are 12 notes
per octave, every octave instance spans on 6 staff lines.\footnote{An
  additional observation is that -- as a coincidence -- the pitch
  class [0] lies in the same helper line in both treble and bass clefs
  (see the first note in the upper voice, at measures 3 and 5).} Such
property could be used to simulate a sort of ``keyboard-view'' like
those present in some \MIDI{} sequencer programs.

%%%%%%%%%%%%%%%%%%%
\abcinput{harmdiat}
%%%%%%%%%%%%%%%%%%%

\subsubsection{\emph{Literal} mode}

The remaining \microabc{} mode allows setting arbitrary replacement
strings for the aliases. We will not show, at this point, any useful
examples -- we will rather simply inspect which macro definitions are
generated when we use the second column of the input file (index 1:
that column with the intervals of the scale) as replacement
text.\footnote{DOS/Windows users should use \texttt{more} instead of
  \texttt{less} in the command line.}

\begin{verbatim}
microabc replace:1 < harmonic.txt | less
\end{verbatim}

The result printed on the screen should contain lines such as these
ones:

\begin{verbatim}
#define [9,] 13/8
#define [10,] 7/4
#define [11,] 15/8
#define [0] 1/1
#define [1] 17/16
#define [2] 9/8
#define [3] 19/16
#define [4] 5/4
#define [5] 21/16
#define [6] 11/8
#define [7] 23/16
#define [8] 3/2
#define [9] 13/8
#define [10] 7/4
#define [11] 15/8
#define [0'] 1/1
#define [1'] 17/16
\end{verbatim}

The \microabc{} literal mode has a few variants, used when the
replacement text is in a special format: \texttt{replaceabc:} and
\texttt{replacesagittal:}, respectively for \ABC{} and Sagittal
formats.\footnote{Sagittal format does not work with \abcpp{}; it will
  work only when using \microabc{} as preprocessor. See section
  \ref{sec:sagittal} at page \pageref{sec:sagittal}.}

Also, there is the option \texttt{replaceupdn:} to insert
``octave'' modifiers (like \texttt{'} and \texttt{,} in \ABC{}) in the
replacements. In the example above, the replacement text does not
contain such modifiers: any instance of pitch class [0] is replaced
with 1/1, any instance of pitch class [11] is replaced with 15/8 and
so on.

\subsection{\label{sec:19edo}An example in 19-EDO}

Let us suppose we want to write a music in 19 equal divisions of
octave. The score can be accomplished using the conventional
accidentals flat, natural and sharp, but we need tune the pitches for
\MIDI{} files. Of course, we want to write only one \ABC{} input
code to obtain both \PS{} and \MIDI{} outputs.

\subsubsection{The \microabc{} file}

A solution is to use macros for each pitch instead of simple \ABC{}
pitches. The replacement for each macro should be different, depending
on output format: one for \PS{} generation, another for \MIDI{}
generation. By default, the \microabc{} macros are delimited by square
braces \texttt{[}~and~\texttt{]}.

\subsubsection{\PS} 

For \PS{}, we want ``common'' pitches and accidentals. Therefore:
\noindent{}\code{C} can be represented as the macro \code{[C]};
\code{\^{}C} as \code{[\^{}C]}; \code{\_D} as \code{[\_D]}; and so on,
that is: all macro names are the corresponding \ABC{} pitch names between
square braces.

\subsubsection{\MIDI}

For \MIDI{}, the things are not so simple, because normally we have 12
chromatic pitches per octave, but our scale has 19. The frequencies
for all pitches need to be set, to get a tuned \MIDI{} file. Let us
use \abcmidi{}'s \code{\%\%MIDI snt} command for Standard \MIDI{}
Tuning.\footnote{\label{runscala}Standard MIDI Tuning is not
  implemented in several MIDI devices, but it is supported by the
  program \timidity{}.  If you are creating MIDI files for
  distribution, you may prefer retune them with \scala{} using Pitch
  Bend messages, which are more portable.  The \microabc{} command
  \texttt{scala:} allows you to export a *.scl file. To retune a MIDI
  file with \scala{}, issue a
  command like this:\\
  \texttt{scala scalefile.scl --example/midi inputfile.mid
    outputfile.mid --exit}}

\subsubsection{The code}

Below is the basic \microabc{} code for our scale, \texttt{tut.txt}.
It sets a scale with 19 steps of size, which is an equal temperament
defined by 19 divisions of a octave (2/1). The pitch names are like
\ABC{} pitch names, listed at columns 0 and 1. Enharmonic pitches share a
same line in the following list, and here they are considered as
synonyms (``aliases'').

%\scriptsize
\small
\begin{verbatim}
{----------begin----------}
size:19
equaltemp: 19 2/1
aliasabc: 0 1
range:-20 20
{}
=C C
^C __D
_D ^^C
=D D
^D __E
_E ^^D
=E E
^E _F
=F F
^F __G
_G ^^F
=G G
^G __A
_A ^^G
=A A
^A __B
_B ^^A
=B B
^B _c
{}
{-----------end-----------}
\end{verbatim}
\normalsize

\subsubsection{Macro definitions files}

In \microabc{}, macros can have several aliases (synonyms), but only
one meaning, that is, only one replacement. To maintain a strict
correspondence between macros and pitches for a \PS{} score
(enharmonic pitches should be differentiated in a score), \microabc{}
needs to be ran twice, and the outputs concatenated. The first run
sets the macro definitions for the first (indexed by 0) column of the
input file; the second run sets the macros for the enharmonic pitches
(second column of input). In this example, the replacement is one of
the list columns, taken as an \ABC{} pitch.

The command \code{cat} concatenates the files into
\texttt{tut-ps.abh} (\texttt{MS-DOS} users should use \code{type}
instead).

\small
\begin{verbatim}
microabc -itut.txt aliasabc:0 replaceabc:0 -otut-ps.ab1
microabc -itut.txt aliasabc:1 replaceabc:1 -otut-ps.ab2
cat tut-ps.ab1 tut-ps.ab2 > tut-ps.abh
\end{verbatim}
\normalsize

The macros for \MIDI{} are easier to obtain, because both input
columns 0 and 1 mean a same pitch (enharmonic differentiation is
irrelevant here).  Our \microabc{} input file already has selected
both columns with \code{aliasabc:~0~1} (above overridden for \PS{}
score). The additional command option \code{snt:} generates the file
\texttt{tut.snt} for Standard \MIDI{} Tuning.

\small
\begin{verbatim}
microabc -itut.txt -otut-mid.abh snt:tut.snt
\end{verbatim}
\normalsize

\subsubsection{The \ABC{} file with macros}

The next step is to write the music in \ABC{} notation with macros,
stored in the file \texttt{tut.abp}. Remember that all pitches must be
between square braces (they are macro names, and \microabc{} macro
names are delimited by square braces), and note the \code{\#include}
command to insert the Standard \MIDI{} Tuning definitions from the
file \texttt{tut.snt}.\footnote{If you want to
  use \scala{} to retune the MIDI file, create a *.scl file with:\\
  \texttt{microabc -itut.txt scala:tut.scl}\\
  Then, remove the line\\
  \texttt{\#include "tut.snt"}\\
  of the sample source given in this section and follow the
  instructions in the footnote number \ref{runscala} (page
  \pageref{runscala}) to retune the MIDI file according to the scale
  file \texttt{tut.scl}.}  Here is our scale:

\small
\begin{verbatim}
X:1
T:microabc tutorial
T:19-edo
#include "tut.snt"
M:6/8
L:1/8
K:C
[C][^C][_D] [=D][^D][_E] |\
[=E]2 z [E][^E][F] |\
[^F][_G][=G] [^G][_A][=A] |\
[^A][_B][=B] [^B]3 | [c]3 z3 |]
\end{verbatim}
\normalsize

\subsubsection{\label{preprocess}Preprocessing}

The \ABC{} code with macros (\texttt{tut.abp}) needs to be
preprocessed and converted to pure \ABC{} code.

\ABC{} file for \PS{} score generation:
\small
\begin{verbatim}
cat tut-ps.abh tut.abp | abcpp > tut-ps.abc
\end{verbatim}
\normalsize

\ABC{} file for \MIDI{} file generation:
\small
\begin{verbatim}
cat tut-mid.abh tut.abp | abcpp > tut-mid.abc
\end{verbatim}
\normalsize

\subsubsection{Getting the \MIDI{} file}

The \MIDI{} simulation is generated by \abcmidi{}, with the following
command:

\small
\begin{verbatim}
abc2midi tut-mid.abc -o tut.mid
\end{verbatim}
\normalsize

The synthesizer \timidity{} can play the \MIDI{} file and
convert it to other formats like \texttt{.wav} or \texttt{.ogg}.

\subsubsection{\label{getps}Getting the \PS{} score file}
 
Use \abcps{} to convert the \ABC{} code into a graphical \PS{} score:

\small
\begin{verbatim}
abcm2ps tut-ps.abc -O tut.ps
\end{verbatim}
\normalsize

The output can be previewed with \textbf{ghostview}, and then printed
or converted to \texttt{PDF} or other formats.

\subsubsection{Customisation of the accidentals in the \PS{} score file}

Just to show another interesting feature of \abcps{} -- the insertion
of \PS{} instructions to (re)define symbols, let us customise the
score glyphs for the accidentals sharp and flat.  Put this code in
the original \ABC{} file (\texttt{tut.abp}), before the music, then
follow again the steps of the sections \ref{preprocess} and
\ref{getps}:

\small
\begin{verbatim}
%%postscript /sh0{ gsave exch .45 add exch T .85 SLW
%%postscript    -1.2 -8.4 M 0 15.4 RL
%%postscript    1.4 -7.2 M 0 15.4 RL stroke
%%postscript    -1 0 translate .9 1 scale
%%postscript    -2.6 -3 M 5.4 1.6 RL 0 -2.2 RL -5.4 -1.6 RL 0 2.2 RL fill
%%postscript    -2.6 3.4 M 5.4 1.6 RL 0 -2.2 RL -5.4 -1.6 RL 0 2.2 RL fill
%%postscript    grestore}!
%%postscript /ft0{ gsave T .95 SLW
%%postscript    -1.8 2.5 M
%%postscript    6.4 3.3 6.5 -3.6 0 -6.6 RC
%%postscript    4.6 3.9 4.5 7.6 0 5.7 RC
%%postscript    currentpoint fill M
%%postscript    0 7.1 RM 0 -7.1 RL stroke
%%postscript grestore}!
\end{verbatim}
\normalsize

Here is the resulting score:

%%%%%%%%%%%%%%
\abcinput{tut-ps}
%%%%%%%%%%%%%%

\subsection{\label{sec:sagittal}Sagittal notation -- using \microabc{} as preprocessor}

\microabc{} can do a specialised form of preprocessing. Unlike
\abcpp{}, macro definitions are not declared with \texttt{\#define}
statements. The definitions are based on the \microabc{} input file
itself (option \texttt{-i}), which defines the working mode, the
scale, the aliases and other options -- or the definitions are
built-in, in the case of using the Sagittal microtonal notation. To
omit the input file, use the option \texttt{-i-}.

The command line options \texttt{-p}, \texttt{-M} and \texttt{-P}
preprocess the file given as argument. The option \texttt{-S} enables
the support for Sagittal notation.

\subsubsection{Just Intonation}

You find below the sample music file \texttt{sagit.abp}. It uses the
format file \texttt{sagittal-pfb.fmt}, which is included in
\microabc{} package.\footnote{\abcps{} expects that the format file be
  stored in the current directory or in the ``default format
  directory'' which you can know by issuing \texttt{abcm2ps~-V}. The
  directory for format files can also be indicated with the \abcps{}
  option \texttt{-D}. For details, please consult the \abcps{}
  documentation.} \footnote{The use of \texttt{sagittal-pfb.fmt}
  assumes that the Sagittal \PS{} Type 1 font is installed in your
  system. You can alternatively try with \texttt{sagittal.fmt} which
  embeds the font in the output \PS{} file, or yet, use the flag
  \texttt{-e} when running \microabc{}.} Note that the octaves are
indicated with \texttt{,} (down) and \texttt{`} (up) -- the latest is
a grave accent, not the apostrophe (\texttt{'}) used in \ABC{}.

\begin{verbatim}
%%format sagittal-pfb.fmt
%%stretchlast

X:1
T:microabc tutorial
T:Sagittal preprocessing
K:C
%%text Pure intonation (fifth=2:3, octave=1:2)
V:1
[C][E\!] [G][B!!!)] [D`][F/|\`] [A(!/`][B\!`] |\
[C``][B\!`] [A(!/`][F/|\`] [D`][B!!!)] [G][E\!] | [C]4 z4 |]
V:2
[C,]8 | [C]8 | [C,]4 z4 |]
\end{verbatim}

To get a \MIDI{} file, preprocess with the option
\texttt{-M}:\footnote{The \MIDI{} file will be generated in microtonal
  mode, that is, using \MIDI{} Pitch Bend messages. It has the
  limitation of do not support chords. Splitting the chords into
  multiple voices can be made with \abcalias{}. You may alternatively
  use a special command for \abcmidi{} (see note \ref{footchord} at
  page \pageref{footchord}).}

\begin{verbatim}
microabc -i- -S -Msagit.abp > sagit-mid.abc
abc2midi sagit-mid.abc
\end{verbatim}

And to get a \PS{} score, use the option \texttt{-P}:\footnote{If you
  do not want to use \abcps{} format files, call \microabc{} with the
  flag \texttt{-e}:\\
  \mbox{\texttt{microabc -i- -S -e -Psagit.abp > sagit.abc}}}

\begin{verbatim}
microabc -i- -S -Psagit.abp > sagit.abc
abcm2ps -O= sagit.abc
\end{verbatim}

The score will look like this:

%%%%%%%%%%%%%%%%
\abcinput{sagit}
%%%%%%%%%%%%%%%%

\subsubsection{Equal divisions of octave}

The conversion of Sagittal pitches for \MIDI{} is, by default, done in
just intonation, based on pythagorean nominals -- with fifths of 2:3
and octaves of 1:2.

Equal divisions of octave can be set with the \microabc{} command
\texttt{equaltemp:}, which can be given in an input file, from the
command line or even from the music source file (\texttt{.abp}), in
this format:

\begin{verbatim}
%%microabc: equaltemp:24
\end{verbatim}

\begin{verbatim}
%%format sagittal-pfb.fmt
%%stretchlast
%%continueall

X:1
T:microabc tutorial
T:equal divisions of octave
M:none
L:1/2
%%MIDI program 16
%%MIDI trim 1/4
K:C
%%microabc: equaltemp:24
"^24-EDO"\
[Ce][C^][C/N\][D\U/][Dv][De] z
%%microabc: equaltemp:31
"^31-EDO"\
[Ce][C^][C/N\][D\U/][Dv][De] |
\end{verbatim}

Just like in the previous example, these commands will convert the
file \mbox{\texttt{edo.abp}} into \mbox{\texttt{edo-midi.abc}} (for
\abcmidi{}) and \mbox{\texttt{edo.abc}} (for \abcps{}):

\begin{verbatim}
microabc -i- -S -Medo.abp > edo-midi.abc
microabc -i- -S -Pedo.abp > edo.abc
\end{verbatim}

The score and the \MIDI{} file are obtained with:

\begin{verbatim}
abcm2ps -O= edo.abc
abc2midi edo-midi.abc -o edo.mid
\end{verbatim}

%%%%%%%%%%%%%%
\abcinput{edo}
%%%%%%%%%%%%%%

This example \mbox{(\texttt{edo.abp})} uses the ``same'' pitches in
two different tunings: 24-EDO and 31-EDO. The difference is noticeable
in the \MIDI{} file: \verb'C/N\' and \verb'D\U/' are equivalent in
24-EDO, but not in 31-EDO.

\subsection{\label{sec:sagittal2}Using Sagittal notation for arbitrary scales}

This is an example which may be used as reference for many
applications. It uses \scala{} to aid with Sagittal notation. The
\MIDI{} file is created in \emph{chromatic} mode, and then retuned
with \scala{}. As the scale size is small, there is no a ``range
\emph{versus} chord'' conflict.\footnote{See section \ref{sec:limit},
  page \pageref{sec:limit}.}

\subsubsection{Pick out a scale --- make the \microabc{} input file}

Start the program \scala{} and create or load a scale. For instance,
click the button \texttt{Open}, select the file
\mbox{\texttt{barlow\_17.scl}} and then click on \texttt{OK}.

Now, we need to name the pitches. Let us use a Sagittal notation for
just intonation, with short mixed names. Execute these commands in the
\scala{} prompt (the bottom line of the interface):

\begin{verbatim}
set notation saji1
set sagittal short mixed
show
\end{verbatim}

The result is shown below. Save these lines in a text
file.\footnote{Tip: To copy the text, do click with the right button
  of the mouse on the text window of \scala{} and select the option
  \mbox{\texttt{Edit with $@$edit\ldots}}}

\begin{verbatim}
  0:          1/1           C     B#\ unison, perfect prime
  1:         25/24          Db\   C#_ classic chromatic semitone, minor chroma
  2:         27/25          C#/   Db= large limma, BP small semitone
  3:          9/8           D         major whole tone
  4:         32/27          Eb    D#\ Pythagorean minor third
  5:         11/9           Eo    D#f undecimal neutral third
  6:         32/25          E/    Fb= classic diminished fourth
  7:          4/3           F     E#\ perfect fourth
  8:         25/18          Gb\   F#_ classic augmented fourth
  9:         36/25          F#/   Gb= classic diminished fifth
 10:          3/2           G         perfect fifth
 11:         25/16          Ab\   G#_ classic augmented fifth
 12:         18/11          Av    G#q undecimal neutral sixth
 13:         27/16          A         Pythagorean major sixth
 14:         16/9           Bb    A#\ Pythagorean minor seventh
 15:         50/27          B_    Cb\ grave major seventh
 16:         48/25          B/    Cb= classic diminished octave
 17:          2/1           C     B#\ octave
\end{verbatim}

We need editing the file to adapt it for \microabc{}.

First, delete the last line. It is just the pitch 0 an octave
higher.\footnote{The equivalence interval (formal octave) is defined,
  in \microabc{} with the instruction \texttt{sclmod:<interval>}.}

Note the presence of equivalent pitches, like \texttt{C} and
\verb'B#\'. There are a few pitches with no equivalents: \texttt{D},
\texttt{G} and \texttt{A/}. For such pitches, fill the fourth column
with a dot (\verb$.$).\footnote{For certain scales, \scala{} shows
  some intervals in cents, adding the word ``cents''. A similar
  procedure may be then necessary in order to assure the
  correspondence of columns for \microabc{}.}

Note yet that the pairs of equivalents \{\texttt{C}~\verb'B#\'\},
\{\verb'B_'~\verb'Cb\'\} and \{\verb'B/'~\verb'Cb='\} do not specify
the different octaves.  Add a comma (\verb$,$) to \verb'B#\' to make
clear that the \verb'B#\,' is of the lower octave. Then add a grave
accent (\verb$`$) to \verb'Cb/' and \verb'Cb=' to indicate the higher
octave: \verb$Cb/`$ \verb'Cb=`'.

The next step is to tell \microabc{} how to interpret the data. Insert
these instructions above the scale data:

\begin{verbatim}
scl:1
aliassagittal:2 3
chromatic:1
\end{verbatim}

``\mbox{\texttt{scl:1}}'' means that the column 1 (start counting by
zero) contains the tuning.

``\mbox{\texttt{aliassagittal:2 3}}'' tells \microabc{} that the
columns 2 and 3 contains the pitch names in Sagittal.

``\mbox{\texttt{chromatic:1}}'' selects the \emph{chromatic} mode. Its
effect is that, when generating the \MIDI{} file, the pitches will be
mapped to the chromatic scale (rather than be tuned with pitchbends).
The \MIDI{} file will be retuned later with \scala{}.

Save the file as \mbox{\texttt{blw17.txt}}. Here are its contents:

\begin{verbatim}
scl:1
aliassagittal:2 3
chromatic:1
  0:          1/1           C     B#\, unison, perfect prime
  1:         25/24          Db\   C#_ classic chromatic semitone, minor chroma
  2:         27/25          C#/   Db= large limma, BP small semitone
  3:          9/8           D     .    major whole tone
  4:         32/27          Eb    D#\ Pythagorean minor third
  5:         11/9           Eo    D#f undecimal neutral third
  6:         32/25          E/    Fb= classic diminished fourth
  7:          4/3           F     E#\ perfect fourth
  8:         25/18          Gb\   F#_ classic augmented fourth
  9:         36/25          F#/   Gb= classic diminished fifth
 10:          3/2           G     .    perfect fifth
 11:         25/16          Ab\   G#_ classic augmented fifth
 12:         18/11          Av    G#q undecimal neutral sixth
 13:         27/16          A     .    Pythagorean major sixth
 14:         16/9           Bb    A#\ Pythagorean minor seventh
 15:         50/27          B_    Cb\` grave major seventh
 16:         48/25          B/    Cb=` classic diminished octave
\end{verbatim}

\subsubsection{The \microabc{} test file}

We want to see and to listen to the Barlow's 11-limit rational
17-equal, Barlow, On the Quantification of Harmony and Metre scale, to
test and check our \microabc{} input file.

Let \microabc{} create a test file \mbox{\texttt{blw.abp}}:

\begin{verbatim}
microabc -tblw.abp < blw17.txt
\end{verbatim}

Now, preprocess the test file. One command generates \ABC{} code for
\abcmidi{}.  The other command generates \ABC{} code for \abcps{}
(without using \mbox{\texttt{blw17.txt}}).

\begin{verbatim}
microabc -Mblw.abp < blw17.txt > blw-midi.abc
microabc -i- -S -Pblw.abp > blw.abc
\end{verbatim}

Now, let us convert the \ABC{} files to \MIDI{} and \PS{}. Put a copy
of the file
\mbox{\texttt{sagittal.fmt}}\footnote{\mbox{\texttt{sagittal.fmt}} is
  included in the \microabc{} package. It is used by \abcps{} to
  provide the Sagittal font. If you prefer do not deal with format
  files, add the flag \texttt{-e} to the \microabc{} command line in
  the previous step:\\
  \mbox{\texttt{microabc -i- -S -e -Pblw.abp > blw.abc}} } in the
same directory where the \ABC{} files are, and execute:

\begin{verbatim}
abc2midi blw-midi.abc
abcm2ps blw.abc -O=
\end{verbatim}

Recall that the \MIDI{} file was not generated in the Barlow's scale,
but in chromatic mapping.  To tune it, load the scale file
\mbox{\texttt{barlow\_17.scl}} into \scala{} and access the menu
\texttt{Tools} $|$ \mbox{\texttt{Retune MIDI-file\ldots}}, then select
the input file \mbox{\texttt{blw-midi1.mid}} and choose the output
file name \mbox{\texttt{blw.mid}}. Finally, click the \texttt{OK}
button.  Running \scala{} with this command line does the same:

\begin{verbatim}
scala barlow_17.scl --example/midi blw-midi1.mid blw.mid --exit
\end{verbatim}

Check the resulting \PS{} and \MIDI{} files. You may find the \MIDI{}
file just boring, but the \PS{} file contains information of interest,
for example: the score covers the complete range (\emph{ambitus})
available.

Now, let us generate a test file just covering just one octave, and
without the equivalent pitches. Modify the file \verb'blw17.txt'
according to this:

\begin{enumerate}
\item Change ``\verb$aliassagittal:2 3$'' to
  ``\verb$aliassagittal:2$''; this will omit the equivalent pitches.
\item Add a line with ``\verb$range:0 17$''; this will limit the range
  to the central octave.
\end{enumerate}

The first four lines of \verb'blw17.txt' will now be:

\begin{verbatim}
scl:1
aliassagittal:2
range:0 17
chromatic:1
\end{verbatim}

Redo the process of generation of the test file and its conversion to
\PS{} and \MIDI{} files:\footnote{You may want issue the third command as:\\
  \mbox{\texttt{microabc -i- -S -e -Pblw.abp > blw.abc}}}

\begin{verbatim}
microabc -tblw.abp < blw17.txt
microabc -Mblw.abp < blw17.txt > blw-midi.abc
microabc -i- -S -Pblw.abp > blw.abc
abc2midi blw-midi.abc
abcm2ps blw.abc -O=
scala barlow_17.scl --example/midi blw-midi1.mid blw.mid --exit
\end{verbatim}

The example below uses ``\verb$aliassagittal:2 3$'' to show the
equivalents:

\begin{center}
\begin{minipage}{12cm}
%%%%%%%%%%%%%%%%%%
\abcinput{blw}
%%%%%%%%%%%%%%%%%%
\end{minipage}
\end{center}

\subsubsection{Create your own \mbox{\texttt{*.abp}} music file}

If the testings with the test file succedded, we are ready to write
some music.\footnote{Be sure to remove the ``\code{range:}''
  limitation of the file \code{blw17.txt}!}

\scala{} will help us to write a scale. Issue \code{show/notation}
in the command prompt (or press \code{F7}), then copy the pitches:

\begin{verbatim}
C Db\ C#/ D Eb Eo E/ F Gb\ F#/ G Ab\ Av A Bb B_ B/ C.1
\end{verbatim}

Note that \scala{} uses numbers to indicate the octaves. Replace the
last pitch \code{C.1} with \code{C`} as we are using characters
\code{`} and \code{,} as octave modifiers.\footnote{Although in this
  section we are using Sagittal pitch names, we are not preprocessing
  for \MIDI{} with the flag \code{-S}.  Hence, the Sagittal pitches
  from the \code{*.abp} files are not interpreted as such, but as
  ordinary macros: variants like \code{[Ce]} for \code{[C]}, or even
  \code{[:Ce,,]} for \code{[C,,]} will not work without the flag
  \code{-S}. However, do not use \code{-S} to generate \MIDI{} with
  arbitrary scales: \microabc{} would ignore the user-defined scale
  and interpret the Sagittal pitches in the default way. If you want
  to add variants, add more \code{sagittalalias:} columns to the
  \microabc{} input file. Be rigorous to use the pitch names exactly
  as defined.}  Then enclose all pitches between brackets \verb$[$ and
\verb$]$, and add an \ABC{} header. The example below includes also a
few chords:

\begin{verbatim}
%%format sagittal-pfb.fmt
%%format sagittal-mixed.fmt
%%postscript sagmixed

X:1
T:microabc tutorial
T:Barlow's 17-tone scale
M:none
K:C
[C] [Db\] [C#/] [D] [Eb] [Eo] [E/] [F] [Gb\]
[F#/] [G] [Ab\] [Av] [A] [Bb] [B_] [B/] [C`] ||
x4 \
[[Db\][Gb\][B/][Eo`][Ab\`]]8 \
[[C][F][Bb][Eo`][Ab\`]]8 \
[[Bb,][F][Db\`][Eb`][Av`]]8 |]
\end{verbatim}

Here is the resulting score:

\abcinput[options=-O=]{blw2}

%\subsubsection{Changing/adding pitch names}

\subsection{More possibilities}

There are many other interesting things to do with \microabc{} and
\ABC{} music tools. The reader is invited to read the documentation of
the programs, and to browse their sample files directories.

\section{HTTP addresses}

\noindent
``Making Music With \ABC{} Plus'' (Guido Gonzato):\\
\indent\url{http://abcplus.sourceforge.net/#ABCGuide}
\newline
``Sagittal -- A Microtonal Notation System'' (David Keenan \& George Secor):\\
\indent\url{http://users.bigpond.net.au/d.keenan/sagittal/}
\newline
\abcmidi{}: \url{http://ifdo.pugmarks.com/~seymour/runabc/top.html}
\newline
\abcps{} and \tclabc{}: \url{http://moinejf.free.fr}
\newline
\abcpp{}: \url{http://abcplus.sourceforge.net}
\newline
\textbf{ghostscript} and \textbf{ghostview}:
\url{http://www.cs.wisc.edu/~ghost}
\newline
\microabc{}:
\url{http://br.geocities.com/hfmlacerda/abc/microabc-about.html}
\newline
\scala{}: \url{http://www.xs4all.nl/~huygensf/scala}
\newline
\timidity{}: \url{http://timidity.sourceforge.net}

\end{document}



% \begin{verbatim}
% {----------begin----------}
% {-----------end-----------}
% \end{verbatim}
