This is the directory for bmw2tex. It is a program which translates
music in Bagpipe Music Writer format to bagpipe.tex format. It is
currently in its first release as version 1.00. 1.00 differs from
the beta releases in that it uses the new features of bagpipe.tex
2.02.

bmw2tex is designed to translate BMW source as specified in the
BMWDM Version 5.0/BMWPS Version 2.0 manual. I infer from
the archives that earlier BMW versions were more tolerant of
non-conforming code than this release. (Actually I think it is
that BMWDM is more tolerant than BMWPS). I have not found it
convenient to emulate all of these unknown (to me) abilities,
but have accommodated the more common deviations. I have
implemented the old symbols which have new names so that
both old and new symbols will work. This version successfully
parses all but a dozen of the tunes in the Peter Mohr
and Michael Bell collections. The translated files 
(at least those free of blatant copyright problems) are
available on the Ceolas archive. The failing input files 
have fairly gross errors (at least as they arrive on my machine), 
e.g., no tabs whatsoever. I have only spot checked that the
files produced TeX properly. 

The code is written in flex and bison (probably compatible with
lex and yacc) source. These are processed into C *.c and *.h
files which can then be compiled into the executable. 
The final program can be used as a UNIX filter, that is, it
uses standard input and output. Alternatively, input and
output files may be specified on the command line.
Enter 'bmw2tex help' to get the details. This should be easy to
use on UNIX boxes, MS DOS machines, and in Win32 console mode.
Windows and MAC systems are another story. Such programs require
additional App wrapper code, a developers environment, or a
shell program to use on MACs or as a Windows application.
The MAC application uses the DropUNIX app-wrapper. In the current
version the drag and drop feature still does not work, but you can
convert files using the select file menu item. The 
result is awkward in that one has to restart the application
for each file converted, but at least it can be used. 

CAUTION: in UNIX, if the input director (<) is intended, but the
output director (>) is typed, the bmw file will be wiped out.
This can be avoided by using an explicit file argument.

TIP: in UNIX, use the foreach construct to convert a large
number of files.

bmw2tex requires version 2.02 of bagpipe.tex.

Contents of this release:

NeXT_bmw2tex      : NeXTStep executable (quad-fat)
AIX_bmw2tex       : AIX executable
Sol_bmw2tex       : Solaris executable
MAC_bmw2tex.hqx   : MAC executable
Win32_bmw2tex.exe : Win32 console application 
expressions.l     : lexicon, flex (lex?) source file.
grammar.y         : grammar, bison (yacc?) source.
tokensDat.h       : semantic content of tokens returned by lex.yy.c.
tokens.h          : pointers to the above contents.
lex.yy.c          : the C file output of flex.
y.tab.c           : the C file output of bison.
y.tab.h           : a BISON generated header file for use with lex.yy.c
y.output          : a parser description file generated by bison.
makefile          : a file describing how build bmw2tex (for use with make).
*.bmw             : sample BMW source files.
*.tex             : the files generated by bmw2tex.


Notes for testers:

bmw2tex does not add information that is not in the BMW source. 
For example, it does not generate sloped beams or differentiate
between part endings and final endings. (I haven't figured out how 
to use the end of file in the parser). It also does not
adjust the spacing. Most strathspeys will have overfull hboxes
when TeXed. See bagdoc.tex for solutions for crowded music. 
There are a small number of items which BMW does 
that MusicTeX does not. I have made reasonable substitutions. 
bmw2tex can't, of course, handle user defined BMW tokens.

Unrecognized tokens are echoed to the output between bagpipe.tex lines.
Recognized tokens in an unrecognized order cause the parser to fail and quit.
Sometimes this is the fault of bmw2tex and sometimes of the BMW source. 
The most common cause is a missing tab. Other problems I've seen
in archived BMW tunes include missing CLEFTs, misssing spaces,
missing line termination, missing beam (l,r) characters, capitalization
errors, and tokens between a note and its dot.

Once the input file has been parsed, the next question is will it
TeX? The most likely cause for a TeX failure is an unknown 
beamed group macro. Often the only solution to this is to add
the appropriate definition to the TeX file. Sometimes the
note grouping may be rearranged so that an existing macro 
may be used. Another cause is a beamed group of a single note.
This can result an unknown macro or a misused macro. These are
usually due to errors in the BMW source, either an inappropriate
beam character or tabs in mid-beam.  

A parser trace may be generated by using a debugger to
set the global variable yydebug to 1 after breaking at yyparse. 

Please test only plausible BMW source, not arbitrary combinations
of tokens. If you get a parse error please verify that the
BMW file is legal. This is best done by running the source through
the current version of BMW, preferably BMWPS. 
The most common problem is that something happened to the tabs. 
There must be a tab or a bar immediately after every 
beamed note group and not in mid-group. 
(The "group"  may include things like trailing 
dots, ties, and triplet signs, but preferably not trailing
embellishments, and first/second time indicators).

If you find an error please email to me the offending source file 
and anything you know about the error, for example the erroneous
output file. If the parse trace is on, the trace will be in the 
output file as well. 

Apologies to those who have access to flex and bison and might
actually do some debugging for me. There are very few comments in the
source as yet. Few are needed, but some of the subroutines are a bit
obscure. 

Good luck,
Walt Innes (walt@slac.stanford.edu)