1. Chords
2. Beams
3. Points, accents and slurs
4. Automatic spacing
5. Transposition

-------------

1. Chords

A chord has two parts: note-part and feature-part.
The note-part contains all notes of the chord with possible accidentals and
octave symbols, and the feature-part contains commands related to, for example,
points, accents, ties and slurs.

In order to implement automatic shifting of notes, one must code the notes
of a chord in either ascending order or decending order.
If any chord violates this rule, a message will appear in the log file.
The feature-part, if it exists, is located in front of the note-part,
and separated by a comma.

  chord = {[feature-part,][note-part]}

I have chosen the names of most new macros for chords to have the
same spelling as those for spacing notes except that the first one or two
letters are in upper case.

Single chords:
  \Wu \Wd \Wh \Hu \Hd \Ha \Qu \Qd \Qa Cu \Cd \Ca \Ccu \Ccd \Cca
  \Cccu \Cccd \Ccca \Ccccu \Ccccd \Cccca

Sequences of chords:
  \WU \WD \WH \HU \HD \HA \QU \QD \QA CU \CD \CA \CCu \CCd \CCa
  \CCcu \CCcd \CCca \CCccu \CCccd \CCcca

I think \Wu and \Wd are needed because sometimes one wants to control
the direction of shifted notes.

What these chord macros can do includes:

* Choose stem direction if it is not specified;
* Shift notes according to stem direction;
* Shift points and accidentals based on the existence of shift notes;
* Choose between \Pt and \Dpt according to voice with auto-spacing \an...\en.

However, these macros can not prevent accidentals crashing into each other,
All accidentals of a chord are horizontally aligned regardless of the location
of the notes they belong to.

How to determine the stem of a chord when it is not specified?
If the note which is farthest from the center staff line is above (or below)
the line, a down (or up) stem will be chosen. If there are two such notes on
different sides of the center staff line, a down stem will be chosen.

-------------

2. Beams

Beams with auto stems
  \Ba \bBa \bbBa \bbbBa        (single beam)
  \Bba \BBa \bBBa \bbBBa       (double beam)
  \Bbba \BBba \BBBa \bBBBa     (triple beam)
  \Bbbba \BBbba \BBBba \BBBBa  (quadruple beam)

Beams with up stems
  \Bu \bBu \bbBu \bbbBu        (single beam)
  \Bbu \BBu \bBBu \bbBBu       (double beam)
  \Bbbu \BBbu \BBBu \bBBBu     (triple beam)
  \Bbbbu \BBbbu \BBBbu \BBBBu  (quadruple beam)

Beams with up stems
  \Bd \bBd \bbBd \bbbBd        (single beam)
  \Bbd \BBd \bBBd \bbBBd       (double beam)
  \Bbbd \BBbd \BBBd \bBBBd     (triple beam)
  \Bbbbd \BBbbd \BBBbd \BBBBd  (quadruple beam)

To replace \tbbu, \tbbd, ...
  \tbba \tbbba \tbbbba

To replace \trbbu, \trbbd, ...
  \trbba \trbbba \trbbbba

To replace \nbbu, \nbbd, ...
  \nbba \nbbba \nbbbba

To change the staff of chords
  \xstaff

To change the stem direction of chords
  \xstem

To change the staff and the stem direction of chords
  \xover

To inidicate which \nst@ff is associated with the lower staff so that \xstaff
knows where to go
  \twostaffs \threestaffs

To specify the slope number for the next auto beam
  \slope

To change the stem length, in unit of beam thickness (for normal size)
  \cutstemlength

To replace \sk, \hsk and \bsk
  \Sk

If the stem direction is unspecified, it will be determined as follows:
first search among all notes associated with the beam for the ones which are
farthest from the center staff line.
if they are above (or below) the center staff line,
a up (or down) stem will be chosen;
if there are two such notes one is above the center staff line and
the other below, a down stem will be chosen.

After the direction of stems is chosen, or if it is specified,
the slope of the beam is estimated based on the highest notes or
the lowest notes, depending on the stem direction,
of the first and the last chords.
The vertical location of the beam is chosen in a way that the shortest stem
has the default length.

The number of beams that a macro produces is the number of upper or lower
case B's in its name starting with the first upper case B.
A beam macro puts its beams at the normal vertical position if its name has
no lower case b.
If there are n lower case b's following the first upper case B in its name,
the macro moves its beams outward by a distance of n beams.
If there are n lower case b's preceding the first upper case B in its name,
the macro moves its beams inward by a distance of n beams.

For example, the shortest stem in \BBa has the defaul length, that in \Bba has
a shorter length, and that in \bBBa has a longer length.

Macros to change stem direction and staff in beam notes have also been coded.
Use \xstaff to change staff, \xstem to change stem direction, and \xover to
change both staff and stem direction (think of cross-over).
Notice that one has to specify a stem direction before using \xstem or \xover.
All these three macros are toggles.
Whether changing of staff ocurrs between between \nst@ff 1 and 2 (for piano)
or between \nst@ff 2 and 3 (for organ) is indicated by including either
\twostaffs or \threestaffs. The default is \twostaffs.

