README

/*
   This program is copyright 1991 by Wayne Cripps,
   P.O. Box 677 Hanover N.H. 03755.
   All rights reserved.  It is supplied "as is" 
   without express or implied warranty.

   Permission is granted to use, copy, modify and distribute
   this software without fee, provided that this notice appears
   in all copies, and that a copy of this notice is provided to
   anyone who recieves a binary copy without sources.

   This software may not be used for commercial purposes
   without explicit, prior written permission.

   Please mail bug reports, suggestions, and improvements
   to wbc@cs.dartmouth.edu.

 */


***************************************************************************
*     get on the lute mailing list - send e-mail to
*     lute-request@cs.dartmouth.edu
***************************************************************************

tab is a program to typset lute tablature.  It works like TeX  in that
a plain text file (that bears little resemblance to the desired output)
is created and processed into a device independent printer format
file.  The standard output format is PostScript, which laserwriter
printers print.  This program is not particularly beginner-friendly,
but is quite fast once you have gotten used to it.  

github:
The source is available at github.com/mandovinnie, but I work with the old
make distrib system.  The Makefile has a list of files to include in the
distribution tarball, which saves me from making a huge .gitignore.  However,
this means that I can't pull change requests.  I have to put them in by hand
into the main code stream.

Environment variables:

	Tab looks in the directory pointed to by the
	TABFONTS environment variable, if it is set.
	The font directory can be compiled in with the TLOC definition
	in the Makefile if you  are compiling this yourself.
	Otherwise it looks in the current directory.

