Change Log for Philip's Music Writer (Linux/Unix version)
---------------------------------------------------------


Version 4.22 re-release
-----------------------

There are no changes whatsoever to the code, just to the packaging and the 
documentation:

1. Added support for DESTDIR to the Makefile.

2. Reformatted the specification using the latest version of SDoP, which turns 
   cross-references and index page numbers into clickable links in the PDF.
   
3. Added some newly contributed files to the contrib directory. 


Version 4.22
------------

 1. Get rid of an "uninitialized variable" warning in paginate.c.

 2. Added \..\ for staccatissimo, using new characters 194, 195 in the font,
    which are teardrop shapes (one inverted). As part of this, the code for
    parsing accents and ornaments has been reorganized to be more table driven.

 3. When a syntax error is output, the file name used to be included with the
    line number only for included files, but now it is always included for the
    benefit of people who use the "compilation mode" of Emacs (or similar
    feature in other environments). This mode makes use of the error messages
    and is able to open the file at the place where the error was found during
    the compilation, but of course it needs the file name.

 4. Tidied up the copyright string, which for some crazy reason appeared twice
    in the source code. Added "Built" to the date that is shown by -V etc.
    
 5. When righttoleft was set with -eps, the bounding box values in the EPS file 
    were incorrect whenever the magnification was not 1.0.
    
 6. When a layout directive caused a system to be squashed to fit onto a line,
    underlaid words could crash into each other because of the squashing. (Bars
    are initially spaced to avoid underlay crashes, but this did not take
    account of squashing.) This problem has been alleviated by respacing lines
    when the squashing is above a certain threshold - in the same way as
    happens when systems are stretched a lot. For backwards compatibility on
    old files, a new directive called stretchrule has been invented, with
    values 0, 1, or 2; oldstretchrule (dating from a much earlier change) is
    equivalent to setting stretchrule to 0. The default is 2, and 1 is the
    situation prior to this change.
    
 7. Related to 6, when PMW was adjusting note spacing so that underlaid
    syllables did not collide, it was ignoring leading and trailing #
    characters, treating them as spaces (which of course, they print as).
    However, this means that using # to move a syllable left or right did not
    work as expected. It now ignores leading and trailing spaces only if they
    are actual space characters.
    
 8. Updated the AFM files in the fontmetrics directory to later versions that
    include additional characters in current versions of the text fonts.  
    
 9. When a bar was not of the correct length, the error message always said it 
    was too long, even when it was too short. I am amazed nobody has noticed 
    this bug before; it was introduced by change 30 of version 4.20.
    
10. Allow /u, /d, /l, and /r in strings for drawing calls. 

11. Add -MF <directory> to allow overriding of the directory in which the
    music fonts are stored.
    
12. Process the files in the testdist directory with -includefont (requiring 
    the new -MF option) so that the output can be directly viewed in 
    environments where the fonts are not installed.
    
13. Added ||| to print an "end-of-piece" barline in the middle of a piece. 