When an auto beam contains \xstem or \xover,
its slope is determined by the reference note of the first chord and the
reference note of the last chord,
where the reference note of a chord is the highest (or lowest) note
if its stem points up (or down).
The vertical location of the beam is chosen in such a way that the
shortest stems on both sides of the beam are of equal length.

Macro \slope to pick a slope number is effective for the next beam only.
Macro \cutbeamstem inside a pair of \notes...\en
is effective until the next | or \en, while they have a global effect outside
a pair of \notes...\en, which is similar to opustex' \maxbeamslope.

At the time of calculating the slope and height of a beam, each chord,
no matter whether it contains a note or a rest, is assumed to be followed by
one \noteskip. To modify this amount, one may use \Sk{r} in the feature-part
of a chord. No other spacing macros is recognized at this scanning stage.
Therefore, in order to compute a beam correctly, make sure
there is exactly one implicit space in each chord, i.e., one should

* Always have some notes or a rest in a chord;
* Never mix notes and rest in a chord;
* Never use \Sk alone in a chord, use it with some notes or a rest.

Examples:

\notes\slope2\Bba{JNLN}|\Ba{c{\Sk2\tbba,e}}\en
\notes\slope2\Bba{JNLN}|\Bba{c{\EEr{-2},}e}\Eer\en

With auto spacing, one does not have all these troubles.
Macro \Sk becomes obsolete. (But \ins kicks in.)
The information about spacing that OpusTeX needs is read from jobname.as2.

Octave symbols in feature-part have no effect outside the feature-part where
they belong to. The reason is that when chords are scanned to determine
the stem direction and the slope and height of the beam, the only things
recognized in feature-parts are \xstaff, \xstem, \xover and \Sk.
Maybe the same restriction should be applied to sequence of chords too.

-------------

3. Points, accents and slurs

Points
  \Pt \Ppt \Dpt \Dppt

Accents at the opposite side of stems
  \Fz \St \Stpo \Po \Ppz \Sf

Accents above the chords
  \Ufz \Ust \Ustpo \Upo \Uppz \Usf

Accents below the chords
  \Dfz \Dst \Dstpo \Dpo \Dppz \Dsf

Slurs (partially working)
  \Isluru \Islurd \Tsluru \Tslurd

Use point and accent macros in feature-part of a chord without any parameter.
An accent macro not specifying the direction (up or down) puts an accent at
the opposite side of the stem.
Right now a chord can have no more than one accent.

Use slur macros in the feature-part of a chord with one parameter, which is
the reference number of the slur.
Right now slur macros only work for stem slurs.

-------------

4. Automatic spacing

To replace \notes
  \an

To insert space for all staffs
  \ins

Non-lifted rests used with \an..\en
  \Wr \Hr \Qr \Er \Eer \Eeer \Eeeer

Lifted rests used with \an..\en (followng by an integer):
  \Liftwr \Lifthr \Liftqr \Lifter \Lifteer \Lifteer \Lifteeer

Multivoice
  / \multivoice \nomultivoice

My solution to auto spacing is to use a non-TeX program auto.c:

  TeX => auto => TeX => Opusflex => TeX

To use autospacing, code all notes and rests in a pair \an...\en instead of
\notes...\en, and use only new macros for chords and rests described in the
previous sections to ensure proper spacing following each chord and rest.

The program auto.c inputs jobname.as1 and outputs jobname.as2.
It checks whether all notes and rests in each voice within \an...\en sum up
to the same time value, and gives warnings if they do not match.

To insert a space for all staffs, use \ins{r} in only one staff (or voice),
where dimen r is in unit of \noteskip.

If there are more than one voice in a staff, use / to start a new voice.
Macros \multivoice and \nomultivoice change \catcode of /.
Multivoice macros work without auto spacing as well.
With auto spacing one should code low voice before high voice, so that \Pt
in the low voice becomes \Dpt automatically.

If the notes in a voice do not fill the bar, and one does not want to use
more than one pair of \an..\en for the bar, then one can use empty chord
\Qa{\relax,} to fill the gap of a quarter note, for example.

Auto-spacing does not work with triplets yet.

-------------

5. Transposition

To replace \transpose, but in half steps instead of staff line
  \Transpose

To replace \generalsignature
  \Generalsignature

To replace \setsign
  \Setsign

To choose between signatures +5 and -7, +6 and -6, +7 and -5
  \transposechoice

The purpose of these new macros is to simplify the transposition of a piece
with many key changes so that one does not need to change the key at each
\setsign.
Use \Transpose, Generalsignature and \Setsign exactly the same as their
counterparts in OpusTeX, except that the paramter of \Transpose is the
number of half steps to be transposed.
Use either + or - as each of the three parameters of \tranposechoice to
indicate one's preference, and any other character is ignored.
The default is ++-,
which means that if the signature after tranposition can be either +5 or -7,
signature +5 will be used, and signatures +6 and -5 will be selected over
-6 and +7 respectively.

-------------