Options:
    These can be used on the command line, as in tab -P -6
    or in the tab source file.

    -a extended arguments - 
	-af num Font-Name uses Font-Name for font num - see
	F below.  DOES NOT WORK
	-as num size uses font size size (points) for font num
    -alttitle	use alternate title font
    -alttitle-off use regular title font
    -a4 adjust for a4 paper size
    -ascii  print "ascii tab" for email
	this option understands the -Q option to cram music into a
	small space.  also the -wide option to print on 132 character
	wide paper (if you have an old fashioned high speed printer)
    -autoKey sets key signature on all lines as on first line
    -2 prints 1200 dpi
    -1200 does the same
    -2400 prints 2400 dpi
	be warned that some large glyphs won't print at 1200
	and PostScript will crash!
    -300 prints 300 dpi
    -4 prints only four staves
    -5 prints only five staves
    -6 prints 600 dpi
    -600 does the same
    -7 prints seven staves
    -0 prints six staves (I know this should be -6 but I used
	that already!)
    -b uses baroque tuning to transcribe to music and uses
        a baroque font (blute9) to set the music
    -B uses flags and f,h, and i like those used by
       M. Board and other english writers.
    -count_dots	- count dots as barline for measure numbering
    -c prints measure numbers only at the start of a line
    -C prints every fifth measure number below the staff.
    -CC prints every measure number below the staff.
    -compressStaff sets interspace to 9.0 pt and m_space to 0.068 which makes things tighter
    -dvi output in dvi format to out.dvi
         this depensd on you installing the GNU gs postscript processing command in the right place.
    -pdf generate pdf output to out.pdf
    -D sort of like Dowland's style
    -debug <Mode> print out debugging information about 
	Fonts Inter TFM Stack Flow Proceedure
      
    -e rotates the page 90 degrees for landscape music.
    -E prints "DRAFT" on every page along with the date.
    -EPSF sets head so that file can be included in another document.
	this only works well for single pages.
    -F maps the flags to modern style flags
	-h translates french to italian, 6 courses only
    -f resets to french style (the default)
    -fc sets the characters to standard style
    -ff sets the flags to standard style
    -fontpath  <path> sets font directory to path
    -G prints a copyright notice at the bottom of the page
       useful if you have the right name.....
    -guitar printe manuscript on a single guitar staff
    -h converts french tab to italian tab automatically!
    -H does the same, but for 7 course tablature
	the second -h or -H unsets the conversion
	-h
	-h
	does nothing!
    -highlightparen uses parentheses instead of gray characters in
		postScript output.
    -highlightred uses red characters instead of gray characters in
		postScript output.
    -I maps the flags to renaissance style  
    -i shifts the lines to the middle of the numbers,
       and maps the flags to renaissance style
    -italFlags uses Italian style flags for tablature
    -j when translating italian between line to french
       is a correction.
    -K cancels automatic end of page detection.  You will have
       to insert page breaks yourself with the p flag.
    -l "n units"  sets line length to n units, where n
	   is a floating point number, eg 3.25, and units is one
	   of mm, in or pt.  The default is "6.5 in". The double
	   quotes are mandatory.
	-l reset resets the line length to the previous length.
    -staff_line_thickness "x.x in"    sets the thickness of the staff line
    -listfonts  lists the PostScsript fonts, with short name
     	that you specify in the $titlefont= command and the
	long name that must be on your printer. This lists the
        font names that are built in to tab.
    -longbar with music draws bar lines between tablature and staff
    -m print out the piano version of the tablature. This is kind of basic!
    -midi sends a midi file to standard output.  Be sure to say -midi
	*before* the file name when you want midi output!
        You must use numstyle=italian or -i if you are using numbers
        for the fret values.
    -midi-patch number  is the same as $midi-patch=number.  You can use
        it on the command line.  Try patch 123!
    -modernNotes  use modern, rather then renaissance notation for music
    -M print marks on the page to show where the character positions are.
    -N uses fonts like Robinson
        these fonts use the default characters for any 
        characters they don't have - Mace only has f and e.
        Robinson has b-h.
    -n uses fonts like Mace
    -nmidi sends midi output to the file nout.mid.  This variation
       of midi output only works for 6 course music, italian
       tablature right now.  This option only works on the command
       line, you can not specify it within the file.
    -nobox  Do not set a bounding box - for postscript debugging
       the next two commands help keep grid flags even
    -no_space_before_note - print the ornament in the space of the previous character
    -no_space_after_note - don't add space for ornaments after notes
    -O uses thin line flags, like dalza. 
       and shifts the lines to the middle of the numbers
       you can use -i -T instead.
    -o specifies an output file.  default is out.dvi
       if the .dvi or .ps extension is not specified it is added.
	   this can not be specified in the input file.
       if the name is stdout then output goes to standard output.
    -p number the pages automatically
    -P the output file out.ps, in PostScript format, is
           generated - this can be sent to a printer directly,
	   without running dvips on it.
    -Q space the notes correctly when whole notes are used a lot
    -q don't say anything unless something really bad happens.
    -R7  reduces size to 66%, -R95 to 94%, -R9 to 88% -R8 to 77% 
    -S don't advance the line after the current system
       puts the following system on the same line
    -s lets you use seven course italian notation, with
       the -i or -O flag.
    -sharpUp places the sharp or flat above the staff,
    -sharpNorm places the sharp or flat in the regular place.
    -sItalNotes uses small Italian style noteds for music
    -sound sends a midi sound file to standard output, or if 
	recompiled the right way can create a raw sound file
	with a 8000 integer 8 bit unsigned format  
        called "data".
    -spanish when used with -m and -h converts "spanish" tab to 
        music correctly.
    -tabfontpath prints out the place where TAB looks for font files
    -tuning 
	-tuning C4D4E4F4G4c3f3a2d2g2	renaissance
	-tuning e4a3d3f+3b2e2		for guitar
	-tuning a4b-4c4d4e4f4g4a3d3f3a2d2f2 	is d minor
	-tuning c4d4e4f+4g4a3d3g3b2d2f+2 is sharp
	-tuning c4d4e-4f4g4a3d3g3a+2d2f2 is flat
        Note that the lowest note tab knows about is a4, and
        each octave starts at a, as in a4-g4a3-g3a2-g2
    -twostaff allows you two insert two lines of music along with
        one line of tablature.
    -twelvedots - in Italian notation, use an X with two dots 
        above it instead for N12.  This also changes N10 to X
	and N11 to an X with a dot above it
    -T uses dalza style flags
    -t prints the notes on the line and does nothing else
    -tfmdump  dumps useful info about the TFM file headers (developrs only)
    -thin uses the older,renaissance font "tlute"
    -v prints the intermediate language to the screen
    -V gives the version and date
    -x notes on the line, thin flags, standard characters
	   italian numers and italian notes.
    -wide in ascii mode prints 132 characters wide.
    -X supresses note expansion for debugging
    -Y supresses word fitting for debugging
    
    a line in the .tab file beginning with - is read as command
