\documentclass{article}

\usepackage{hyperref}
\usepackage{multicol}
\usepackage{listings}

\usepackage{ddphonism}

\title{The \textsf{ddphonism} package\footnote{This
		document corresponds to \textsf{ddphonism} v0.2, dated 2019/09/01.}}
\author{Celia Rubio Madrigal\footnote{Email: \href{mailto:celrubio@ucm.es}{\texttt{celrubio@ucm.es}}}}
\date{September 1, 2019}


\begin{document}
	
	\maketitle
	
	\begin{abstract}
		This is a music-related package focused on notation from the Twelve-Tone System, also called Dodecaphonism. It provides \LaTeX{} algorithms that produce typical dodecaphonic diagrams based off a musical series, or row sequence, of variable length.
		
		\begin{center}
			\textbf{Keywords}
		\end{center}
	
		\textit{twelve tone system, dodecaphonism, music, mathematics, matrix, row, series, permutation, diagram, clock diagram, notation, algorithm, schoenberg, contemporary music, 20th century}
	\end{abstract}

	\tableofcontents
	
	\section{Introduction}
	There are hundreds of music tools and software online which are able to produce different music notations. However, I have never seen a \LaTeX{} tool that can do the same. This package is not only about notation, but it also calculates mathematically how this notation should work.
	
	It is said that a twelve-tone matrix is the only thing a twelve-tone composer should need, because it provides the whole serial spectrum with which they may work. I wanted \LaTeX{} users to be able to generate them automatically.
	
	But I also think that a twelve-tone matrix is not enough, that there exist several other notations with which they may understand their series and their potential. These are the diagrams that can be obtained with this package:
	
	\begin{multicols}{2}
		\dmatrix{4,3,2,1,0}
		
		\ddihedral{4,5,7,1,6,3,8,2,11,0,9,10}
		
		\ddiagram[arrow shift = 4]{4,5,7,1,6,3,8,2,11,0,9,10}
		
		\darrows{4,5,7,1,6,3,8,2,11,0,9,10}
		
		\bigskip
		\drow{4,3,2,1,0}
	\end{multicols}
	
	\section{Using the \textsf{ddphonism} package}
	These are the commands provided by \textsf{ddphonism}. The main parameter in every command is the row sequence.
	
	\newcommand{\I}[1]{\item[\texttt{$\backslash$#1}]\quad}	
	\newcommand{\Ii}[1]{\item[\textsf{#1}]\quad}
	\begin{itemize}
		\I{dmatrix} produces a twelve-tone matrix of arbitrary length, as shown in \href{https:matrices.netlify.com}{this website}. For example, \verb|\dmatrix{0,2,1,4,3,6,5}| produces the matrix \dmatrix{0,2,1,4,3,6,5}

		\begin{itemize}
			\Ii{sep} scales the matrix.
			\Ii {vsep} scales the matrix vertically.
			\Ii {hsep} scales the matrix horizontally.
			\Ii{lines} draws lines between rows and columns.
			\Ii{outside lines} only draws the outside lines.
			\Ii{inside lines} only draws the inside lines.
			\Ii{vlines} only draws the vertical lines.
			\Ii{hlines} only draws the horizontal lines.
		\end{itemize}
		\verb|\dmatrix[lines,sep=0.75]{0,2,1,4,3,6,5}| produces the matrix
		
		\dmatrix[lines,sep=0.75]{0,2,1,4,3,6,5}
		
		\begin{itemize}
			\Ii{no tikz} deletes the tikz environment and lets the user write it instead.
		\end{itemize}
		
		\I{ddiagram} produces a twelve tone clock diagram of arbitrary length, as shown in \href{https:diagramas.netlify.com}{this website}. For example, \verb|\ddiagram{0,2,1,4,3,6,5}| produces the diagram\\ 
		\ddiagram{0,2,1,4,3,6,5}
		
		\begin{itemize}
			\Ii{name} writes a name at the center of the diagram.
			\Ii{up} lets the user choose which number is up north. The default value is the first number in the row.
			\Ii{arrow shift} lets the user choose where the arrow should fall on the line. The values range from 0 to 10. The default value is 2.5.
		\end{itemize}
		
		\verb|\ddiagram[name=P, up=5, arrow shift=5]{0,2,1,4,3,6,5}| produces the diagram\\
		\ddiagram[name=P, up=5, arrow shift=5]{0,2,1,4,3,6,5}
		
		
		\begin{itemize}
			\Ii{no numbers} deletes the numbers around the diagram.
			\Ii{no arrow} deletes the arrow inside the diagram.
		\end{itemize}
		
		\verb|\ddiagram[no numbers, no arrow]{0,2,1,4,3,6,5}| produces the diagram\\
		\ddiagram[no numbers, no arrow]{0,2,1,4,3,6,5}
		
		\begin{itemize}
			\Ii{xshift} shifts the figure horizontally.
			\Ii{yshift} shifts the figure vertically.
			\Ii{no tikz} deletes the tikz environment and lets the user write it instead.
			The option \textsf{up} does not work anymore and the up position becomes 0.
			It is recommended that the user passes the option \textsf{ddiagram} to the environment:
			\begin{verbatim}
			\begin{tikzpicture}[ddiagram]
			\ddiagram[no tikz]{0,2,1,4,3,6,5}
			\end{tikzpicture}
			\end{verbatim} produces the same diagram as  \verb|\ddiagram{0,2,1,4,3,6,5}|.
		\end{itemize}
		
		\I{ddihedral} produces a dihedral representation of a series of arbitrary length. For example, \verb|\ddihedral{0,2,1,4,3,6,5}| produces the diagram\\
		\ddihedral{0,2,1,4,3,6,5}
		
		\begin{itemize}
			\Ii{t} applies the transformation \textit{transposition} to the diagram.
			\Ii{s} applies the transformation \textit{inversion} to the diagram.
			\Ii{c} applies the transformation \textit{cyclic shift} to the diagram.
			\Ii{v} applies the transformation \textit{retrograde} to the diagram.
			
			The transformations are applied in that exact order.
		\end{itemize}
		
		 \verb|\ddihedral[s=1, c=4]{0,2,1,4,3,6,5}| produces the diagram\\
		\ddihedral[s=1, c=4]{0,2,1,4,3,6,5}
		
		\begin{itemize}
			\Ii{no italics} removes the italics from the diagram name.
			\Ii{new t} renames the transformation \textit{transposition}.
			\Ii{new s} renames the transformation \textit{inversion}.
			\Ii{new c} renames the transformation \textit{cyclic shift}.
			\Ii{new v} renames the transformation \textit{retrograde}.
		\end{itemize}
	
	\verb|\ddihedral[no italics, new v=R, v=1]{0,2,1,4,3,6,5}| produces the diagram\\
	\ddihedral[no italics, new v=R, v=1]{0,2,1,4,3,6,5}
	
		\begin{itemize}
			\Ii{no tikz} deletes the tikz environment and lets the user write it instead. It is recommended that the user passes the option \textsf{ddihedral} to the environment:
			\begin{verbatim}
			\begin{tikzpicture}[ddihedral]
			\ddihedral[no tikz]{0,2,1,4,3,6,5}
			\end{tikzpicture}
			\end{verbatim} produces the same diagram as  \verb|\ddihedral{0,2,1,4,3,6,5}|.
		\end{itemize}
		
		\I{darrows} produces the arrows from the \verb|\ddihedral| diagram. For example,
 		\verb|\darrows{0,2,1,4,3,6,5}| produces the arrows\\
 		\darrows{0,2,1,4,3,6,5}
 		
 		\begin{itemize}
 			\Ii{no tikz} deletes the tikz environment and lets the user write it instead.
 		\end{itemize}
		
		\I{drow} produces a twelve-tone row sequence as a permutation in its matrix form. For example, \verb|\drow{0,2,1,4,3,6,5}| produces the row
		
		\drow{0,2,1,4,3,6,5}
		
		\begin{itemize}
			\Ii{sep} lets the user choose the column separation.
		\end{itemize}
		
		\verb|\drow[sep=10pt]{0,2,1,4,3,6,5}| produces the row
		
		\drow[sep=10pt]{0,2,1,4,3,6,5}
		
	\end{itemize}
	
	\section{The package code}	
	\lstset{
		language=[Latex]Tex,
		%
		basicstyle=\footnotesize\sffamily,
		keywordstyle=\footnotesize\sffamily,
		identifierstyle=\footnotesize\sffamily,
		commentstyle=\footnotesize\sffamily,
		stringstyle=\footnotesize\sffamily,
		escapechar=¬,
		%		
		numberstyle=\footnotesize\sffamily,%\ttfamily\tiny\color[gray]{0.3},
		numbers=left,
		stepnumber=2,
		numbersep=15pt,
		%
		columns=flexible,
		showstringspaces=false,
		tabsize=4,
	}
	\lstinputlisting{ddphonism.sty}
	
\end{document}
