PMW(1)

NAME
pmw - a program for typesetting music

SYNOPSIS
pmw [options] [input file]

DESCRIPTION

PMW (Philip's Music Writer) is a program for typesetting music. It is not an interactive program; instead, it reads a description of the music from a textual input file, which can be prepared by any text editor. The output from PMW is either a PostScript file or a PDF of page images of typeset music. The default output format is set when PMW is built, but there are options to select either form. A secondary output in the form of a MIDI file can be requested. Support for importing and exporting MusicXML files can optionally be included when PMW is built, but this is currently experimental and not yet of production quality. A full description of PMW and its markup language is given in the reference manual. This man page just summarises the command line options.

GENERAL OPTIONS

-a4ona3
    Pages are A4-sized; output them 2-up, suitable for A3 paper.

-a5ona4
    Pages are A5-sized; output them 2-up, suitable for A4 paper.

-C <arg>
    Show a build-time option; exit with its value (0 or 1). Possible arguments are:

      b2pf suport for B2PF processing
      musicxml support for MusicXML input and output

-drawbarlines
    Instead of using characters from the music font for bar lines, generate drawing instructions. Some PostScript/PDF interpreters do not display the font bar line characters correctly on the screen when several of them are used to generate a long vertical line; drawing them instead may give a better result. -dbl is an abbreviation for -drawbarlines.

-drawstavelines [<thickness>]
    Instead of using characters from the music font for stave lines, generate drawing instructions. Some PostScript/PDF interpreters do not display the font stave characters correctly on the screen; drawing them instead may give a better result. The default thickness of drawn stave lines is 0.3 points, scaled according to relative stave size and overall magnification. An integer number given with this option specifies the thickness in tenths of a point. -dsl is an abbreviation for -drawstavelines.

-eps
    Write the main output as encapsulated PostScript (useful if this is an illustration that is going to be included in some other document). This option is mutually exclusive with -pdf.

-F <directory-list>
    Search the given colon-separated list of directories for fontmetrics files, before searching the default directory that was set up when PMW was built. These directories are also searched for optional Unicode translation (.utr) files for fonts that do not use Adobe standard encoding, and for any special text fonts that are requested to be included in PostScript output or are needed for PDF output.

-f <name>
    Specifies a format name, used when the input file is set up to output in several different formats.

-help or --help
    Output a list of options, then stop. No file is read.

-MP <file>
    Use the given file as the MIDIperc file, instead of the default that was set up when PMW was built. This file translates between names and "pitches" for untuned percussion voices.

-MV <file>
    Use the given file as the MIDIvoices file, instead of the default that was set up when PMW was built. This file translates voice names to MIDI voice numbers.

-midi <file>
    Write MIDI output to the given file (in addition to the normal PDF or PostScript output). The stave selection (see -s below) also applies to MIDI output.

-midibars <range>
    If -midi is given, write only the given bars to the MIDI output. The range can be two numbers separated by a hyphen or a single number for just one bar. A single number followed by a hyphen plays from that bar to the end of the movement. -mb is an abbreviation for -midibars.

-midimovement <number>
    For a multi-movement input file, this specifies the movement that is to be output as MIDI when -midi is given. The default is the first movement. -mm is an abbreviation for -midimovement.

-norc or -nopmwrc
    Do not read the caller's .pmwrc file. This must be the first option given.

-norepeats
    When generating a MIDI output file, do not repeat repeated sections of the music. -nr is an abbreviation for -norepeats.

-nowidechars
    This option stops PMW from using the 100-point wide stave characters when outputting staves. Instead, staves are constructed entirely from the 10-point wide characters. This option is provided because it seems that some PDF/PostScript interpreters cannot deal correctly with the very wide characters. -nw is an abbreviation for -nowidechars. The -drawstavelines option overrides this option.

-o <file>
    Send the PostScript or PDF output to the given file, or, if "-" is given, to stdout. The default file name is the input file with the extension ".ps" or ".pdf" replacing any existing extension, or being added if there is no extension. If there is no input file (input from stdin) the default output is to stdout.

-p <list>
    Output only the specified pages. These can be individual page numbers, or pairs of numbers separated by a hyphen, to specify a range. Use commas to separate items in the list.

-pamphlet
    Output pages in pamphlet order. This is usually used in conjunction with -a5ona4 or -a4ona3.

-pdf
    Select PDF as the main output format. This is mutually exclusive with -ps and -eps.

-printadjust <x> <y>
    Move the image on the page by (x,y) points.

-printgutter <x>
    This option specifies a distance by which righthand (recto) page images are moved to the right, and lefthand (verso) page images are moved to the left, thus creating a "gutter" for binding when the images are printed doublesided. The -printgutter setting applies only when pages are being printed 1-up. It is ignored for any of the 2-up printing styles.

-printscale <n>
    Scale the output image by <n>.

-printside <n>
    Output only odd or only even pages; <n> must either be 1 or 2.

-ps Select PostScript as the main output format. This is mutually exclusive with -pdf.

-reverse
    Output the pages in reverse order.

-s <list>
    Output only the specified staves. These can be individual stave numbers, or pair of numbers separated by a hyphen, to specify a range. Use commas to separate items in the list.

-t <number>
    Specify a transposition, in semitones.

-V or --version
    Output the PMW version number to stdout, then stop. No file is read.

-v  Output verification information about the typesetting to stderr.

POSTSCRIPT-SPECIFIC OPTIONS

The following options are relevant only for PostScript output.

-a4sideways
    The paper is A4, but the printer feeds it sideways, so rotate the page images before printing.

-c <number>
    Arrange to print <number> copies. This number is honoured by PostScript printers. It may not be honoured by other programs that interpret PostScript.

-duplex
    This option sets the PostScript option for duplex printing (see also -tumble).

-H <file>
    Use the given file as the PostScript header file, instead of the default that was set up when PMW was built.

-incPMWfont or -incpmwfont or -ipf
    This option causes PMW to include the music font within the PostScript output that it generates. If the PMW-Alpha font is used, that is also included. If you use this option, there is no need to install the PMW music font(s) for GhostScript (or any other display program) to find.

-manualfeed
    Set the `manualfeed' option in the generated PostScript. Most PostScript printers interpret this to mean that the paper should be taken from an alternate input tray or slot. Some also require the user to push a button before each page is printed.

-tumble
    When -duplex is set, -tumble causes the PostScript option for "tumbled" duplex printing.

MUSICXML OUTPUT OPTIONS

These options are available when PMW has been built with optional MusicXML support. If the PMW input file contains more than one movement, and no individual movement is selected by -musicxmlmovement, and the file name set by -musicxml contains "%d" with optional digits between those two characters, each movement is output as a separate MusicXML file, with the "%d" sequence replaced by the movement number.

-musicxml <file>
    This option requests that, in addition to the normal PostScript or PDF output, one or more MusicXML files be written. -xml is an abbreviation for -musicxml.

-musicxmlmovement <number>
    In conjunction with -musicxml, this selects which movement is to be written as MusicXML. The default is the first movement. -xmlmovement and -xm are abbreviations for -musicxmlmovement.

-x<selectors>
    This sets one or more options for MusicXML output. They must be separated from each other and from -x by plus signs, with no white space. A list of possible options is output when PMW is called with the --help option. The PMW manual describes what each one does.

MAINTENANCE AND DEBUGGING OPTIONS

These options are of use only to a PMW maintainer.

-d<selectors>
    Write general debugging information to stderr.

-dbd [<movement>,][<stave>,]<bar>
    Write debugging data for the given the bar to stderr. This option contrains the amount of output that is produced by -d+bar (which it implies).

-dtp <bar>
    Write debugging positioning data for the bar to stderr. If there is more than one movement (not likely while debugging at this level), the data is output for every bar with the given number. If the number is -1, data is output for all bars.

-errormaximum <number>
    Set the maximum number of errors before the program gives up. The default is 40. This option is provided mainly so that an error test can generate a large number of errors. -em is an abbreviation for -errormaximum.

-MacOSapp <directory>
    Specify the resource directory when PMW is run from within a MacOS app (experimental).

-MF <directory>
    Search the given colon-separated list of directories for PMW's music fonts, before searching the default directory that was set up when PMW was built.

-SM <directory>
    Search the given directory for standard macro files instead of searching the default directory that was set up when PMW was built.

-testing
    Run in testing mode. A number may follow to control various testing settings.

DIAGNOSTICS AND RETURN CODES

Error messages are written to the standard error stream. The return code is the C return code EXIT_SUCCESS (usually 0) for success, even if there were some warnings, and EXIT_FAILURE (usually 1) otherwise.

EXAMPLES

  pmw myscore
  pmw -format A5 -a5ona4 -pamphlet myscore
  pmw -pdf -s 3 -o quartet-viola.ps quartet.pmw

AUTHOR

  Philip Hazel
  Email local part: Philip.Hazel
  Email domain: gmail.com

Last updated: 19 December 2025
Copyright (c) 2025 Philip Hazel