line options.  You may reset options between systems, to 
reset line length, print two tyes of tab, or print tab and
regular musical notation.  If you wish to use the -R flag to reduce
the type size (as in -R8) you must put it on the first part of the
first line, as the first line of the input file is scanned
once for commands before loading fonts.

Input:

A file is created in the pattern of ./music/Mathias.tab, using the following
characters.  The file should have a .tab extension to its name.  Note
that a character often has a different meaning as the first letter
in a pattern than it does in following positions.

start of line:
{ words } 	- one of more lines of text (unjustified, not wrapped)
		- if the line starts with \CL/ the text afterwards is 
		  centered.
	     	- a hat followed by two numbers in the text specifies a font,
		  as in ^05, italic and ^02 regular
	 	  ^01 10 pt regular words to songs
		  ^02 12 point regular titles
		  ^03 12 point bold  ^04  24 point large regular
		  ^05 10 point italic ^06 18 point regular music time sig
		  ^07 12 point regular for page numbers
		  you can use $textsize to change the point size of ^01
		  you can use $alttextsize to change the point size of ^05
		  you can use $titlesize to change the point size of ^02
		  you can use $alttitlesize to change the point size of ^03
		  you can use $textfont to change the fonts, too
[ words }	- text, positioned closely above a system, for 
		  Da capo, etc.  Maximum of 10 characters when in the middle 
		- of a system.
{words/words}	- words left and right justified, with a space in the 
		  middle
	there must be exactly one blank line between text and staff

% 		- comment
#		- first note of a grid
		  followed by number of lines in grid
*		- insert a letter, as in *A
~		- wavy lines over these notes
=		- in music, eg W = W.
A		- first, second repeats in modern style (Another)
		  number is second char on line.
b		- barline
           in most cases you can add several letters after a b to do more
           than one thing.
bT		- a barline with a tie
b!		- don't print this barline
bv		- a v above the staff, indicating page breaks in orig
bV		- two v's
b2, b3	- a barline with a number, 1 - 9, above it
bQ              - a pale bar
bX		- a bar line that does not count with -C or -c
bL	 	- a pale bar that does not count with -C -c or -CC
B		- a very thick barline (when followed by newline or !)
B		- a breve (when followed by notes)
bb 		- two barlines
  (blank line)  - break line here - you must specify line
	 	  breaks yourself!
. 		- column of 5 dots (for a repeat) as in .bb.
                - with the "-count_dots" this will increment the bar count
                  unless followed by an "X"
C 		- a big C
c		- cut time in both staves if necessary
d		- the del signe sign, for repeats
D		- a D.C. - for Da Capo
e		- end of document -tab will work but will complain
		  without it.
F Num		- specify a font - this is tricky -
		  Num is between 1 and 5
		  1 roman words to songs
		  5 italic words to songs
		  2 roman titles   (regular font)
		  3 italic titles  (alternate font)
		  for example F 2 sets roman titles
f		- fin (spanish - should be fine in some languages)

