musixpss - a MusiXTeX Extension Package: PostScript Slurs by MetaPost

version 0.54 [2017/08/17]

Introduction

MusiXTeX is a very powerful system to writing a musical score. However, the appearance of slurs (including ties) are not so beautiful, because of their drawing method: combination of fonts.

This package provides a new method for slurs and ties to improve them: using Encapsulated PostScript (EPS) code generated by MetaPost.

Features

Support almost all MusiXTeX traditional slur expressions (normal slur/tie, slur height adjustment, inverted slur, dotted slur).
Almost full upper-compatible with traditional font-based slurs, except for that \curve{h}{i}{j} is equivalent to \midslur{h} at present.
No limits of slur length, slur height, slur slope.
Improved appearance.
Compatible with various DVIwares and pdfTeX.
Low consumption of TeX's registers: 1 \count, 1 \write, 1 \read.
Good working in LaTeX music environment with musixtex.sty.

Disadvantages

Generating too many intermediate files. (The author recommends users to prepare one directory per one score.)
Increase of procedure.
Max 4095 slurs. (dependent on OS and TeX distribution)

doc directory **
- musixpss_en.html
  This file; Document in English.
- musixpss_it.html
  Document in Itailan. (translated by Luigi Cataldi)
  NOTE: this Italian document is for ver.0.53; is not latest.
- musixpss_ja.html
  Original document in Japanese.
musixpss.tex
TeX macro file.
musixpss.mp
MetaPost macro file.
musixpss.exe
Support program executable for Microsoft Windows, compiled with MinGW-gcc-3.4.5.
musixpss.c
C source code of support program.
gpl-2.0.txt
GNU General Public License ver.2; a verbatim copy of http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.

* All readable files (html, tex, mp, c) are in CRLF line termination (MS-DOS/Windows style).

Requirement

TeX. pdfTeX (ver.1.10a-devel or later) is also applicable.
MusixTeX ver.T.99 or later
MetaPost
(in case with conventional TeX)
a DVIware which supports inclusion of EPS figures via \special{PSfile=...} . At least followings are OK:
- dvips
- dvipdfm (ver.0.12 or later)
- dvipdfmx (ver.20040616 or later)
- dviout
Recommendable DVIwares are dvips (dvipsk), dvipdfm, dvipdfmx. DVIwares which require child process execution of Ghostscript to rasterize EPS-files are not recommended due to slow operation.
(in case with pdfTeX)
two additional support macro files, supp-pdf.tex and supp-mis.tex . These files should be enough new ones. They are available from ConTeXt distribution or http://www.tug.org/applications/pdftex/ . For further info, see the pdfTeX documents and samples.
Using pdfTeX is also recommended for enough fast operation.
an ANSI C compiler. (in case your OS is not Microsoft Windows)

Installation

Assume that TeX (or pdfTeX), MusiXTeX, and MetaPost work well on your system.
Put musixpss.tex into the directory where the working score exists or where "TeX input files directory" in TEXMF tree (for example $TEXMF/tex/generic/musixtex/misc/ ).
Put musixpss.mp into the directory where the working score exists or where "MetaPost input files directory" in TEXMF tree (for example $TEXMF/metapost/musixtex/misc/ ).
If your OS is Microsoft Windows, put musixpss.exe into an appropriate directory registered in PATH environment variable; for example the directory where musixflx.exe is located.
If not, modify musixpss.c line 44-45, compile it with an ANSI C compiler (for example: gcc -Wall -O2 -o musixpss musixpss.c ), and put the executable into appropriate directory.

Usage

Assume that the MusiXTeX score source is named foo.tex.

Make a MusiXTeX score source foo.tex in conventional way.
add a line \input musixpss.tex\relax after \input musixtex.tex .
Run usual MusiXTeX procedure (pass 1, 2, 3):
tex foo
musixflx foo
tex foo
In pass 3, some messages such as No file foo.slu.1.mps. or (foo.slu.1.mps) will appear on the terminal and LOG file, and a file foo.slu containing parameters of slurs will be additionally generated.
(Pass 4) Run the support program.
musixpss foo
The program musixpss.exe will translate foo.slu into MetaPost input, foo.mp. Filename extension is forcely regarded as .slu , regardless of its existence.
(Pass 5) Run MetaPost.
mpost foo
where command line is system dependent. See the manual of your MetaPost system. EPS files foo.slu.1.mps, foo.slu.2.mps ... containing each slur will be generated.
(Pass 6 -- except for dvips/dvipdfm optimized mode) Run TeX once more.
tex foo
The warnings will disappear and \special for inclusion of EPS files will be written into DVI file.
Run DVIware, Ghostscript, Acrobat Reader, etc.

