summaryrefslogtreecommitdiff
path: root/support/autosp/doc/autosp.1
diff options
context:
space:
mode:
Diffstat (limited to 'support/autosp/doc/autosp.1')
-rw-r--r--support/autosp/doc/autosp.1303
1 files changed, 303 insertions, 0 deletions
diff --git a/support/autosp/doc/autosp.1 b/support/autosp/doc/autosp.1
new file mode 100644
index 0000000000..a4a24c6827
--- /dev/null
+++ b/support/autosp/doc/autosp.1
@@ -0,0 +1,303 @@
+.\" This manpage is licensed under the GNU Public License
+.TH AUTOSP 1 2019-08-27 "" ""
+
+.SH NAME
+autosp \- preprocessor to generate note-spacing commands for MusiXTeX scores
+
+.SH SYNOPSIS
+.B autosp
+.RB [ \-v\ |\ \-\-version\ |\ \-h\ |\ \-\-help ]
+
+.B autosp
+.RB [ \-d\ |\ \-\-dotted ]
+.RB [ \-l\ |\ \-\-log ]
+.IR infile [\fR.aspc\fP]
+.RI [ outfile [ \fR.tex\fP ]]
+
+.SH DESCRIPTION
+This program makes it easier to create MusiXTeX scores by converting (non-standard) commands of the
+form \\anotes ... \\en into one or more conventional
+note-spacing commands (\\notes \\Notes \\NOtes ...),
+determined by the actual note values, with \\sk spacing commands inserted as necessary.
+The coding
+for an entire measure can be entered one part at a time,
+without
+concern for note-spacing changes within the part or spacing requirements of other parts.
+
+For example, if applied to
+.nf
+
+ \\anotes\\qa J\\qa K&\\ca l\\qa m\\ca n\\en
+
+.fi
+.B autosp
+generates
+.nf
+
+ \\Notes\\qa J\\sk\\qa K\\sk&\\ca l\\qa m\\sk\\ca n\\en
+
+.fi
+Typically,
+an
+\\anotes command generates several conventional
+note-spacing commands.
+
+If the
+.I infile
+argument
+does not have an .aspc extension, input is taken from
+.IR infile .aspc
+if that file exists.
+
+If the
+.I outfile
+argument does not have a .tex extension, output is sent to
+.IR outfile .tex.
+If no
+.I outfile
+argument is provided, output will go to
+.IR infile .tex
+(or to
+.IR infile .ltx
+if a \\documentclass declaration is encountered).
+
+For
+\\anotes commands,
+line breaks and spaces may precede note segments, allowing more flexible source formatting;
+the line breaks and spaces will be elided from the output.
+
+For example,
+.nf
+
+ \\anotes
+ \\ibl0K0\\qb0K\\nbbl0\\qb0{.K}\\tbbbl0\\tbbl0\\tql0L&
+ \\ibbl1m{-2}\\qb1{.m}\\tbbbl1\\tbbl1\\qb1l\\tql1k\\en
+
+.fi
+is acceptable and generates
+.nf
+
+ \\notesp\\ibl0K0\\qb0K&\\ibbl1m{-2}\\qb1{.m}\\en
+ \\nnotes\\sk&\\tbbbl1\\tbbl1\\qb1l\\en
+ \\notesp\\nbbl0\\qb0{.K}&\\tql1k\\en
+ \\nnotes\\tbbbl0\\tbbl0\\tql0L&\\sk\\en
+
+.fi
+
+
+If the
+.B \-l
+( \fB\-\-log\fP ) option is used, a very detailed log
+.IR infile .alog
+is generated.
+
+If the
+.B \-d
+( \fB--dotted\fP )
+option is used,
+.I dotted
+beam notes of the form \\qb{\fIn\fP}{\fB.\fP\fIp\fP} are
+.I not
+given extra space;
+it is assumed that the subsequent note will be shifted
+by
+a \\roff-like command
+or a spacing command such as \\qsk or \\hqsk.
+Commands of the form \\qlp{\fIp\fP}, \\qlpp{\fIp\fP}, ..., \\qpb{\fIn\fP}{\fIp\fP} and
+\\qppb{\fIn\fP}{\fIp\fP} are always spaced
+as indicated.
+
+If there is a single staff, consecutive whole-bar rest bars
+are merged into a multi-bar rest. Bar-centered rests can be
+coded using the standard \\def\\atnextbar notation but
+the non-standard command \\Cpause in a note segment also generates a
+bar-centered rest.
+
+Spacing commands \\sk and \\bsk in the source are discarded,
+but not "small" skips \\hsk, \\qsk, \\tqsk, \\hqsk or \\qqsk,
+or the small "backward" skips \\hbsk, \\bqsk, \\btsk, or \\bhsk.
+Moreover,
+non-standard commands
+\\QQsk, \\HQsk \\TQsk and \\Qsk in the source generate "global" skips; i.e., the effect of \\qqsk, \\hqsk, \\tqsk or \\qsk, respectively, in
+.I every
+staff. These ensure that staffs remain synchronized if additional spacing is needed in any staff(s).
+
+Global skips may also be obtained within collective-coding sequences by using
+up to four successive commas
+to get the effects of \\QQsk, \\HQsk, \\TQsk or \\Qsk, respectively.
+Global skips \\tqsk (or, for double-flats, \\qsk) are
+automatically inserted before accidentals ('^', '_', '=', '<', '>') on collective-coding notes
+(except when the preceding note is "virtual"; i.e., a skip).
+If this automatic additional spacing is
+.I not
+wanted in some context, it may be avoided by
+replacing
+the accidental in the collective-coding sequence
+by
+any of the
+.I explicit
+accidental commands: \\sh, \\fl, \\na, \\smallsh, \\bigsh, etc.
+If the automatic spacing is insufficient, the spacing may be increased by adding sufficient commas or
+using a conventional notes command instead of \\anotes.
+
+
+A note segment can be completely empty, but if a note segment should start
+with or contain a "space," the note-value
+of that space must be made explicit with a command of the
+form \\ha{*}, \\qa{.*}, \\qa{*}, \\ca{*}, etc.
+
+From version 2017-06-14, the effects of \\TransformNotes calls are implemented by the
+.B autosp
+pre-processor. This
+enables use of
+musixlyr in
+.B autosp
+scores; musixlyr.tex
+is incompatible with the
+musixtnt.tex
+implementation of \\TransformNotes.
+
+All other conventional MusiXTeX commands are output exactly as given in the input.
+
+
+.SH OPERATION
+
+.B autosp
+determines the spacing for ordinary notes from the note
+commands themselves; for example,
+.TP 3
++
+\\qa, \\qu, \\ql, \\qp result in
+\\NOtes;
+.TP 3
++
+\\ca, \\cu, \\cl, \\ds result in \\Notes;
+.PP
+and so on.
+
+The spacing for
+.IR beamed
+notes is determined by the beam
+multiplicity, so that \\ib... results in \\Notes, \\ibb... results in
+\\notes, etc.
+
+Collective coding of note sequences (including accidentals and dots) is handled
+by expanding the sequence
+into a sequence of individual note commands.
+
+
+.B autosp
+scales notes by the relevant instrument-size value.
+
+.SH LIMITATIONS
+
+.B autosp
+assumes that & and | (rather than \\nextinstrument and \\nextstaff) are used to separate instruments and staffs.
+
+
+Appoggiaturas and grace notes are recognized by the use of \\tinynotesize; note-spacing
+of 1.45\\elemskip is used. If this isn't suitable and can't be corrected with a small skip, a
+\\vnotes command with any desired spacing can be used.
+
+.B autosp
+supports
+.I x-tuplets
+introduced using \\xtuplet{\fIx\fP}
+or \\xxtuplet{\fIx:y\fP}
+and
+.I triplets
+introduced
+using any of the following commands (regardless of any re-definition of \\txt or \\tuplettxt):
+.nf
+
+ \\triolet
+ \\uptrio
+ \\downtrio
+ \\uptuplet
+ \\downtuplet
+
+.fi
+.B autosp
+assumes that an x-tuplet is to be played in
+(\fIx\fP\-1)/\fIx\fP
+of the apparent x-tuplet duration.
+So, for example, a triplet in eighths is assumed to be played in the time of one quarter note.
+If this assumption
+isn't valid, the x-tuplet must
+be coded explicitly using a suitable \\vnotes command; see the first
+measure of barsant2.aspc for an example of a non-standard x-tuplet: a 5-tuple
+of 64th notes with an intended duration
+of
+.I six
+64ths.
+
+In some polyrhythmic scores, the \\txt numeral may be displaced, even if the notes
+themselves are correctly spaced. In these cases, it is possible to suppress
+the normal output of \\txt by using the non-standard commands \\Triolet (no arguments)
+or \\Xtuplet{k}\\
+and placing a numeral at the correct location using \\zcn (i.e., \\zcharnote).
+
+.B autosp
+can deal with simultaneous x-tuplets in multiple staffs provided the x values and
+total note durations are identical.
+
+In some baroque scores, particularly by J.S. Bach, a beamed sixteenth note is vertically aligned
+with
+the third note of a triplet of eighth notes in another staff (implying that they should
+be sounded simultaneously); e.g.,
+.nf
+
+ \\ibl0L0\\qb0{.L}\\tqql0L
+
+.fi
+would be played as if notated
+.nf
+
+ \\uptrio{b}10\\ql L\\hroff{\\cl L}
+
+.fi
+The following coding will align the beamed sixteenth note
+with the third note of a triplet in another staff:
+.nf
+
+ \\ibl0L0\\qb0{.L}\\hbsk\\tqql0L
+
+.fi
+and, similarly, for triplets of sixteenth notes:
+.nf
+
+ \\ibbu0J0\\qb0{.J}\\hbsk\\nqqqu0J\\qb0{.J}\\hbsk\\tqqqu0J
+
+.fi
+Generally, user-defined macros are not processed or expanded; however, definitions of the form
+.nf
+
+ \\def\\atnextbar{\\znotes ... \\en}
+
+.fi
+generate definitions that do take account of \\TransformNotes.
+
+All staffs are assumed to have the same meter; see kinder2.aspc for
+an example of how to work around this.
+
+.B autosp
+may not be effective for music with more than one voice in a single staff. It might be
+advisable to use a separate staff for each voice, to avoid \\anotes when necessary,
+or to omit certain voices
+initially and add them into the resulting TeX file.
+
+.SH EXAMPLES
+See files quod2.aspc, kinder2.aspc, geminiani.aspc and barsant2.aspc for scores suitable for input to
+.BR autosp .
+The program
+.B tex2aspc
+can be used to convert "legacy" MusiXTeX scores to .aspc format.
+
+.SH SEE ALSO
+.BR msxlint (1)
+.BR tex2aspc (1)
+.PP
+musixdoc.pdf
+
+.SH AUTHOR
+This program and manual page were written by Bob Tennent <rdt@cs.queensu.ca>.