                                 -==-
                                ABC2NW 
              ABC Musical Notation to Noteworthy Converter
                                 -==-

Contents
~~~~~~~~
(1) About the Program
(2) Extensions Over and Differences From ABC
(3) How to Use The Program & Requirements
(4) What the Program Supports
(5) What the Program Doesn't Support
(6) Known Problems (And How to Fix Them)
(7) About the Programming
(8) About the Programmer

                                 -==-
(1) About the Program

    ABC2NW (ABC to Noteworthy) converts any ABC file such as one would
    find on the Internet to the format of the DOS music publishing
    program Noteworthy (http://www.braeburn.demon.co.uk/)  A "generic"
    ABC file might look something like this:

X:1
T:Carrickfergus
M:3/4
L:1/8
K:F
f2 f3 e|d2 G4|GA B3 c|A3 G F2-|F2 FG A2|B2 D4|EF G3 A|F6:|
cc f2 e2|f6|fg a2 f2|g3 e c2|c2 f2 g2|a6|gf b2 a2|g6|
f2 f2 e2|d2 G4|GA B3 c|A3 G F2-|F2 FG A2|B2 D4|EF G3 A|F6|]

    The X: being the reference to the song (it would be song #1 in a
    file which could hold hundreds), T: the title of the song, M: the
    meter, L: the default note length, and K: the key. Everything after
    it is music data. ABC songs range in complexity from the very simple,
    such as the one above, to the very complex. For the complete
    ABC documentation, go to:  http://www.gre.ac.uk/~c.walshaw/abc/

    Regarding the layout of the music as made by ABC2NW: All staves will
    either be compressed or expanded as needed to fit exactly the same
    distance across the page. Although this was a lot of work, the end
    product is very well laid out and very professional looking!  There 
    were also problems with the last staff, which, because it may not
    have a "full" staff of notes, was left unjustified. I've changed 
    this so that the program neither expands to the extreme a few notes 
    left on the last staff nor leaves un-justified a nearly full line 
    of music. Now, if the music goes more than 3/4 of the way to the end 
    of the staff, it will be justified. If not, the extra staff will be 
    chopped off, which does a lot to improve the look of the music. 

    Be sure to read HISTORY.TXT to find out how lucky you are to have
    a later version of the program. Of course, you may not have *the*
    latest version, so visit my web page if you can.


(2) Extensions Over and Differences From ABC
  
    Extensions
    
    ABC2NW supports S: as part of the "header" field as an extension 
    over ABC. This is used for changing the clef on each staff (and, 
    of course, the placement of the notes), and can be used in the 
    middle of the music similarly to the M: and K: fields. Acceptable 
    values are "treble", "bass", "alto", and "tenor". The program 
    defaults to "treble", and, as usual, only the first three characters 
    of the field are paid attention to. Simple piano music can be made 
    with this field by changing the clef between each staff, but the 
    bars of the music will almost definitely not be lined up, and the
    staves will not be bracketed together (this can be done in Noteworthy). 
    An example which shows how the alignment of the notes will be changed:

X:2
T:Clef Song, The
C:Sean O'Malley
L:1/8
S:treble
K:D
A|
S:BASS
A|
S:Alt
A|
S:TEN
A|

    Differences

    The only differences between ABC2NW and the ABC standard are the 
    way ABC2NW ignores the \ (line continuation) symbol, and several
    minor, not often-used notations. Basically, if you try something
    and it doesn't show up or produces an error, it isn't supported.
    

(3) How to Use The Program

    The command line for ABC2NW is:

     ABC2NW <ABC file> <NW file> <Reference number>

    <ABC file> is the name of the file containing the ABC songs,
    <NW file> is the file to create, and <Reference number> is the number
    following the X: in the ABC song (see the song above). If the NW
    file you're trying to create already exists, it will warn you and
    exit the program.  (This is to make sure the file is not erased
    accidentally.) The default extension for ABC files is .ABC, and
    for Noteworthy files .NW. These will be added automatically if
    no extensions are given.

    The Noteworthy files this program creates can then be loaded as
    usual into Noteworthy.

    Requirements: If your computer can run Noteworthy, it's definitely
    able to use ABC2NW. I kept memory usage and processing at a minimum, 
    but ABC2NW can use upwards of 8kb of memory at once. (Which is much 
    smaller than the ABC2NW executable itself.)


