diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/abc/abc.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/abc/abc.dtx | 572 |
1 files changed, 572 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/abc/abc.dtx b/Master/texmf-dist/source/latex/abc/abc.dtx new file mode 100644 index 00000000000..582601a6e19 --- /dev/null +++ b/Master/texmf-dist/source/latex/abc/abc.dtx @@ -0,0 +1,572 @@ +% \iffalse meta-comment +% +% Copyright (C) 2005 by Enrico Gregorio +% <Enrico dot Gregorio at univr dot it> +% ------------------------------------------------------- +% +% 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} +%</driver> +%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01] +%<package>\ProvidesPackage{abc} +%<*package> + [2006/03/22 v1.0 Enrico Gregorio] +%</package> +%<*driver> +\documentclass{ltxdoc} +\usepackage{verbatim} +\newenvironment{smallverb}{\footnotesize\verbatim}{\endverbatim} +\EnableCrossrefs +\CodelineIndex +\RecordChanges +\begin{document} + \DocInput{abc.dtx} +\end{document} +%</driver> +% \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 +%</example> +% \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 +%</abc> +% \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}}% +} +%</package> +% \end{macrocode} +% \end{macro} +% \end{environment} +% \Finale |