When correcting and retypesetting the score, it is not required deleting intermediate EPS files such as foo.slu.1.mps. If there is no change in both foo.mx2 and foo.slu (this is relatively rare case), only one execution of TeX will go.
Deleting EPS files before retypesetting will speed up operation of Pass 3, in case of a large change of score and using general mode or pdfTeX exclusive mode.

Options and some advanced functions

Operation mode selection

This package has 3 basic operation modes to adapt itself to various environment.

\psslurmode{general} : general mode (default)
\psslurmode{dvips} : dvips/dvipdfm optimized mode
\psslurmode{pdftex} : pdfTeX exclusive mode

The default is 'general mode'. This mode guarantees the same compatibility of dvi file as LaTeX2e graphicx package with [dvips] option, since the internal procedures are almost same. Use this mode in general.

'dvips/dvipdfm optimized mode' is designed for dvips and dvipdfm/dvipdfmx. This mode makes the 6th pass of typesetting procedure unnecessary and thus provides much faster operation than 'general mode', because the internal procedures of this mode is much simpler. Also, this mode provides slightly good alignment. The resulting dvi file is, however, not compatible with some DVIwares, because of the difference of low-level (not LaTeX2e-level) implementation of \special{PSfile=...} from dvips.

'pdfTeX exclusive mode' is just as the naming. This mode works well with pdfTeX ver.1.10a-devel or later. It is known that some old version of support macro files supp-pdf.tex and supp-mis.tex lead to unaccountable error. In that case please update these two files at first.

The author hopes to adapt this package to DVIwares not listed above (xdvi, etc.) but has no environment of such DVIwares, other TeX distributions and OS's. Informations and trial reports are welcome.

Since ver.0.52, following two definitions for automatic mode selection are added. In these settings, musixpss.tex detects whether the using engine is conventional TeX or pdfTeX and selects appropriate operation mode automatically. Other characteristics are identical to the selected basic mode.

\psslurmode{auto-pdftex-general} : automatic selection for 'general mode' and 'pdfTeX mode'
\psslurmode{auto-pdftex-dvips} : automatic selection for 'dvips/dvipdfm optimized mode' and 'pdfTeX mode'

operation mode general mode dvips / dvipdfm optimized mode pdfTeX exclusive mode auto selection for general and pdfTeX auto selection for dvips and pdfTeX

general DVIwares* OK dependent on DVIware NG OK dependent on DVIware

dvips/dvipdfm(x) OK OK NG OK OK

pdfTeX NG NG OK OK OK

*Any DVIware compatible with LaTeX2e graphicx package with [dvips] option. for example dviout, etc.

operation mode general mode dvips / dvipdfm optimized mode pdfTeX exclusive mode

code \input musixtex \input musixpss \relax \input musixtex \input musixpss \relax \psslurmode{dvips}% \input musixtex \input musixpss \relax \psslurmode{pdftex}%

procedure Total 6 pass
+ DVIware

tex foo
musixflx foo
tex foo
musixpss foo
mpost foo
tex foo
%DVIWARE% foo
Total 5 pass
+ dvips or dvipdfm(x)

tex foo
musixflx foo
tex foo
musixpss foo
mpost foo
dvips foo
(or dvipdfm(x) foo)
Total 6 pass
+ Acrobat Reader

pdftex foo
musixflx foo
pdftex foo
musixpss foo
mpost foo
pdftex foo
(AcroRd32) foo

operation mode auto selection for general and pdfTeX auto selection for dvips and pdfTeX

code \input musixtex \input musixpss \psslurmode{auto-pdftex-general}% \input musixtex \input musixpss \psslurmode{auto-pdftex-dvips}%

Slur thickness adjustment

The thickness of slurs can be changed by redefining a macro \psslurthickadj . For example, \def\psslurthickadj{2.5} makes the slurs 2.5 times thicker than the default.

Switching EPS-based slurs and font-based slurs

EPS-based slurs can be switched on and off at any place in the score source by:

\enablepsslurM
use EPS-based slurs (default)
\disablepsslurM
use font-based slurs

Support program: cleaning intermediate EPS files

The support program has a function for deleting intermediate EPS files. This function is useful when deleting EPS files before total retypesetting and so on.

musixpss -clean foo.slu