0, 1, 2, 3, 4, 5 - a note with that many flags
W		- a whole note  0   |
w		- a half note       0
8		- 8vb in the music
k		- key signature kg is key of G, also d, a, f, c, b, e
K		- move to next column, 3.5 in hardcoded
L		- longa
I filename	- include filename
@               - print just a dot for a dotted note in the previous bar, used in Cosens ms.
i		- indent a bit (used at the beginning of a line
	          that doesn't start with a bar)
j		- the same as i but less padding when the line is justified
 .		- after a number, dot the value of the flag
 !		- after a number or b - don't print flag but use its value
		  for spacing - for replicating manuscripts.
 -       	- after a number, allows you to put a ! or . on the top line.
x 		- same number of flags as the last one
m		- Mesangeau's flourish!
M		- a note of music with no tab M#n+ where # equals 
		  number of flags.
		  You may place one tab after the M to line up the music.
		  n is the note value A-Ga-g (with 1 2 3 4 giving you high  a - d, 
		  and + is for sharp, . for dotted note
 		    - for flat, n for natural, or 0 for neither
		    v for dot and flat, ^ for sharp and dot
		    N for dot and natural
		  MG gives a G clef in the music.  MF gives
		  an F clef in the music
		  appending an 8b places an 8 below the G and MGa places
                  an 8 above the G clef.
O		- this chord is an ornament, as in Capirola book - 
		  it has no width
p		- force end of page.
P		- pagenumber
Q		- a flourish for the end
q		- same
R		- a rest (hat) - followed by the flag number - as in R2
S		- a time signature - ie S3-4 or SC
		  a dash, as 12-8 draws the signature in the music
		  rather than the tablature.
		  S2| or S3| draws a line throught the number
		  a single digit followed by Q is highlighted
		  SO and So do Narvaez style time sig
		  S0  (that is a zero) gives  the O for perfect time
		  SI and Si gives a circle for perfect and imperfect time
T		- text to go on system lines  (a tab gives a second line)
t 		- first note of a triplet, followed by the
		  followed by the number of lines there would be
	 	  if there were lines - eg. t3 a,x b, xb,
		  this places a 3 above the second note.
	        - a t before a barline is a tie across the barline
v               - a mark above and below the staff, indicating a line break in the
                  original ms.  It can also follow a b or B.
V " 2.2 in"	- vertical skip
x		- more notes in same grid
Y		- fermata
y		- another fermata
		  a Yb or yb draws a fermata above a barline
	          Y. YW Yw YB also work
$		- used to set these values. This flag must be 
		  outside of the systems to work.  A $flag in a system
		  is ignored.

		  $lutefont=fontname, where fontname is of the
			form font, and the file font9.tfm and font9.300pk
			exist. 9 is for full size fonts, 300pk for 300 dpi
		  $titlefont=cmbx10 (a dvi font name) for the titles
		  $titlefont=pncbi  (a PostScript font name)
		  $titlesize=12 (or other point size)(12 is default)
		  $alttitlefont= the italic title font 
		  $textfont= a font name for text
		  $textsize=12  (or other point size)(12 is default)
		  $alttextfont= the italic text font
		  $pstitlefont, $pstextfont, $psalttitlefont, $psalttextfont
		  $dvititlefont, $dvitextfont, $dvialttitlefont, $dvialttextfont
		  $barnumberfont=<number 1-5> the number of the font to use for bar numbers
			hint - smaller italic = 5
		  $first_bar= the number of the first bar on a page
		  $line=o or $line=b (characters in music on or between lines)
		  $description=text = a no-op for compatibility

		  for the following, only the first few characters are 
		  significant.
		  $flagstyle=con == $flagstyle=contemp
		  $flagstyle=board		english manuscript style
		  $flagstyle=capirola		thin line flags
		  $flagstyle=contemp		regular notes
		  $flagstyle=italian		a long italian flag
		  $flagstyle=smallitalian	basic italian style
		  $flagstyle=standard		the default
		  $flagstyle=thin		like capirola, dowland
		  $charstyle=board		like m board book
		  $charstyle=dowland		does nothing!
		  $charstyle=mace		like mace
		  $charstyle=standard		regular characters
		  $charstyle=robinson		like robinson, 1600 english
		  $numstyle=standard
		  $numstyle=italian
		  
		  $tempo=8			tempo for music, larger=faster
						default is 2.  Used for
						playing music, writing
						piano version
		  $note-conversion=0 		[0-12] how many more flags 
						does an equivalent music 
						note have to a tab note
						The default is 2, 4 doubles 
						the tempo. does not work
		  $sys-skip=1.2			extra space to skip between
						systems, in inches, only
		  $midi-patch=n			a number, 0 to 127, which
						selects a midi "instrument"
		  $start-system=n		which system to start "printing"
						This is intended to be used with 
						the midi option to skip the 
						beginning of a piece.  It also 
						works for the printout, but does
						not look good.
		  $scribe="scribe"		Adds a name after the copyright 
						(the -G flag)
		  $transpose=n			transposes midi or mensural 
                                                notation n half steps
    		  $left-margin=nn               sets the left margin in 1/72 inch (points)
    		  $top-margin=nn                sets the top margin in 1/72 inch (points).
		                                the default is 72 so setting this to 72
						does not make any difference!  Any title
						will extend
						a little above this margin.
		  $extended_character_set	Normally q is an ornament, 
						if you need q-v to be letters use this
		  $slur_depth=-10.0		for the {} slur, underline, baroque,
						you can set the curvature distance
						should be negative, 0 to 10
		  $perfectum	  		use a fancier perfectum time signature that may cause problems printing

the following characters have special significance as the
second letter on a line - in most cases, if not needed
they can be ignored:

 - 	a place marker, technically should be the default second character
	but usually can be left out - it helps when you want to use a
	*, # or - ornament on the character on the top line.
 .	a dotted flag
 # 	begin a grid- you may say #2 or 2# but for an ornament 
	you must say 2-#aa, not 2#aa!
 *	a dotted note within a grid
 | 	a flag with an extra bar within a grid.  using | instead of #
        at the beginning of a series starts with a note with extra flag
 t	a tie to the next note	(this doesn't look like it works)
 W	a tie and a dot		(this doesn't look like it works either!)
 !	after a number - don't print flag but use its spacing
 !	after a b - don't print barline, but count it.
 Q	highlight this flag
 @      highlight and dot this flag
 B	a dot preceeding the flag

the following are the characters that can be used in a line
of tablature, as the second to tenth character.

	a b c d e f g h i j k l m n o p - the tab characters
	  ( I know you don't use j, but it is there for completeness)
		F G H I give characters like M Board used
	1 2 3 4 5 6 7 8 9 - numbers, for italian style
	!x 		- for the tenth fret, in italian mode.
	space	i	- no character on this line
			  a 0 no longer indicates a space!
	z		- a zero
	\\		- one backslash in note position
	. 		- one dot below tab - fingering
	:		- two horizontal dots below tab - fingering
	|		- stroke - for thumb
                          two in a row give two side by side strokes 
	-		- vertical bar - play similtaneously
	+ * # x $ < 	- an ornament before the next note
	                  + makes a cross
			  +* makes a cross with a dot above it
			  * makes a dot
			  # makes a hash sign
			  x makes an x
			  $ makes four small dots in a rectangle
			  < makes a short horizontal line - a dash
		'	- a comma above the line
		,	- a comma on the line
		Q	- character is highlighted
	%		- two horizontal dots preceeding next note
	?		- a flat
	>		- something like a flat but different
	@		- an asterix
	= or &=		- colon
	$ or &$		- double colon
	_ or &_ 	- a smiley
	&+ &* &# &' &`	- an ornament after preceeding note
	&%		- two dots above the note
	w, u		- "hold" for italian style tab
	&x		- a postfix x
	<		- a horizontal dash as an ornament
	^		- a hat
	& is the postfix operator - the next character is printed
			  to the right of the preceeding char.
	! is the escape operator - for example, print / ( a prefix )
			  in a note position rather than treating it
 			  as a prefix, which is its default.
			  1 c!/ca
			  !0376 will give a del signe -
			  other 0xxx codes could be added
	" is the prefix operator- most things default to prefix
			  but you can print -- as a prefix
			  as 1 "-c"-d"-da
	Nxx		- print number xx -as in 10 through 30 for
			- high frets in Italian tab or modern guitar tab.
	q		- a '/. sign for Kapsberger
        r               - a repeat sign under the staff
	R		- a rest
	R!		- a rest, with no flag
	U		- begins a horizontal underline to indicate a held 
			  bass note. line starts beside character above U
			  With PostSCript output this is a curved line like a slur
	X		- ends the underline
	[ ]		- horizontal underline with a curve to it, a slur
			- a ]v (a v after the ] ) draws an upside down slur
                        - a ]w (a w after the ] ) draws a wavy up-down slur
	( )		- a straight underline, so you can use two.
			  the slope is determined by the position of
  			  the beginning and end parenthesis.
			  you can use the & to start a line beside a note.
	{ }		- a horizontal or slanting underline with a configurable curve to it
			  the $slur_depth sets the curvature
	/		- a slash for a bourdon if used on bottom line
			  otherwise a light slash
	//		- two slashes
 	///		- three slashes
	<!tilde>	- the same as the ~ - looks like a sine wave
	<!2mordent>     - a 2 lobed squiggle, baroque tab only
	<!3mordent>     - a 3 lobed squiggle, baroque tab only
        1 3 4 5 6 7	- the number for bass string when you 
			  run out of slashes
	\1 \2 \3 \4	- left hand fingerings placed
			- before the next letter.
	r		- show current dvi location (for debugging)
				(not currently active)
	M		- the next three characters are the time
			(just like the flag), pitch [A-Ga-g], and
			+ (sharp) -(flat)  . (dot)  ^ (sharp and dot)
			v (flat and dot) n (natural) or anything else for
			music above the line of tablature.
			For pitch you can also use ? @ for the low F and G
			and 1 2 3 4 for high a b c d.
			if the note is R you get a rest.
			MG gives a g cleff in the music
			M000 does not print anything, it is a space holder.
			a # following the three characters starts a
			beamed set, an x following the three characters
			continues it. A - following the three characters 
			is a tie to the next note. = is a tie at the end of
			a beamed set.
			
	T		- text to be associated with this chord
			the music must come before text, and 
			you can replace the M or T with a tab 
			character.
			a tab in the text translates into a line feed
			and carriage return, so you can have more than one
			line of text.
			A ^ puts the following text on the top line when 
			there are two lines of music and text.
the following are currently working:
			\`a is a backslash over the letter a
			   letter takes a's place - \`letter
			\'a puts a slash / over the letter a ( or whatever 
			\^a is a circumflex over the letter a
			\"a is two dots - umlaut over the letter a
			\~a is the wiggle over the letter a
			\=a is a flat horizontal bar over the letter a
			\.a is a dot above the letter a
			\ua is breve accent
			\va is a v above the letter
			\ce is the cedilla with an e - note the space that i
			   used to be neededais no longer needed !
			\sl is a long s
			\{ is {, \} is } \) is ), \( is (
			\[ is [, \] is [
			\! and \? are turned upside down
			\ss = German ss \ae = ae \AE = AE \oe = oe \OE = OE 
			\oo = o with line through it, \OO the same
			\wt is a tie between letters 

			\C centers the title
			?` - upside down ? but \? is preferred
			!` upside down !   but \! is prefrred
			(these are just like TeX/LaTeX)
			] is a tie between letters (unless followed 
			   by }, /, or a space)
			@ is a ~ with dots for repeat in song lyrics
			| as the last letter buts the word against 
			  the next word
			you can not use < and > in text!
e		- end of document - this should be followed by a blank line

Music is written as a sequence of chords - each chord starting on the top
string, with spaces  representing unplayed strings.

b
S3
1abd a
xf
#2d   c
xc
b
1.ab  d
2 a
#2  d
... etc
 
I see this as representing tablature on its side (through a mirror)

When the document is completed, type < tab document.tab > to format it into
a file named " out.dvi ".  You can view it with xdvi (if you have xdvi )
by saying < xdvi out > - you can format it to postscrip if you have
dvips by saying < dvips out >.

If you have the postscript version of tab, then < tab file > will produce a
PostScript document that you can send to a Laserwriter or view with ghostview
or any postscript previewer.  there is a line in the file, tab.h, that
you can comment out, and the output will always be in PostScript.

Errors:

tab makes two passes to format your tablature.  The first pass reads the
input file and formats it into an internal document.  Any errors that are
detected in this pass are reported with a line number and character position
in the file.

The second pass processes the internal document into a dvi or 
PostScript format file. 

running tab with the -v option outputs the "chords" as they are
read, and also as they are processed in the second pass.  Reading the
output may help you find errors, though there is a lot of output.
Internal document errors are reported with system number, and 
"chord" number in that ystem.  In the internal format ornaments, graces,
barlines, etc are each given a seperate chord.
 
Fonts:

mk_font_local is a script which builds fonts
in your current directory.

as of 2015 TeXLive doesn't do a good job with MetaFont .. here are some tips.

1 - make plain.base
> inimf
**plain
*input local
*dump

2 - mf \&plain
*\mode=supre
*\mag=1.0




this runs on 
	sun-3 running 4.1.0 and 3.5
	sparcstation running 4.1.1
	decstation running ultrix 4.1, 4.2
	dec alphas running OSF
        silicon graphics iris IRIX 3.3.2 -> 5.2
	HP 700 running HP-UX 8.05 and 9.01
	Linux, though certain versions of the c compiler
		have troubles.
	Mac OSX in text windows


If you like it ...

   If you actually use this program and want to be notified of
updates, and maybe exchange tablature, send email to me.


	Wayne Cripps
	wbc@cs.dartmouth.edu
	June 9, 1994


p.s. -notes for PDF at
https://brendanzagaeski.appspot.com/0005.html