\chapter{Embedding Musical Excerpts in Text Documents} Here we discuss the options for including music in text documents. The first decision is whether or not to use \LaTeX\footnote{We'll assume a user wanting to embed a musical excerpt in a \LaTeX\ document is already familiar with the fundamentals of \LaTeX. For more information about it, see for example the manual \ital{\LaTeX: A Document Preparation System} by Leslie {\sc Lamport}}. Because \LaTeX\ so effectively simplifies production of text-based \TeX\ documents, most users take that path, and most of the descriptions given here will assume that's the case\footnote{Please do not be confused; while \LaTeX\ is recommended for text-based documents containing musical excerpts, its use is definitely discouraged for ordinary self-contained musical scores of any sort.}. If for some reason you choose not to use \LaTeX\ for musical excerpts, the basic approach is simply to set off the musical parts between \verb|\startpiece| or \verb|\contpiece| and \verb|\stoppiece| or \verb|\endpiece|, or between \verb|\startextract| and \verb|\zendextract|. But some details in what follows will also apply without \LaTeX. There are two basic approaches to embedding musical excerpts in \LaTeX\ documents. The first method is to directly include the \musixtex\ code in the \LaTeX\ source file. That will be the subject of the next subsection. The other is to create an EPS (encapsulated Postscript) or PDF file containing only the excerpt, and then ``paste'' it into the \LaTeX\ file. That will be covered in Section~\ref{embedeps}. The advantages of using the direct method are that all of the source code for all excerpts can be kept in the same file as the text, and that there is no limit on the length of the excerpt. The advantage of the EPS/PDF method is that you don't have to burden the \LaTeX\ source with any of the \musixtex\ paraphernalia. That in turn permits use of primitive versions of the \TeX\ compiler that may not have the capacity to handle the direct method (due to the number of registers consumed by \LaTeX\ and \musixtex). The disadvantages are that you must create and keep track of a separate \TeX\ and EPS/PDF file for every excerpt, and that the excerpt must not span any page breaks. On balance, the direct method is probably to be preferred. \section{Directly embedding excerpts in \LaTeX\ documents}\label{excerpts} To use the direct method, add \verb|\usepackage{musixtex}| to the preamble. This will cause the file \ttxem{musixtex.sty} to be loaded, so naturally you must make that file available in a place where \TeX\ can find it. That file simply inputs two other files, \verb|musixtex.tex| and \ttxem{musixltx.tex}, which again must obviously be available to \TeX. Now you are in position to directly embed an excerpt by inserting code at the appropriate place in the source file. The most common type of excerpt is one that occupies less than a full line and is to be horizontally centered. In that case, the extract should begin with the command \keyindex{begin\LBR music\RBR}, followed by any preliminary commands. Then, instead of \verb|\startpiece|, use \keyindex{startextract}. Now comes the normal \musixtex\ coding. Finally, end the extract with \keyindex{endextract} instead of \verb|\endpiece| or \verb|\stoppiece|, followed by \keyindex{end\LBR music\RBR}. To terminate an extract without any bar line, use \keyindex{zendextract} instead of \verb|\endextract|. To create a left-justified excerpt, use the sequence \begin{quote} \verb|\let\extractline\leftline|. \end{quote} If several extracts are to be placed on the same line, you can redefine \keyindex{extractline} as demonstrated in the following example\footnote{The macro {\tt\Bslash extractline} is defined once and for all in {\tt musixtex.tex} as {\tt\Bslash centerline}. You might think that the suggested coding would permanently redefine {\tt\Bslash extractline}, thereby upsetting the normal function of {\tt\Bslash startextract ... \Bslash endextract} for subsequent use. But it doesn't, because any actions within \keyindex{begin\LBR music\RBR}...\keyindex{end\LBR music\RBR} are local, not global.}: % DAS temp (where is the reference???) %An example of this is given at \ref{extractline} on page \pageref{extractline}. % end DAS temp \begin{quote}\begin{verbatim} \begin{music}\nostartrule \let\extractline\hbox \hbox to \hsize{% \hss\startextract ... \zendextract\hss% \hss\startextract ... \zendextract\hss} \end{music} \end{verbatim}\end{quote} An even shorter type of extract is one that is embedded \ital{within} a line of text. To insert \musixtex\ symbols within a line of text, you could begin by defining \keyindex{notesintext} as follows\footnote{provided by Rainer {\sc Dunker}}: \begin{quote}\begin{verbatim}\begin{music}\nostartrule \makeatletter \def\notesintext#1{% {\let\extractline\relax \setlines10\smallmusicsize \nobarnumbers \nostartrule \staffbotmarg0pt \setclefsymbol1\empty \global\clef@skip0pt \startextract\addspace{-\afterruleskip}#1\zendextract}} \makeatother \end{music}\end{verbatim}\end{quote} Then, for example, the code \begin{verbatim} Use \raisebox{0ex}[0ex][0ex]{\notesintext{\notes\rql1\qu2\en}} not \raisebox{0ex}[0ex][0ex]{\notesintext{\notes\ql2\lqu1\en}} \end{verbatim} \noindent would produce: ``Use \raisebox{0ex}[0ex][0ex]{\notesintext{\notes\rql1\qu2\en}} not \raisebox{0ex}[0ex][0ex]{\notesintext{\notes\ql2\lqu1\en}}~''. \noindent The \verb|\raisebox| voids the vertical space that is introduced by the notes. Finally, you may want to insert an extract containing more than one line of music. This is the easiest of all: between \verb|\begin{music}| and \verb|\end{music}|, use \ital{exactly} the same coding you would to make an ordinary score. \enlargethispage*{4ex} The best way to learn how to apply these methods is to study the source files for this document\footnote{Do note, however, that {\tt musixdoc.tex} loads a \texttt{musixdoc.sty} package in its preamble, not just \texttt{musixtex.sty}; the former performs the functions of \texttt{musixtex.sty} as well as numerous tasks peculiar to this particular document.}. %DAS I don't think this section is worth including. % \section{Wide music in \LaTeX}\label{musixblx} % Another difficulty appears with \LaTeX: internal \LaTeX\ macros handle the %page size in a way which is not supposed to be changed within a given document. %This means that text horizontal and vertical sizes are somewhat frozen so that %one can hardly insert pieces of music of page size different from the size %specified by the \LaTeX{} \itxem{style}. %Although a \ttxem{musixblx.tex} has been provided, which makes the %\ital{environment} \verb|bigmusic| available. %\zkeyindex{begin\LBR bigmusic\RBR} %The main drawback is an unpredictable behaviour of top and bottom %printouts, especially page numberings. % % If the whole of a document has wide pages, it can be handled with the %\ttxem{a4wide} style option, or any derivate of it. \section{Embedding musical excerpts as PDF or EPS files} \label{embedeps} To use this method of including excerpts, you first must create a separate \musixtex\ input file for each excerpt. Process each such file with \TeX\ and \verb|musixflx| to generate a \verb|.dvi| file. Generate a Postscript file from each \verb|.dvi| using \verb|dvips|. Then convert each Postscript file to a \verb|.pdf| or \verb|.eps| file using \verb\ps2pdf\ or \verb\ps2eps\; if you are using Windows, {GSview} can be used for either. Note that conversion to EPS (Encapsulated Postscript) is possible only for \emph{single-page} Postscript files. To set up your \LaTeX\ document for including \verb|.pdf| or \verb|.eps| files, you must post the command \verb|\usepackage{graphicx}| in the preamble of the document. Now, you may include each \texttt{sample.pdf} or \texttt{sample.eps} file at the appropriate place in the {\LaTeX} document with a command like \keyindex{includegraphics}\verb|{sample}|. If an embedded file is a PDF (rather than an EPS), the document must be processed with \verb|pdflatex| (rather than \verb|latex|). \section{Issues concerning \texorpdfstring{{\Bslash catcodes}}{catcodes}} \label{catcodeprobs} \musixtex\ uses the following symbols differently from plain \TeX: \verb|>|, \verb|<|, \verb&|&, \verb|&|, \verb|!|, \verb|*|, \verb|.|, and \verb|:|\ .\\ The symbols are given their special meanings by executing the macro \keyindex{catcodesmusic}, and are restored to their plain \TeX\ meanings with \keyindex{endcatcodesmusic}. When setting either a self-contained score or a musical extract, you normally need not worry about this at all, because \verb|\startpiece| or \verb|\startextract| executes \verb|\catcodesmusic| and \verb|\endpiece| or \verb|\endextract| executes \verb|\endcatcodesmusic|. But there are some special situations where you might need to use these catcode-modifying macros explicitly. One is if you were to define a personalized macro outside \verb|\startpiece ... \endpiece|, but which incorporated any of the symbols with their \musixtex\ meanings. Another would be if you wished to have access to facilities enabled by alternate style files such as {\tt\ixem{french.sty}} which change \keyindex{catcode}s themselves. In such cases, provided you have input \verb|musixtex.tex|, you can always invoke \keyindex{catcodesmusic} to set the \keyindex{catcode}s at their \musixtex\ values, and \keyindex{endcatcodesmusic} to restore them to their prior values.