This is the directory for bww2tex. It is a program which translates
music in Bagpipe Music Writer [Gold] format to bagpipe.tex format. It is
currently in its first release as version 2.00.

bww2tex is designed to translate BWW/BMW source as specified in the
Bagpipe Music Writer Gold help, or 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 or BMW gold). I have not found it
convenient to emulate all of these unknown (to me) abilities,
but have accommodated a few of the more common deviations. bww2tex is less
accomodating than bmw2tex. 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 and the sample
tunes in the BMW Gold distribution. 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 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 'bww2tex help' to get the details. This should be easy to
use on UNIX boxes, and in Win32 console mode.
Windows GUI mode 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. In Windows console mode the "for" constrluct
may used for the same purpose.

bww2tex requires version 3.00 of bagpipe.tex.

Contents of this release:

Lin_bmw2tex       : AIX executable
Sol_bmw2tex       : Solaris executable
MAC_bmw2tex.hqx   : MAC executable
Win32_bmw2tex.exe : Win32 console application
expressions.l     : lexicon, flex source file.
grammar.y         : grammar, bison 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:

bww2tex does not add information that is not in the BWW/BMW source.
For example, it does not generate sloped beams. It also does not
adjust the spacing. Many strathspeys will have overfull hboxes
when TeXed. See bagdoc.tex for solutions for crowded music.
There are a small number of items which BWW/BMW does
that MusicTeX does not. I have made reasonable substitutions.
The formatting instructions in BWW files are mostly ignored.
The font size is reduced to two sizes, and the landscape
spec is honored.
bww2tex can't, of course, handle user defined BMW tokens.
musicsize16 (small music) is specified and the note spacing
is set to a minimal value. The TeX output may edited to improve
the appearance of tunes which do attempt to crowd the lines.

Unrecognized tokens are echoed to the output between bagpipe.tex lines.
Recognized tokens in an unrecognized order cause the parser to fail and
drop the current line.
Sometimes this is the fault of bww2tex and sometimes of the BWW/BMW source.
The most common cause is a missing tab. Other problems I've seen
in archived BMW tunes include missing CLEFTs, missing 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 BWW/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 BWW/BMW source, not arbitrary combinations
of tokens. If you get a parsing error please verify that the
BWW/BMW file is legal. This is best done by running the source through
the current version of BMW gold.
The most common problem is that something happened to the tabs.
There must be a tab separating every beat.
and none in the middle of a beamed note group.
(The "group"  may include things like trailing
dots, ties, and triplet signs, 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. Few are needed, but some of the subroutines are a bit
obscure.

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