Initial import of bww2tex-2.00, a Bagpipe Music Writer Gold to BagpipeTeX

converter, submitted by David Griffith in PR pkg/19978.

1 files changed, 104 insertions, 0 deletions

diff --git a/print/bww2tex/files/bww2tex.1 b/print/bww2tex/files/bww2tex.1
new file mode 100644
index 00000000000..4f1e8eaa058
--- /dev/null
+++ b/print/bww2tex/files/bww2tex.1
@@ -0,0 +1,104 @@
+.\" -*- nroff -*-
+.TH BWW2TEX 1 2.00
+.SH NAME
+bww2tex \- Bagpipe Music Writer Gold to BagpipeTeX converter
+
+.SH SYNOPSIS
+.B bww2tex
+[\ infile.bww\ [\ outfile\ ]\ ]
+
+.SH DESCRIPTION
+
+.B 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.
+.P
+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.
+
+.SH USAGE
+.PP
+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.
+.P
+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.
+.P
+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.
+.P
+A parser trace may be generated by using a debugger to set the global
+variable yydebug to 1 after breaking at yyparse.
+.P
+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 CAVEATS
+.PP
+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.
+
+.SH AUTHORS
+.B bww2tex
+was written by Walt Innes (walt@slac.stanford.edu) in 2002.  Content of 
+the manpage is also by him.
+.br
+Manpage created by David Griffith (dgriffi@cs.csubak.edu) using the
+README from bww2tex 2.00 for inclusion in the NetBSD pkgsrc tree.
+
+.SH "SEE ALSO"
+.BR musixtex(1)
+.BR musixflx(1)
+.BR bagpipetex(1)