% \iffalse meta-comment % % Copyright (C) 2005 by Enrico Gregorio % % ------------------------------------------------------- % % This file may be distributed and/or modified under the conditions of % the LaTeX Project Public License, either version 1.2 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.2 or later is part of all distributions of LaTeX % version 1999/12/01 or later. % % \fi % % \iffalse %<*driver> \ProvidesFile{abc.dtx} % %\NeedsTeXFormat{LaTeX2e}[1999/12/01] %\ProvidesPackage{abc} %<*package> [2006/03/22 v1.0 Enrico Gregorio] % %<*driver> \documentclass{ltxdoc} \usepackage{verbatim} \newenvironment{smallverb}{\footnotesize\verbatim}{\endverbatim} \EnableCrossrefs \CodelineIndex \RecordChanges \begin{document} \DocInput{abc.dtx} \end{document} % % \fi % % \CheckSum{292} % % \CharacterTable % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z % Digits \0\1\2\3\4\5\6\7\8\9 % Exclamation \! Double quote \" Hash (number) \# % Dollar \$ Percent \% Ampersand \& % Acute accent \' Left paren \( Right paren \) % Asterisk \* Plus \+ Comma \, % Minus \- Point \. Solidus \/ % Colon \: Semicolon \; Less than \< % Equals \= Greater than \> Question mark \? % Commercial at \@ Left bracket \[ Backslash \\ % Right bracket \] Circumflex \^ Underscore \_ % Grave accent \` Left brace \{ Vertical bar \| % Right brace \} Tilde \~} % % \changes{v1.0}{2006/03/22}{After long delay decided to publish it} % % \changes{v0.7}{2005/11/21}{Corrected some errors from previous % version; changed `abcinput' to support keyword-value pairs like % the environment; added the production of a batch file when the % `noshellescape' option is active; improved the documentation} % % \changes{v0.7beta}{2005/11/19}{Added the `postoptions' and `width' % keywords} % % \changes{v0.6}{2005/11/18}{Changed options: erased `nix' and % `dos', added `ps2epsidos' to correct a mistake} % % \changes{v0.5}{2005/11/13}{Added the interface to keyval} % % \changes{v0.4}{2005/11/10}{Initial version; too many things changed} % % \changes{v.0.1-0.3}{2005/11/01}{Very preliminar versions} % % \GetFileInfo{abc.dtx} % % \DoNotIndex{\newcommand,\newenvironment,\def,\ifpdf,\begin} % \DoNotIndex{\DeclareOption,\ExecuteOptions,\RequirePackage} % \DoNotIndex{\renewcommand,\else,\fi,\relax,\@bsphack,\@esphack} % \DoNotIndex{\active,\AtEndOfPackage,\catcode,\centering} % \DoNotIndex{\closeout,\comment,\do,\dospecials,\end,\endcomment} % \DoNotIndex{\fbox,\gdef,\immediate,\includegraphics,\let} % \DoNotIndex{\linewidth,\message,\newif,\newwrite,\openout} % \DoNotIndex{\PackageWarning,\space,\the,\verbatim@line} % \DoNotIndex{\verbatim@processline,\verbatim@start,\write} % \DoNotIndex{\@makeother,\IfFileExists,\ProcessOptions} % \DoNotIndex{\@ifnextchar,\define@key,\MessageBreak,\setkeys} % \DoNotIndex{\^} % % \title{The \textsf{abc} class\thanks{This document corresponds to % \textsf{abc}~\fileversion, dated \filedate.}} % % \author{Enrico Gregorio \\ \texttt{Enrico dot Gregorio at univr dot it}} % % \date{\filedate} % % \maketitle % % \section{Introduction} % There are several ways to set music using \TeX{}, notably % Musix\TeX{} and Lilypond. Both are very powerful and, % consequently, a bit difficult to learn and to use. % % From the point of view of notation, the ABC % system\footnote{\texttt{http://staffweb.cms.gre.ac.uk/\char`\~c.walshaw/abc/}} % is much simpler. A recent extension of this language, called % ABC~Plus\footnote{\texttt{http://abcplus.sourceforge.net}}, allows % for setting multiple staves and polyphony. One of the best programs % for converting these notations into sheet music is % \texttt{abcm2ps}, which can take an ABC or ABC~Plus file and % transform it into a PostScript\texttrademark{} file. % % The purpose of this package is to allow \LaTeX{} users to include in % their documents small excerpts of music written directly in % ABC (Plus). It exploits the \verb|\write18| technique available with % the Web2C implementation of the \TeX{} system and free utilities % like \texttt{ps2eps}, \texttt{ps2epsi} and \texttt{epstopdf}. % % This package can be used both with \LaTeX{} and % \textsc{pdf}\LaTeX{}, without any change in the user's source file. % It employs also the package \textsf{keyval} by David Carlisle and % ideas from the \textsf{verbatim} package in the \LaTeX{} tools. % % \section{Usage} % \DescribeEnv{abc} % The only environment provided by this package is \verb|abc| with % the following syntax: % \begin{quote} % \verb|\begin{abc}[|\meta{keyword}$=$\meta{value}\verb|...]|\\ % \meta{ABC Plus material}\\ % \verb|\end{abc}| % \end{quote} % The environment should be used only in LR-mode. Its output is set % in a `center' environment. We give a list of the available % keywords. % \begin{description} % % \item[\normalfont\texttt{name=}\meta{name}:] \meta{name} is a name % for the temporary file which will be output and massaged by % \texttt{abcm2ps}. \emph{Warning}: the extension \texttt{.abc} is % automatically added to the file name; esistent files with the same % name will be silently erased (to be changed in future versions). % % \item[\normalfont\texttt{options=}\meta{options}:] \meta{options} % are command line parameters to the \texttt{abcm2ps} utility; the % default are `\texttt{-O= -c}'. % % \item[\normalfont\texttt{postoptions=}\meta{postoptions}:] % \meta{postoptions} are possible command line options which, in % \texttt{abcm2ps} syntax, go after the file name. % % \item[\normalfont\texttt{program=}\meta{program}:] \meta{program} is % used to specify an alternative program to \texttt{abc2mps} (if % existent). In this case users must specify completely the command % line options, directly in \meta{program} or with \meta{options} and % \meta{postoptions}. For example % \begin{quote} % \verb|\begin[name=song,program=abctoeps,options={-a -b}]|\\ % \verb|\begin[name=song,program={abc3ps -a -b}]| % \end{quote} % (assuming there is an \texttt{abc3ps} program). % % \item[\normalfont\texttt{width=}\meta{width}:] \meta{width} should % be a dimension; it is best to express it as a fraction of % \verb|\abcwidth|. % % \item[\normalfont\texttt{center}:] This is a boolean, either true % or false; the default is true, if left flush alignment is preferred, % specify \texttt{center=false}. % \end{description} % % \DescribeMacro{\abcinput} % It is also possible to input an available ABC file. The syntax is % \begin{quote} % \verb|\abcinput|\oarg{options}\marg{name} % \end{quote} % where \meta{name} is the name of the file, without the extension % which should be \texttt{.abc}. In the optional argument users can % put keyword-value pairs as for the environment. Of course the % keyword \texttt{name} is ignored here. % % \DescribeMacro{\abcwidth} % Users have a minimum control (at least in this version) on how to % include some lines of music. The only parameter they can modify is % \verb|\abcwidth| with \verb|\renewcommand|. Its normal value is % \verb|\linewidth|. The best thing to do is % \begin{quote} % \verb|\renewcommand{\abcwidth}{|\meta{fraction}\verb|\linewidth}| % \end{quote} % where \meta{fraction} is some number between $0$ and~$1$. Changing % this parameter affects every subsequent music inclusion, obeying to % the usual scoping rules. The width can be changed locally for the % environment or the command with the method explained before. % % \DescribeMacro{\normalabcoutputfile} % The name for the generic output files is ``\texttt{out-abc}''. In % the (improbable) case that some file \texttt{out-abc.}\meta{ext} is % present in the directory, users can redefine % \verb|\normalabcoutputfile| as they like. % % \section{Package options} % There are some package options, to control what is to be passed for % subsequent processing. % % \subsection{\texttt{shellescape} and \texttt{noshellescape}} % The option \texttt{shellescape} (default) means that some external % programs will be called by \LaTeX{} to get the inclusion of the % music lines. If you don't trust the automatic generation, or your % \TeX{} implementation does not allow the trick with \verb|\write18|, % then use \texttt{noshellescape}. In this case, a name should be % specified for every `abc' environment, because otherwise ABC output % files will be overwritten, since they receive the same generic name, % by default. A file named \texttt{out-abc.sh} is produced, % containing the commands to give for elaborating the music files. % % \subsection{\texttt{generate} and \texttt{nogenerate}} % With the \texttt{generate} option (default) the ABC lines will be % processed by the external programs. The \texttt{nogenerate} option % can be used when the ABC sources have not changed, in order to % increase speed. Also in this case, however, a name should be % specified for all output ABC files. % % \subsection{\texttt{ps2epsi}, \texttt{ps2epsidos} and % \texttt{ps2eps}} % The option \texttt{ps2eps} (default) means that the \texttt{ps2eps} % Perl script will be used for generating the EPS file for graphic % inclusion. Specify the \texttt{ps2epsi} option if you prefer the % \texttt{ps2epsi} program; specify \texttt{ps2epsidos} if you are on % a system where the utility \texttt{ps2epsi} generates a file with % three letter extension \texttt{.epi}. % % \section{Compiling documents} % Users must give the option \texttt{-shell-escape} when compiling % their documents (unless they chose the \texttt{nogenerate} package % option. Thus one of % \begin{quote} % \texttt{latex -shell-escape} \meta{\TeX{} file name}\\ % \texttt{pdflatex -shell-escape} \meta{\TeX{} file name}\\ % \texttt{simpdftex latex --extratexopts "-shell-escape"} % \end{quote} % should be used from the command line (or equivalent way, depending % on operating system and distribution). % % \section{An example file} % \iffalse %<*example> % \fi % \begin{smallverb} \documentclass[a4paper,12pt]{article} \usepackage[generate,ps2eps]{abc} \usepackage{mathptmx} \begin{document} \title{Example of ABC Plus in \LaTeX{}} \author{Guido Gonzato} \date{} \maketitle This is a short piece. \medskip \begin{abc} X:4 T:Cronin's Hornpipe R:hornpipe S:Keenan and Glackin E:7 M:C| L:1/8 K:G BA|GABc dBde|gage dega|bage dBGB|cABG A2BA|! GABc dBde|gage dega|bage dBAB|G2G2 G2:|! fg|afd^c d2ga|bged e2ga|(3bag (3agf gedB|(3cBA AG AcBA|! GABc dBde|~g3e dega|bage dBAB|G2G2 G2:|! \end{abc} \medskip This is another short piece, but we would like to keep the ABC source in our directory. \begin{abc}[name=jacky] X:9 T:Jacky Tar R:hornpipe M:4/4 L:1/8 K:Edor (Bd) | "Em" e2 ed efge | "G" d2 B2 B2 (dB) | "D" ABde faef | d2 A2 A2 (Bd) | "Em" e2 ef g2 fe | "G" dB GB d2 (cB) | "D" AGFE DEFA | "Em" G2 E2 E2 :| (GA) | "Em" BGEG BGEG | BAGF E2 (FG) | "D" BGEG BGEG | AGFE D2 (EF) | "G" GFGB g2 (fe) | dBGB d2 (cB) | "D" AGFE DEFA | "Em" G2 E2 E2 :| \end{abc} \clearpage And, finally, we want to set also the last piece; its ABC code is already in our directory. \medskip \abcinput{poll} \end{document} % \end{smallverb} % \iffalse % % \fi % % This file is accompanied by a file \texttt{poll.abc} % \iffalse %<*abc> % \fi % \begin{smallverb} X:12 T:Poll Ha'penny T:Garra\'i na bhF\'eile\'og R:hornpipe H:The Irish title means "The Garden of Honeysuckles" D:Mary Bergin: Feadoga Stain D:Noel Hill agus Tony McMahon: I gCnoc na Grai Z:id:hn-hornpipe-26 M:C| L:1/8 K:Amix (3GAB | =cAAG A2 (3AB=c | (3d=cB (3AGF G2 (3B^cd | ed^cA d^cAG | ~A3 G A2 de | ~f3 d ~e3 c | d2 (3Bcd efge | aged (3=cBA GB | ~A3 G A2:| |: ef | ~g3 f gfef | g2 ga gedg | eaag a3 g | eaag a2 ag | ~f3 d ~e3 c | d2 (3Bcd efge | aged (3=cBA GB | ~A3 G A2 :| % \end{smallverb} % \iffalse % % \fi % % \section{To do} % Find a robust way to assign a unique name to output files. With % \verb|\label| and \verb|\ref|, probably. % % \StopEventually{\PrintChanges\PrintIndex} % % \section{The implementation} % After the usual stuff of package presentation, here are the actual % macros. To begin with the option declarations and the defaults. % The first options are boolean. % \begin{macrocode} %<*package> \newif\ifabc@shellescape \newif\ifabc@generate \newif\ifabc@warning \DeclareOption{noshellescape}{\abc@shellescapefalse\abc@warningtrue} \DeclareOption{shellescape}{\abc@shellescapetrue} \DeclareOption{nogenerate}{\abc@generatefalse} \DeclareOption{generate}{\abc@generatetrue} % \end{macrocode} % The following options control the external programs to use. % \begin{macrocode} \def\abc@epsext{eps} \DeclareOption{ps2eps}{\def\abc@pscmd{ps2eps -f}} \DeclareOption{ps2epsi}{\def\abc@pscmd{ps2epsi}\def\abc@epsext{epsi}} \DeclareOption{ps2epsidos}{\def\abc@pscmd{ps2epsi}\def\abc@epsext{epi}} % \end{macrocode} % Now we declare the default options and call the user specified ones. % \begin{macrocode} \ExecuteOptions{generate,shellescape,ps2eps} \ProcessOptions\relax % \end{macrocode} % % Then we have to load some packages we need. The first one is to do % verbatim output to a file without reinventing the wheel. Then the % package for implementing keyword-value options; we have to take care % of graphics inclusion, and to control whether we are using \LaTeX{} % with DVI or PDF output. % \begin{macrocode} \RequirePackage{verbatim} \RequirePackage{keyval} \RequirePackage{graphicx} \RequirePackage{ifpdf} % \end{macrocode} % Next we define some internal commands. We choose to give explicitly % the extensions to the graphics files, since some user could prefer % \texttt{ps2epsi}. % \begin{macrocode} \newcommand{\abc@cmd}{abcm2ps} % virtually no choice \newcommand{\abc@parm}{-O= -c} % -O= MUST stay \newcommand{\abc@epstopdfcmd}{epstopdf} \newcommand{\abc@pdfext}{pdf} \def\normalabcoutputfile{out-abc} \def\abc@tempfile{\normalabcoutputfile} \def\abc@opt{} \let\abc@postopt\@empty \ifpdf \let\abc@finalext\abc@pdfext \else \let\abc@finalext\abc@epsext \fi \newif\ifabc@center \abc@centertrue % \end{macrocode} % The following is the only parameter the user is authorized to % tamper with. % \begin{macrocode} \newcommand{\abcwidth}{\linewidth} % only fractions of \linewidth % \end{macrocode} % \begin{macro}{\abc@startgen} % \begin{macro}{\abc@finishgen} % Now something directly borrowed from the package \textsf{verbatim}. % We declare an output stream and define two macros which will be % called by the \texttt{abc} environment or by the \verb|\abcinput| % command in case we are generating the graphics files. The macro % \verb|\abc@startgen| then passes the control to \verb|\abc@process| % which is different, according to the options given to the package. % \begin{macrocode} \newwrite\abc@out \def\abc@startgen{% \@bsphack \immediate\openout\abc@out\abc@tempfile.abc \let\do\@makeother\dospecials \catcode`\^^M\active \catcode`\^^I=12 \def\verbatim@processline{% \immediate\write\abc@out {\the\verbatim@line}}% \verbatim@start} \def\abc@finishgen{% \immediate\closeout\abc@out \@esphack \abc@process } % \end{macrocode} % \end{macro} % \end{macro} % \begin{macro}{\abc@doshellcommand} % \begin{macro}{\abc@nodoshellcommand} % We define a macro for the external massaging of the ABC files and % another one for the case the user doesn't trust or have available % the \verb|\write18| trick; the second one spits out a very simple % shell script which can be used to take care of the compilation; this % file is probably compatible with all systems having a command line % interface. Then we check the options again and define the commands % that really do the job. % \begin{macrocode} \def\abc@doshellcommand{% \immediate\write18{% \abc@cmd\space \abc@parm\space \abc@opt\space \abc@tempfile.abc \ifx\abc@postopt\@empty \else\space\abc@postopt\fi}% \immediate\write18{% \abc@pscmd\space\abc@tempfile.ps}% \ifpdf \immediate\write18{% \abc@epstopdfcmd\space\abc@tempfile.\abc@epsext}% \fi } \def\abc@nodoshellcommand{% \immediate\write\abc@outsh{% \abc@cmd\space \abc@parm\space \abc@opt\space \abc@tempfile.abc \ifx\abc@postopt\@empty \else\space\abc@postopt\fi}% \immediate\write\abc@outsh{% \abc@pscmd\space\abc@tempfile.ps}% \ifpdf \immediate\write\abc@outsh{% \abc@epstopdfcmd\space\abc@tempfile.\abc@epsext}% \fi } % \end{macrocode} % We use a conditional to emit a message at the end of the % compilation if some file has not been found and the % \texttt{nogenerate} option was chosen. % \begin{macrocode} \AtEndDocument{% \ifabc@warning \PackageWarningNoLine{abc}{% Remember to generate the [eps,pdf] files before compiling% \MessageBreak again. Use the file \abc@tempfile.sh for a list or as a script}% \fi} % \end{macrocode} % \end{macro} % \end{macro} % Now we define the macro responsible for the massaging of the ABC % files. This is a good moment for inizializing the writing of the % shell script, when needed. % \begin{macro}{\abc@process} % \begin{macrocode} \ifabc@shellescape \let\abc@process\abc@doshellcommand \else \newwrite\abc@outsh \immediate\openout\abc@outsh\abc@tempfile.sh \AtEndDocument{\closeout\abc@outsh} \let\abc@process\abc@nodoshellcommand \fi % \end{macrocode} % \end{macro} % \begin{macro}{\abc@start} % \begin{macro}{\abc@finish} % We now define how to start and finish; if no generation is required, % the ABC lines are skipped like a comment (thanks again to the % \textsf{verbatim} package). % \begin{macrocode} \ifabc@generate \let\abc@start\abc@startgen \let\abc@finish\abc@finishgen \else \let\abc@start\comment \let\abc@finish\endcomment \fi % \end{macrocode} % \end{macro} % \end{macro} % \begin{environment}{abc} % \begin{macro}{\abcinput} % Finally, we define the environment and the command. Some commands % are initialized here; the name of the temporary file is, by default, % ``out-abc'' which should not clobber any existing file. % \begin{macrocode} \def\abc{\@ifnextchar[\abc@grab{\abc@grab[]}} \define@key{abc}{name}{\def\abc@tempfile{#1}} \define@key{abc}{options}{\def\abc@opt{#1}} \define@key{abc}{postoptions}{\def\abc@postopt{#1}} \define@key{abc}{program}{\def\abc@cmd{#1}\let\abc@parm\@empty} \define@key{abc}{width}{\def\abc@width{#1}} \define@key{abc}{center}[true]{\csname abc@center#1\endcsname} \def\abc@grab[#1]{\let\abc@width=\abcwidth\setkeys{abc}{#1}\abc@start} % \end{macrocode} % The final part of the environment; we do the processing, if % required and then include the graphics file. If none is found, the % simple name is used, to recall that some processing is to be done. % \begin{macrocode} \def\endabc{% \abc@finish \trivlist\item[]\ifabc@center\centering\fi \IfFileExists{\abc@tempfile.\abc@finalext} {\includegraphics[width=\abc@width]{\abc@tempfile.\abc@finalext}}% {\global\abc@warningtrue\fbox{\abc@tempfile}}% \endtrivlist } % \end{macrocode} % The command version is similar. The only difference is that we % issue a warning if the named file does not exist. % \begin{macrocode} \def\abcinput{\@ifnextchar[\abc@grabinput{\abc@grabinput[]}} \def\abc@grabinput[#1]#2{\let\abc@width=\abcwidth\setkeys{abc}{#1}% \begingroup\def\abc@tempfile{#2}% \IfFileExists{\abc@tempfile.abc} {% \abc@process \begin{center} \IfFileExists{\abc@tempfile.\abc@finalext} {\includegraphics[width=\abc@width]{\abc@tempfile.\abc@finalext}}% {\fbox{\abc@tempfile}}% \end{center}% \endgroup } {\PackageWarning{abc}{No file \abc@tempfile.abc found}}% } % % \end{macrocode} % \end{macro} % \end{environment} % \Finale