(4) What the Program Supports

    1. All notes, including dotted and double-dotted. The program is
       pretty intelligent in that it can take fractions like 11/16
       and find the nearest note down, but the fractions need to be
       exact if you want dotted and double-dotted notes. For example,
       in a default note length of 1/16, A6 will bring a dotted quarter
       note, and A7 a double dotted quarter note, but A13 will not
       bring a dotted half note even though it's the closest "note"
       down - it will produce a half note.  Same goes for note
       division.

    2. Cross bar tying:  A-| A  This appears identically to regular
       tying with parenthesis. This would give the same result: (A | A)

    3. Grace notes. As in the ABC standard, these are all rendered
       the same note length. ABC2NW shows them as small quarter notes
       with the stems pointed up.

    4. Staccato. (A dot below or above the note.)

    5. All accidentals: sharps "^", flats "_", double-flats "__", and
       naturals "=". Will make smaller-sized accidentals for grace
       notes. (ver 1.2+)

    6. Chords: [D^FAd]

    7. All major and minor key signatures. (See "What the Program
       Doesn't Support") below.

    8. Trills and, for the fiddle, up- and down-bow symbols: ~AvAuBvA

    9. All bars and repeats except "[|", which Noteworthy doesn't
       support. (It will be rendered as "||").  First and second
       repeats are supported.

    10. Beaming - all notes that are supposed to be beamed will be
        beamed. It is also pretty "intelligent" in that, unlike some
        other programs, it will not force all the note stems to point
        in one pre-set direction just to get the beaming to work.

    11. Song titles - it will put the first listed song title at the
        top of the music and correct titles with names like
        "Hamster, The" by putting the "The" first.

    12. Highland piping key signatures HP and Hp. Both will make all
        note stems point down, but Hp will produce a key signature of
        C sharp, F sharp, and G natural.

    13. Tying, using parenthesis: (ABc)  The tying will go over or
        under depending on the stem direction of the first note, and
        will even shift its end point up or down as necessary. (Try
        tying a big sweep from the top-most to bottom-most note and
        see what happens!)

    14. Tuplets: (3ABc (4ABcd

    15. As an extension over "normal" ABC, clefs can be defined by
        S: treble/bass/alto/tenor.

    16. All modes. (Mixolydian, dorian, lydian, etc.)

    17. Broken rhythms: A<B C>D A<<B C>>D
        Only works with single < or double >> pointy brackets since
        Noteworthy doesn't support triple-dotted notes. Triple <<<
        brackets will be interpreted as double.

    18. A tempo key will be placed in the upper-left hand corner
        of the music, or above any staff where the tempo has been
        changed in the middle of the song.

    19. The composer, origin, and rhythm of the song will be printed
        in the upper-right-hand corner of the music.

    20. Accented vowels can be produced by putting a \' before the
        vowel to be accented, or a / after. (These are two common
        methods.)  It will put a slanted line above the accented
        letter which looks like an acute accent.  Note that when the
        program is running, the title it prints out on the screen
        will not have the correct accents - this is because there is
        no way to print out the correct accents with the screen font.


(5) What the Program Doesn't Support

    Because of the vast differences in formatting between ABC notation 
    and the Noteworthy file format, a few things are not supported.

    1. The ABC "line continued" symbol  \  is completely ignored.
       Always keep in mind that one line of ABC = one staff in
       Noteworthy. (This is one instance of something so heavily
       abused that it's become meaningless; entire ABC tunes are
       being written with a \ at the end of each line!)

    2. All major and minor keys are supported, but global accidentals 
       are currently unsupported.

    3. You cannot change key or meter inside a single staff. ABC2NW is
       *strictly* one line of ABC = one staff.

    4. Triple-dotted notes.
       

(6) Known Problems (And How to Fix Them)

    1. The notes are really crunched together. Why?

       There are too many notes on a single line of ABC music and the 
       justification routine ABC2NW uses is pushing everything together 
       so it all fits on the staff. To fix, all you need to do is, 
       using a text editor, arrange the measures so there are about 
       four or five on each line of ABC text. (Fewer measures may be 
       needed depending on the complexity of the music - lots of 
       sixteenth notes will take up more space than a few whole notes!) 
       This will in general also make the ABC code much more readable in 
       text form.

    2. The key of C is turning up with a natural symbol in the key 
       signature. Is there any way to stop this?

       Yes, remove the K: (key information) area from the ABC file.
       If the program finds a key signature, it's going to put a key
       signature into the file. There's no way for it to distinguish
       between a key of C that someone wants to show and a key of C
       that someone wants left blank. (Also, it can always be removed
       inside Noteworthy.) Note that some ABC programs *require* a key
       signature, as it is used in some cases as the boundary between
       header information and song information.

    3. I have an ABC file with the correct numeric reference in it, 
       but ABC2NW gives an error saying it can't find it.

       First of all, make sure the file is in the correct ABC format.
       The X: should be the first two characters of a line, with a
       number and ONLY a number following it directly. ABC2NW is
       slightly lenient in that it will remove extraneous spaces out 
       of most "header" lines, but beyond that it stays strictly 
       within the bounds of the notation.  Second of all, some ABC 
       files downloaded off the Internet may be in the Macintosh or 
       Unix text file formats; ABC2NW only recognizes the DOS format. 
       To convert Unix/Mac files, load them into a DOS text editor and 
       save them again. (Note: MAC text files are currently unrecognized 
       by most, if not all, DOS text editors and MAC files will appear 
       as a single long line of text. You may need a special program to 
       convert these.)

    4. I'm using the chord notation " " for putting words above the
       staff, but the letters sometimes appear placed over each other.

       There is no guarantee that groups of letters or words over 12
       characters long (including spaces) placed inside quotes will be 
       placed correctly. Since the notation for chords is meant purely 
       for chords, this will not normally cause problems. There is 
       currently no way around this, but if you need to put words above 
       the staff, do it inside of Noteworthy where you can more easily 
       see the placement of them.


(7) About the Programming
 
    This was one of the most difficult programs I've ever written. When
    this program was at its bare minimum (basically, it just wrote
    notes down and didn't do anything special), it was still well over
    1,000 lines long. ABC, which gives the bare minimum of musical
    information, needs to be converted into Noteworthy, a binary format,
    which doesn't have any music information - it depends on every
    object having definite X and Y coordinates to produce everything.

    You'll get an idea of what this means if you consider chords: On
    each chord, (1) the notes all need to line up, (2) some stems will
    initially point up and some down, so the program needs to find the
    "average" stem direction and point them all the right way, (3) if
    the notes are faster than quarter notes (and, hence, have "flags"
    on the stems), the flags need to be removed except for the topmost
    or bottommost, depending on which way the stems are pointing. And
    this is just for one chord!  Numbered repeats alone consist of three 
    separate objects with five separate sets of X and Y coordinates. (A 
    vertical line's starting and ending point, a horizontal line's
    starting and ending point, and a number's location.)


(8) About the Programmer

    This is my second "big" program, but I'm sure it won't be nearly
    as popular even though it's been so much more work. The Base64
    utilities were "just" 1,000 lines after six revisions; ABC2NW
    is 1,800 lines and climbing as of the time of this writing.

    If you have any questions, comments, or (ha!) bug reports, send
    them along. I enjoy mail!  (I'm still receiving e-mail about the
    Base64 programs well over a year after I first released them.)
    Also, you may wish to visit my slowly-expanding web page, which
    currently has a page just for this program.

    My e-mail address:  ffrog@geocities.com
          My web page:  http://www.geocities.com/~ffrog