14. Added /), /(, /b, and /B for bracketing expression marks and ornaments.


Version 4.21
------------

 1. Changed an (int) cast to (long int) in the ps.c source, in order to get
    rid of a compiler warning in 64-bit environments.

 2. Re-organized the rdargs module (argument decoding) to get rid of some
    32-bit-isms that caused crashes and/or weird behaviour in 64-bit
    environments.

 3. Added the midifornotesoff heading directive.


Version 4.20
------------

 1. Carried out a general spring clean of the code, tidying up comments,
    removing redundant code left over from the Risc OS days, and also re-
    arranging some of the control logic.

 2. The code for "draw" features used an array of ints for the drawing engine
    implementation, casting addresses to ints for handling text and other
    pointers. This does not work in 64-bit environments. It has now been
    changed to use a union of int and void * for these items. I also added
    a "type" to data items so that it can be checked for the various operators
    (previously there was no check). This has made it possible to upgrade
    "pstack" so that it correctly shows text strings and says "code-block"
    instead of printing the address.

 3. The store (memory) handling functions also used addresses cast to ints.
    This is no longer the case.

 4. Fixed a bug in the string width measuring code which could have given
    wrong answers in cases where non-standard fonts were in use.

 5. A related bug to (3) could have caused trouble when small caps fonts were
    used.

 6. Fixed bugs thrown up by running the tests under valgrind. A couple of
    uninitialized variables, and one text string overrun while calculating a
    length for centering.

 7. Some of the output differed in the third decimal place when the tests
    were run under valgrind. This was connected with floating point arithmetic,
    in particular, that used for drawing fancy types of slur. Some massaging of
    the code, especially in the way floats are converted back to ints, has been
    done, and now the tests produce the same output when run native or under
    valgrind. This was a long and tedious slog.

 8. There was a typo in the AFM file for the PMW-Alpha font: character 222 had
    a width of 0.75 which should really be 0.15.

 9. The documentation has been converted to a new production system, and the
    opportunity has been taken to thoroughly revise it.

10. Two MIDI bugs have been fixed:

    (a) When a chord was tied to a subsequent chord with more notes than the
        first chord, for example, (cd)_(cde), the MIDI generated for the
        additional notes was incorrect, often causing a long period of silence
        with the note played minutes later.

    (b) When a MIDI parameter, for example, the voice, was changed in mid-part
        by a directive such as [midichannel 1 midivoice "flute"], and playing
        was started after this directive, using the command line option
        -midibars, the change of parameter was not heeded.

11. When overlay was used with chords, the level was incorrectly computed,
    taking into account only the lowest note of the chord instead of the
    highest. Overlay has also been raised by one point.

12. A hairpin that continued over more than one line boundary caused PMW to
    crash. This could accidentally be provoked by terminating a '>' hairpin
    with '<' or vice versa.

13. Change 4.01/5 removed "a4" from the PostScript output because it was
    causing trouble with GhostScript. It seems that nowadays it is no longer
    an issue, and is needed for conversion to PDF, especially if the sheet
    size is something else, for example, A3. The action now is to include a
    known paper size, set from the "sheetsize" directive (default A4), between
    %%BeginPaperSize and %%EndPapersize lines. If the dimensions are
    independently set using sheetdepth or sheetwidth, this does not happen.

14. Add support for small note heads (to show optional notes) with the note
    option \sm\. All this does is to reduce the size of the note head.

15. Added "letter" to the list of recognized paper sizes for the "sheetsize"
    directive.

16. The heading directive "stavespacing 0/xxx" was not being diagnosed as an
    error.

17. If [sshere] or [ssnext] were specified on stave 0, or with "0" as a stave
    number (meaning "all staves"), and a relative change was specified (e.g.
    [sshere 0/+20]) the change was interpreted as absolute instead of relative.

18. Give a warning if the same stave is mentioned more than once in a
    stavespacing, [sshere], or [ssnext] directive.

19. Some of the warning messages were missing "Warning:" at the start.

20. The "bar length is different to the staves above" message has been changed
    from a serious error (which prevents PMW from generating output) to a
    warning - some attempt at the output will be made (see also 31).

21. No diagnosis was previously given for an unsupported code point in text.
    It was silently replaced. A warning message is now given.

22. The internal formatting function that is used to generate error messages
    went wrong if more than one substitution of a width was present (previously
    there were no cases of this, so the bug didn't show).

23. Added six characters to the PMW-Music font:

      270 184 0.0   ledger2       a ledger line that is 2/3 thicker
      275 189 0.424 halfsharp1    half sharp, Egyptian style
      276 190 0.6   halfsharp2    half sharp, Turkish style
      277 191 0.5   halfflat1     half flat, Egyptian style
      300 192 0.5   halfflat2     half flat, Turkish style
      301 193 0.6   icomma        inverted comma, for right-to-left music

24. Added the ledgerstyle directive.

25. Added some simple support for half sharps and half flats, and the
    halfsharpstyle and halfflatstyle directives. There is no MIDI support.

26. Added the printkey directive.

27. Added the righttoleft directive (probably incompletely).

28. Changed -F so that it specifies an additional fontmetrics directory, not
    the only one.

29. Fixed a couple of small bugs relating to the handling of characters in
    text strings with codes greater than 127 in the Music font.

30. Fixed a problem with duplets and other irregular note groups that caused
    (for example) {GG} and {3/2GG} in 3/2 time to be treated differently, when
    of course they should be the same. There was also another bug that happened
    when very short notes were involved in certain kinds of irregular groups;
    PMW complained about bars being too long or too short by very small
    fractions of a crotchet. These fixes have also tidied up some other
    irregularities in this area; the documentation now tries to explain it all
    better. There may be differences in the way some of the rarer groupings are
    handled.

31. The "bar length is different to the staves above" message was given twice
    if it occurred in the first bar of a system other than the first, because
    such bars are measured twice (once for the previous system, to discover
    that it doesn't fit).

32. Fixed some cases when the bounding box of EPS output was incorrect. The
    cases all involved text.


Version 4.12
------------

 1. Transposing the key/chord name in a string such as "\tCm9" up by one
    semitone caused the string to be mangled and an incorrect error message to
    be generated, whereas other strings such as "\tCm11" worked fine. (This was
    a buffer length error.)

 2. Transposing a key/chord name in a heading line did not always work
    correctly. For example, transposing Cm (C minor) up by one semitone
    resulted in D$m (D-flat minor) instead of C#m (C-sharp minor), even if the
    movement's key signature preceded the heading line. This transposition now
    works as long as the key signature is defined before the heading that
    contains the transposition.

 3. Code tidies to avoid compiler warnings related to string signedness.

 4. The midistart directive was in the code (from the old Acorn version) but
    was not documented, and didn't work as expected because no time deltas were
    written to the file. All the events in the midistart data are now preceded
    by a zero delta so that they happen at the start of playing, and the
    directive is documented.


Version 4.11
------------

 1. The sorting of MIDI events was not quite as intended, leading to occasional
    cases where a repeated note was turned on for the second time before
    (rather than after) being turned off (at the same point in time). Some MIDI
    players seem to "do the right thing" with this, but apparently others do
    not. The sorting has been mended.

 2. A new character has been added to the PMW-Music font. Its number is 183
    (decimal) or 267 (octal). The character is an "x" that is suitable for
    printing at the head of a guitar grid to indicate a string that is not
    played. Like the open and closed circles, its typographic width is exactly
    right to move the printing point on to the next guitar string position.

 3. The heading directives playtempo, playtranspose, and playvolume, and the
    stave directives playtranspose and playvolume have been given synonyms with
    "play" replaced by "midi" because the old names (which originally referred
    to MIDI and non-MIDI playing) are not longer sensible. They are, however,
    retained for backwards compatibility.


Version 4.10
------------

 1. A major new feature: text strings are now interpreted as UTF-8 character
    strings using the Unicode encoding for non-Music and non-Symbol fonts
    (strictly, fonts that use the Adobe standard encoding by default). For
    backwards compatibility, a byte with a value greater than 127 that cannot
    form part of a valid UTF-8 sequence is interpreted as a Unicode character
    with its byte value. This change is almost backwards compatible. See the
    documentation for exact details.

 2. PMW could crash for certain command lines because a vector used during
    argument decoding wasn't big enough. (The number of possible options has
    increased recently.)

 3. PMW crashed if the quoted string was missing from a "heading" directive.


Version 4.07
------------

 1. Fixed some errors in the PMW-Music.afm file. These did not affect the
    running of PMW, but could cause trouble when using the PMW-Music font with
    other applications.

    (i)  The "B" for the bounding box was missing in all but the first
         character.

    (ii) Some semicolons were not preceded by a space. This is not incorrect,
         as far as I can tell, but I had a report that the afm2tfm program
         didn't like it.

 2. The Makefile contained just "RunTests" for running the tests; it should be
    "./RunTests".

 3. Changes to the PMW-Music.pfa Postscript font:

    (i)  There was a typo in the data for the "diminished chord sign" character
         (character 181) - "hlineto" instead of "hmoveto". This didn't seem to
         bother GhostScript or PostScript printers, but the "fontforge" utility
         noticed it and complained. (Note: fontforge has other problems with
         the font, which I have not resolved.)

    (ii) I have increased the thickness of the minim notehead by a small amount.

 4. There is a new command line option -nowidechars (-nw) which stops PMW from
    using the 100-point wide stave characters when printing staves. Instead,
    staves are constructed entirely from the 10-point wide characters. This
    option is provided because it seems that some PostScript interpreters
    cannot deal correctly with the very wide characters. Using the standard
    5-line stave, a 310-point stave is normally printed as the string FFFC.
    With the new option, it is printed as CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC.

 5. A simple facility for specifying default options has been created. When
    PMW starts up, it looks in the user's home directory for a file called
    .pmwrc. If this file exists, its contents are read and used to modify the
    PMW command line. White space (spaces, tabs, or newlines) in the file are
    used to separate items. Each item is added to the command line, before the
    given arguments. Thus, for example, if you always want to make use of the
    -nowidechars option, all you need to do is to create a .pmwrc file that
    contains

      -nowidechars

    and the effect is as if you type "-nowidechars" immediately after "pmw"
    every time you run it. If you insert an option that requires data, the data
    item must also be given in the .pmwrc file. For example, the file might
    contain

      -midi /usr/tmp/pmw.midi

    if you always want to create MIDI output. Omitting the file name causes an
    error.

    Note that PMW does not allow options to be repeated, so if an option is
    present in the .pmwrc file, it cannot also be given on the command line.
    There is no way to override individual options that are set in the .pmwrc
    file. However, if the first option on the command line is "-norc", the file
    is not used at all.

 6. A new option, -includefont, is provided to cause 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 font(s) for GhostScript (or any other display program) to
    find. However, it does mean that each PMW output file is bigger by 37K for
    PMW-Music and 31K for PMW-Alpha.

 7. New options -duplex and -tumble are provided to set the duplex and tumble
    printing options in the PostScript output.

 8. A semicolon that did not immediately follow a beamable note was ignored.
    (Way back in pre-history, space was the beam separator, and semicolon was
    needed as a general separator, but this changed a very long time ago.) This
    meant that errors such as "b-b-[endslur];" were not diagnosed, though if a
    comma were used instead, there would be an error. I have now removed the
    use of semicolon as a general separator - hopefully it is rarely used - and
    stuck in explicit diagnostics for misplaced semicolons and commas.

 9. Fixed an extremely obscure bug that caused the loss of some ties in a chord
    when the "p" facility was used. For example, for this sequence:

       (#a`-d-)_ p_ P+._ | (A`+.D+.) |

    one tie was lost between the final two chords. It is possible that other
    specific sequences could also have provoked the bug.

10. It is now possible to use "p" and "x" at the start of a bar to repeat the
    note or chord at the end of the previous bar. If there is no tie, the
    accidentals are repeated; if there is a tie, they are not. If there is a
    subsequent use of "p" or "x" after one or more tied notes, the accidentals
    *are* repeated, according to the usual notation convention.

11. The Makefile has been updated so that, after installing pmw, it runs a
    script that looks for the "gs" command and, if it finds it, writes some
    text about how to get GhostScript to use the music fonts.

12. The gracespacing directive has been extended to take a second, optional
    value. This applies when there is more than one grace note before a main
    note. The second value specifies the space between the grace notes. The
    default is the same as the space between the grace note and the main note,
    and that in turn defaults to 6 points. A "+" or "-" can be used to specify
    a change to the existing value. For example:

      gracespacing +2 -1

    increases the space between the last gracenote and the main note by 2
    points, but reduces the space between multiple gracenotes by one point. If
    only one number is given to gracespacing, it is used for both values. For
    example:

      gracespacing +3

    increases both spaces by 3 points.

13. Added an "uninstall" target to the makefile.

14. Transpositions of an octave or more caused PMW to fail with an error
    message such as "Internal failure - transposition (48, 0, 60, 48)". Such
    transpositions should now work.

15. There is a new command line option -printgutter. This 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.


Version 4.06
------------

1. I had screwed up spectacularly in the representation of variable length
   numbers in MIDI files, setting the top bits of the bytes to precisely the
   wrong values throughout. This meant, for instance, that any long rests in a
   piece threw the whole MIDI thing out, leading to chaos.


Version 4.05
------------

1. It is now possible to specify alterative MIDIvoices and MIDIperc files by
   means of the command line options -MV and -MP, respectively.

2. An incorrect MIDI file was written if there was more than one stave, and
   there were notes tied over bar lines. An attempt to play such a file using
   Timidity caused it to stop at the point of error.

3. If just one bar is selected for MIDI generation, and it happens to be the
   end of a repeat section, PMW does not now carry on to play the repeat.

4. Added the -norepeats (synonym -nr) command line option, to suppress repeats
   in MIDI output.


Version 4.04
------------

1. Internal re-arrangement of flags for each note into two 32-bit words instead
   of one, in order to get more flags available.

2. Added support for writing MIDI files.

3. Added support for transposing chord names in text strings by means of the \t
   escape sequence.


Version 4.03
------------

1. The PostScript music font PMW-Music has been converted from a Type 3 to a
   Type 1 font. The file is now called PMW-Music.pfa, as per the normal
   convention. This font should display better on the screen, and should also
   be included in PDF files, thereby making the music therein display better.

2. Added three extra characters to the music font.

3. The PSheader file used a variable called PMSencoding, a hangover from the
   previous incarnation. Renamed as PMWencoding.

4. If *include was used when the input was the standard input, that is, not a
   named file, PMW crashed. It no longer crashes; however, if the included name
   is not absolute, it cannot make it relative to the main input (because there
   is no name). It just goes ahead and tries to open the file - that is, is it
   taken as relative to the current directory.

5. --help is now the same as -help, because some people are in the habit of
   using --help.

6. Arguments in macro calls are now scanned (recursively) for macro calls. For
   example, &a(&b) first expands &b, then uses the result as the argument for
   &a. The use of & as an escape now applies only to non-alphanumeric
   characters.

7. When cue notes and full-sized notes are vertically aligned, augmentation
   dots are supposed to line up. They weren't. In solving this, I've introduced
   two states: in the default state, the dots are spaced proportionately
   according to the size of the cue notes. There is a new option, invoked by
   [cue/dotalign] which causes them to be placed so that they align with any
   full-sized notes above or below on the same stave. This is useful when using
   the cue facility for alternative notes.


Version 4.02
------------

1. It was still saying "Scribe" in the PostScript output instead of "Writer".

2. Added -manualfeed to set the manual feed flag in the PostScript.

3. Put back the MIDI and playing directives for compatibility with old PMS
   files, though they have no effect. (They were made to work later - see
   above.)


Version 4.01
------------

1. Building problem. It was including one too many "/pmw" components in the
path used for finding the PSheader and fontmetrics.

2. Crash if sluroverwarnings was set and the bar following a warning bar did
not exist.

3. The -debug option wasn't behaving as documented (debug output to stderr). It
was taking the next item on the command line as a file to write to. This is
dangerous! It now behaves as documented.

4. PMW-Music change: when being processed by GhostScript, the widths of the
short stave characters are now (incorrectly) set as long as the long stave
characters. This gives a much better effect in the examples in the manual when
converted to PDF. It may also give a better screen display.

5. The PostScript command "a4" was put in the output (this dates from very
early PostScript printers). It seems to cause trouble with GhostScript, causing
problems in the zoom window, and it doesn't seem to be necessary any more, so I
have cut it out.


Version 4.00
------------

Version 4.00 is the first version ported from the RISC OS program to Unix-like
systems. A lot of changes were made as part of the porting process. However,
the following changes were also made to the application-level logic of the
program itself.

1. Removed (commented out) code for playing. (This got added back in later -
see above.)

2. Fixed a bug with very long arpeggio squiggles - buffer not big enough -
which just doesn't show up on RISC OS.

3. A macro defined with arguments, but no text, didn't removed any arguments
that were present when it was called. For example, if you had

  *Define X(1) @....

followed by &X(3) in the later text, "(3)" got left instead of being removed.

4. There was a place I forgot to record where the code was indirecting through
a NULL pointer (for an empty string); on the Acorn this didn't produce an
error.

****
