chiark - git - mdw - mup/blob - mup/docs/mup.1

   1 .TH mup 1 "Sep 25, 2006" "Arkkra Enterprises"
   2 .SH NAME
   3 .PP
   4 mup - music publisher
   5 .SH SYNOPSIS
   6 .PP
   7 \fBmup\fP [\fB-c\fP\fIN\fP] [-C] [\fB-d\fP\fIN\fP] [\fB-D\fP \fIMACRO[=macro-def\fP]]
   8 [\fB-e\fP \fIerrfile\fP] [-E]
   9 [\fB-f\fP \fIoutfile\fP] [\fB-F\fP] [\fB-m\fP \fImidifile\fP] [\fB-M\fP] [\fB-o\fP \fIpagelist\fP] [\fB-p\fP\fIN\fP]
  10 [\fB-v\fP] [\fB-x\fP \fIN\fP[,\fIM\fP] [\fIfile...\fP]
  11 .SH DESCRIPTION
  12 .PP
  13 Mup is a program for producing printed music.
  14 There is an optional companion program called Mupmate
  15 that provides a more graphical user interface on top of Mup,
  16 but this manual page describes the command line interface.
  17 The Mup User's Guide should be consulted for details of the format of the
  18 input file.
  19 Options include:
  20 .TP
  21 \fB-c\fP \fIN\fP
  22 Combine consecutive measures of all rests or spaces into multirests (multiple
  23 measures of rest printed as a single measure, with the number of measures of
  24 rest printed above the staff).
  25 Any time there
  26 are \fIN\fP or more measures in a row that consist entirely of rests or spaces,
  27 they will be replaced by a multirest. The combining of measures
  28 stops when there is a visible staff that contains notes,
  29 lyrics, or other musical symbols,
  30 when there are parameter changes on a visible staff or in score context, or
  31 when there is a bar line other than an ordinary or invisible bar.
  32 This option is most likely to be useful when printing a subset of staffs,
  33 where the particular staff(s) you are printing have long periods of rests.
  34 (See the -s option.)
  35 .TP
  36 \fB-C\fP
  37 This option is only used in connection with the -E option.
  38 It specifies that comments
  39 are to be passed through rather than deleted.
  40 .TP
  41 \fB-d\fP \fIN\fP
  42 Print debugging information. \fIN\fP is a bitmap.
  43 .RS 4
  44 .TP
  45 1
  46 parse phase information
  47 .TP
  48 2
  49 high level parse phase tracing
  50 .TP
  51 4
  52 low level parse phase tracing
  53 .TP
  54 8
  55 reserved
  56 .TP
  57 16
  58 high level placement phase tracing
  59 .TP
  60 32
  61 low level placement phase tracing
  62 .TP
  63 64
  64 reserved
  65 .TP
  66 128
  67 contents of the main internal list
  68 .TP
  69 256
  70 high level print phase tracing
  71 .TP
  72 512
  73 low level print phase tracing
  74 .RE
  75 .IP
  76 \fIN\fP can be specified in decimal, octal
  77 (by using a leading zero), or hex (by using a leading 0x).
  78 This information is intended for debugging of
  79 \fBMup\fP itself and thus is not likely to be of use to the average user.
  80 .TP
  81 \fB-D\fP \fIMACRO[=macro-def]\fP
  82 Define the macro \fIMACRO\fP. The
  83 macro name must consist of upper case letters,
  84 digits, and underscores, beginning
  85 with an upper case letter. The \fImacro_def\fP is optional, and gives the
  86 text of the macro. If it contains any white space or other special characters,
  87 it must be quoted (if quoting is supported by your operating system or shell).
  88 .TP
  89 \fB-e\fP \fIerrfile\fP
  90 Place error messages into \fIerrfile\fP instead of writing them to the standard
  91 error output stream.
  92 .TP
  93 \fB-E\fP
  94 Rather than produce PostScript or MIDI output, just expand macros and
  95 includes, and write the result to the standard output stream.
  96 Comments in the input are deleted, unless the -C option is also specified.
  97 .TP
  98 \fB-f\fP \fIoutfile\fP
  99 Place the output into \fIoutfile\fP instead of writing it to the
 100 standard output.
 101 .TP
 102 \fB-F\fP
 103 This is like the \fB-f\fP option, except the name of the output file is
 104 derived from the name of the Mup input file. If the name of the Mup input
 105 file ends with a ".mup" suffix, the generated PostScript output
 106 file will end with a ".ps" suffix instead.
 107 If the name of the Mup input file ends with
 108 a ".MUP" suffix, the PostScript file will end with a ".PS" suffix.
 109 Otherwise, a ".ps" suffix will be appended to the end of the Mup
 110 input file name. If multiple input files are listed, the last is used.
 111 If none are specified (input is read from standard input),
 112 the name "stdin.ps" will be used for the output file.
 113 .TP
 114 \fB-m\fP \fImidifile\fP
 115 Instead of generating PostScript output,
 116 generate standard MIDI (Musical Instrument Digital Interface) output,
 117 and put it in \fImidifile\fP.
 118 This option also causes the macro "MIDI" to become defined.
 119 .TP
 120 \fB-M\fP
 121 This is like the \fB-m\fP option, except the name of the MIDI file is
 122 derived from the name of the Mup input file. If the name of the Mup input
 123 file ends with a ".mup" suffix, the generated MIDI file will end with
 124 a ".mid" suffix instead. If the name of the Mup input file ends with
 125 a ".MUP" suffix, the MIDI file will end with a ".MID" suffix.
 126 Otherwise, a ".mid" suffix will be appended to the end of the Mup
 127 input file name. If multiple input files are listed, the last is used.
 128 If none are specified (input is read from standard input),
 129 the name "stdin.mid" will be used for the MIDI file.
 130 .TP
 131 \fB-o\fP \fIpagelist\fP
 132 Print only the pages given in \fIpagelist\fP. The \fIpagelist\fP can be
 133 a comma-separated list of numbers or ranges, where a range is two numbers
 134 separated by a dash. For example, -o1,7-9,12-14 would print pages 1, 7, 8,
 135 9, 12, 13, and 14. Pages will be printed in the order given.
 136 They need not be in order, and a page
 137 number may be included more than once.
 138 Alternately, the \fIpagelist\fP can be the special
 139 keyword "odd" or "even" which will cause all odd or even numbered pages
 140 to be printed. This may be useful if you have a printer that only makes
 141 single-sided copies, but you wish to print Mup output double-sided. You could
 142 print odd-numbered pages, then turn the paper over and feed the pages
 143 through again for the even-numbered pages.
 144 .TP
 145 \fB-p\fP\fIN\fP
 146 Start numbering pages at \fIN\fP instead of at 1.
 147 If \fB-o\fP and \fB-p\fP are used together, the page numbers given in the
 148 \fB-o\fP\fIpagelist\fP must be the printed page numbers. For example, if you
 149 use -p10 and want to print just the second page,
 150 you would need to specify -o11.
 151 .TP
 152 \fB-r\fP
 153 Print a copy of the Mup shareware registration form to the standard output.
 154 .TP
 155 \fB-s\fP\fIstafflist\fP
 156 Only print the staffs that are included in \fIstafflist\fP. This can be a
 157 comma-separated list of staff numbers or ranges, such as "1,5" or "1-3,7-8"
 158 To further restrict to a single voice on a staff, add \fBv\fP\fIN\fP where
 159 \fIN\fP is the voice number (1, 2, or 3), after the staff, as in "2v1,5v2"
 160 You can't specify a list or range for voices;
 161 if you only want to make two out of three voices visible,
 162 you have to specify them separately, like "1v2,1v3".
 163 No spaces are allowed in the list.
 164 .TP
 165 \fB-v\fP
 166 Print the Mup version number and exit. This manual page is for version 5.3.
 167 .TP
 168 \fB-x\fP\fIM,N\fP
 169 Extract measures \fIM\fP through \fIN\fP of the song. This allows you to print
 170 or play a part of a song. The comma and second value are optional;
 171 if not specified, the default is to go to the end of the piece.
 172 Positive values specify the number of measures from the beginning of the piece,
 173 while negative values are relative to the end, with -1 referring to the
 174 last measure of the song.
 175 So -x1,-1 means the entire song, if the song doesn't have a pickup measure.
 176 If the song has a pickup measure, that is specified by 0.
 177 So for a song with a pickup, -x0,-1 would mean the entire song,
 178 and -x0,0 would mean just the pickup measure.
 179 As other examples, -x-1,-1 means just the final measure of the song,
 180 -x2 means starting after the first full measure, -x3,4 means only
 181 measures 3 and 4, and -x6,6 means just measure 6.
 182 The starting measure is not allowed to be inside an ending.
 183 A common use for this option might be to generate a MIDI file
 184 for just a few measures. For example, if you were
 185 trying to tweak tempo values for a ritard in the last 2 measures of a song,
 186 you could use -x-2 to listen to just those measures.
 187 .PP
 188 The options, if any, can be followed by one or more \fIfiles\fP in Mup format.
 189 If no \fIfiles\fP are specified, standard input is read.
 190 If several \fIfiles\fP are listed, they are effectively concatenated together
 191 and treated as one big file. Since there are some things (such as header
 192 and footer) that are only allowed to occur once, if you have several independent
 193 pieces, mup should be called on each individually rather than trying to
 194 print them all with one command.
 195 If a specified file does not exist, and its name does not already end
 196 with .mup or .MUP, then Mup will append .mup to the specified name and
 197 attempt to open that.
 198 .PP
 199 On most systems, the environment variable MUPPATH can be set
 200 to a list of paths in which to look for 'include' files.
 201 The components are separated by a colon on Unix or Linux systems, and by a
 202 semicolon on systems with DOS-like file naming conventions.
 203 .PP
 204 For more debugging, in addition to the -d option,
 205 if the environment variable MUP_BB is set to "bcfghnsu" or any subset
 206 of those letters, the generated output will include "bounding
 207 boxes" for the things Mup internally calls bars (b), chords (c), feeds (f),
 208 grpsyls (g), header/footer and top/bottom (h),
 209 notes (n), staffs (s), and stuff (u).
 210 While this is intended for use in debugging Mup itself, it may also
 211 help you understand why Mup places things the way it does,
 212 since in general, Mup only allows bounding boxes to overlap according
 213 to specific rules. If viewed with a color PostScript viewer (not mupdisp),
 214 these boxes will be in color.
 215 .SH "SEE ALSO"
 216 .PP
 217 gs(1), mkmupfnt(1), mupdisp(1), mupmate(1), mupprnt(1).
 218 .br
 219 Mup \(em Music Publisher User's Guide