(filename extension .slu can be omitted.) or the same

musixpss foo.slu -clean

removes all intermediate EPS files foo.slu.1.mps, foo.slu.2.mps, ...foo.slu.n.mps .

Note: the implementation is very simple, so please check the C source code and use this function with care. The author do not guarantee any responsibility of losing important files.

License

GNU GPL ver.2 or any later version. See the file gpl-2.0.txt for details.
For the time being, the author myself select GNU GPL version 2 as this package's basic criteria of license. However, the author of course do not prohibit shifting to latest GNU GPL version 3 when anyone combine a part of this package into another program.

Author

Hiroaki MORIMOTO <CQX05646 (atmark) nifty (dot) com>

Acknowledgement

The author would like to express a great grarirude to Luigi Cataldi for his Italian version document and pdfTeX trial reports and so on.

History

version 0.10 [2001/02/10]

first public release.

version 0.20 [2001/02/23]

EPS inclusion method is changed from \special{epsfile=...} to special{PSfile=...} .

version 0.21 [2001/04/30]

Bugfix for \midslur h

version 0.22 [2001/06/15]

dvipdfm compatible.
Bugfix for slur alignment.

version 0.23 [2001/10/17]

Bugfix for \islurd... with \midslur h (upside down)
Emulation of slur height limiter of original MusiXTeX: for example \isluru0...\midslur{-5}\tslur0

version 0.30 [2001/10/21] (first announcement to TeX-music Mailing List)

Support for inverted slurs. (\invertslur, \Tslurbreak , \Islur[u|d]break)
Bugfix for \musicsize <> 16pt.
Trimming internal parameters for \midslur h with large h.

version 0.40 [2001/11/03]

Support for dotted slurs.
Operation mode selection: \psslursimplepositioning[true|false] switches dvips optimized mode ON and OFF.
Emulation of slur height limiter of original MusiXTeX can be enabled and disabled by \psslurorgemu[true|false] .
Relate slur thickness to \musicsize .
Improved MetaPost code (divided into common section and individual slur parameters).
Add a check routine on getting parameters from file.

version 0.41 [2002/06/01]

No functional change.
License change (GNU GPL ver.2)
English documentation (HTML) is provided in distribution archive.

version 0.50 [2003/01/05]

Slur thickness can be adjusted by redefining \psslurthickadj .
pdfTeX compatible.
Operation mode selection: \psslurmode{general|dvips|pdftex} invokes "general mode", "dvips optimized mode", "pdfTeX exclusive mode", respectively. Thus \psslursimplepositioning[true|false] became obsolete and no more supported.
Cleaning function for intermediate EPS files.
The common section of MetaPost code is moved into musixpss.mp .
Fix %-ing at line termination in musixpss.tex .
Japanese documentation is ported into HTML.

version 0.51 [2004/02/21]

Suppress extra inclusion of EPS files. In Pass 1 EPS slur files are neither included nor searched. In Pass 3 and 6 of general mode and pdfTeX exclusive mode, further search for EPS files is canceled in case the expected EPS file is not found.

version 0.51.1 [2004/03/21]

No functional change.
Italian document provided by Luigi Cataldi is added.

version 0.52 [2007/01/01]

spam-proof author address description.
pdfTeX automatic selection.
Suppress writing parameters on foo.slu in pass 1 to improve speed.
Support program bug fix: crashes in case options only are given without filename.

version 0.53 [2009/07/21]

Support program bug fix: Program crashes in case given filename has extension.
Support program fix: Compilation problem with gcc-4.x because of buffer overflow warning at gets().
The source URL of GNU GPL ver.2 is updated because GNU GPL ver.2 is no longer the latest GNU GPL.

version 0.54 [core modules on 2017/08/12, documents on 2017/08/17]

Conforming to new specifications of dvipdfm(x) and pdfTeX since TeX Live 2016 concerning MetaPost-generated EPS files ( *.mps ). In case of too old MetaPost which does not support outputtemplate , use version 0.53.
All human-readable files (html, tex, mp, c) are changed into CRLF line termination (MS-DOS/Windows style).
Update URLs in this document.

TODO:

implementing \Check@staff based on MusiXTeX T.109 or later
improvement of dotted slurs (exposing setting parameters)
curve assignment
moving support program to more secure platform
and so on...

Copyright (C) 2001-2017 Hiroaki MORIMOTO
All kinds of comments, suggestions, and bug reports are welcome. If you find any problems or ideas, please tell me via 'TeX-music Mailing List'.