.\" $NetBSD: bww2tex.1,v 1.3 2013/07/20 21:50:54 wiz Exp $
.\" -*- nroff -*-
.Dd January 24, 2002
.Dt BWW2TEX 1
.Os
.Sh NAME
.Nm bww2tex
.Nd Bagpipe Music Writer Gold to BagpipeTeX converter
.Sh SYNOPSIS
.Nm
.Op Ar infile.bww Op Ar outfile
.Sh DESCRIPTION
.Nm
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.
.Nm
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.
.Pp
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
.Dq Ic 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.
.Sh USAGE
.Nm
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.
.Nm
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.
.Pp
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
.Nm
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.
.Pp
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.
.Pp
A parser trace may be generated by using a debugger to set the global
variable yydebug to 1 after breaking at yyparse.
.Pp
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).
.Sh SEE ALSO
.Xr bagpipetex 1 ,
.Xr musixflx 1 ,
.Xr musixtex 1
.Sh AUTHORS
.Nm
was written by
.An Walt Innes Aq Mt walt@slac.stanford.edu
in 2002.
Content of the manpage is also by him.
.Pp
Manpage created by David Griffith
.Aq dgriffi@cs.csubak.edu
using the
README from
.Nm
2.00 for inclusion in the
.Nx
pkgsrc tree.
.Sh CAVEATS
In UNIX, if the input director
.Pq Sq \*[Lt]
is intended, but the output director
.Pq Sq \*[Gt]
is typed, the bmw file will be wiped out.
This can be avoided by using an explicit file argument.