Description of abc2ps (version 1.2) =================================== Program abc2ps reads an input file containing music in abc format and typesets it directly in PostScript. It can also be used to list the contents of an abc file. For a description of the abc syntax, please see the abc userguide which is a part of the abc2mtex package written by Chris Walshaw. ----- Files ----- ReadMe.abc2ps this file License GNU general public license Changes history of changes to the program New.Features description of new features in 1.2.5 layout.txt information about the music layout abc2ps.c main program buffer.h routines to control the output buffer format.h routines for output formatting syms.h routines to define postscript macros subs.h general routines util.h more general routines pssubs.h routines for postscript output parse.h routines to parse input lines music.h routines to typeset music style.h parameters for music layout style.pure alternative style file for "puristic" layout sample.abc input for demo and test .abc sample input files ----- Installation ----- This is a single C program, consisting of file abc2ps.c and some include files *.h. It can be compiled in the usual way to make the executable abc2ps: cc -o abc2ps abc2ps.c To test the program, unleash it on file sample.abc like this: ./abc2ps sample -o The result can be inspected by using a PostScript previewer such as ghostview on the output file Out.ps. Possible problems: By default, the generated PostScript is level 2 since it uses the operator "selectfont". If you want level 1 output instead, set macro PS_LEVEL to 1 in abc2ps.c. Sometimes problems arise with the "stat" function. This used at the end of the program to determine the size of the output file. The call to 'stat' is in routine get_file_size in file subs.h. This file also contains an alternative plodding version of get_file_size, which can be used if the 'stat' version causes problems. Alternatively, just throw out the call to get_file_size in the bottom of abc2ps.c and change the printf statement accordingly... printing out the file size is only for user information. ----- Program structure ----- The program defines a number of PostScript macros for drawing elementary components like note heads, stems, flags, bars, rests etc. These definitions are written to the output file Out.ps first. The symbols are mostly defined using Bezier curves. At some stage, the macros should probably be changed to user paths for more efficiency. The input lines are read and interpreted one at a time. The processing of the info fields is straightforward. The main work is done for lines of music. Such a line is parsed into a list of symbols. To position the symbols horizontally along the staff, the program uses a method adapted from the "glue" used Donald E. Knuth in the TeX program. The algorithm calculates three separate sets of spacings: "shrink": put the symbols as close together as is acceptable; "space": space the symbols "naturally", whereby the space behind a note reflects its length; "stretch": make a similar but stretched layout which still looks good. To fill the staff, the spacings are interpolated between the "shrink" and "space" cases (if the sum of the natural spacings is larger than the staff length) or between the "space" and "stretch" cases (if the sum of the natural spacings is too short). After the positions of all symbols are decided, lines are written to Out.ps to invoke the previously defined PostScript macros with suitable parameters. File "layout.txt" gives information on the positioning and how to modify the layout. ----- Page breaking ----- Page breaking: version 1.2 avoids splitting a tune over pages as much as possible. For each tune, the program checks whether the remaining space on the page is large enough to fit it in. If not, a page break is put in before the tune. To do this, the Postscript output is accumulated in a buffer first. For really large tunes, the buffer might overflow. In that case, the output is just written out without attempting to place the page breaks cleverly. ----- Line breaking ----- The best output is usually obtained if the staff breaks are chosen explicitly by suitable line breaks in the input file. In this standard usage, the program tries to set the music as well as possible for each line separately. The symbols '*' and '**' at the end of a line are ignored, as well as the field 'E:' for the elementary length. However, if a line is too long to fit onto one staff, the overhang is spilled onto the next staff in this version. This makes it possible to get reasonable output even when the input is one long logical line. In practice, this is equivalent to automatic line breaking. To control line breaking, the following flags are available: -b break at all line ends, even if they end with the continuation symbol '\'. -c consider the input as one long line, ie., implicitly append the continuation symbol '\' to every line of music. -B n try to typeset with n bars on each line. -a x set the maximal amount of permitted shrinking to x, where x lies between 0 and 1. If none of these is specified, the standard line-by-line procedure is followed, ie: abc2ps infile -o For completely automatic line breaking, use the command abc2ps infile -c -o This should produce reasonable staff breaks in most cases. However, repeat bars, 1st and 2nd endings, and slurs might not be positioned very nicely. When doing automatic line breaking with -c, the user can control the spacing of the symbols along the staff by specifying the "compression parameter" alfa with the -a flag. A value of 0.0 means that no shrinking is allowed, and a value of 1.0 allows shrinking until the symbols are almost touching. When -c is used, by default alfa is set to an intermediate value (displayed with 'abc2ps -c -h'). When -c is not used, maximal shrinking and stretching are allowed. Thus, to really squeeze everything as much as possible, that is, to get automatic line breaking together with maximal shrinking, use abc2ps infile -c -o -a1 For more stretched output, use (for example) abc2ps infile -c -o -a 0.2 The flag "-B n" formats with n bars on each line. This is useful e.g. to try various spacings before deciding on how to set the linebreaks explicitly in the file. There is not complete agreement on what output should be generated when a staff is underfull, which happens when maximal stretching is not sufficient to fill the staff. The behaviour can be determined by the following macros in abc2ps.c: STRETCH_MODE: allowed values are 0 music for undefull staves is bunched to the left. 1 music for underfull staves is left-bunched for the last staff only. 2 underfull staves are spread over the whole staff. STRETCH_STAFF: allowed values are 0 when music is bunched to the left, the staff is also shortened. 1 staff lines are always drawn all the way across the page. Abc2ps 1.2 tries to take care of slurs and 1st & 2nd endings at the line breaks. But in general, a tune will look a substantially better when the breaks are chosen by hand. ----- General usage ----- Basically, the usage is: abc2ps file1 file2.. where file1, file2.. are the abc input files. This will list the file contents. To generate Postscript output, add flag -o: abc2ps file1 file2.. -o Note that most flags (see below) can be used in any sequence. Of course, the position does matter for flags e,f,C,S,R,T since these determine how the following arguments are interpreted. Flags can be contracted together if the meaning is clear, and a numerical argument for the last flag can be appended. That is, '-b -s 0.7 -v 1' can be contracted to '-bs0.7 -v1'. ----- Tune selection ----- To select specific tunes from the files, use abc2ps file1 file2.. -e selector1 selector2 ... where each selector is a set of xref numbers or a pattern. Without -o, this will list only the selected tunes found in the files. With -o, output is generated only for the selected tunes. Examples: To list all the tunes in a file, say book1 or book1.abc (whichever exists): abc2ps book1 To list selected tunes: abc2ps book1 -e 1-3 5,20- 'House*' Hall This selects xref numbers 1 to 3, 5, and 20 and above, as well as those tunes whose title either starts with "House" or contains the string "Hall". A pattern without wildcards such as 'Hall' is treated as '*Hall*' Optionally, the search can be done on other fields using these flags in place of -e: flag -R seaches the rhythm field flag -C searches the composer field flag -S searches the source field. flag -T seaches the title field (default) Thus abc2ps book1 -C "John" selects all tunes whose composer string contains "John". If the -C flag is used, the composer field is also displayed when the file are listed. The same goes for the flags -R and -S. Flag -A selects all tunes, overriding other selectors. ----- Selection on multiple input files ----- To filter several files with the same set of selectors, the format is: abc2ps file1 file2 -e selectors... To use a different set of selectors for the separate files, use a command such as abc2ps file1 -e 1-3 -f file2 file3 -R Jig This will select tunes 1-3 from file1 and the tunes with 'Jig' in the rhythm field from file2 and file3. More precisely, flag -f indicates that the following arguments (up to the next -e flag) are file names. Each set of selectors is applied to the files preceeding it. As before, the flags -C -S -R can be used in place of -e to change the searched field. For convenience, there are two conventions: 1. An argument with the extension .abc is always assumed to be a file name, and is treated as if it were preceeded by the flag -f. 2. An argument which is obviously a set of xref numbers is assumed to be a selector, and is treated as if it were preceeded by the flag -e. For example, these three commands all select tunes 1-3 from A.abc and tunes 5-7 from B.abc: abc2ps A.abc -e 1-3 -f B.abc -e 5-7 abc2ps A.abc -e 1-3 B.abc -e 5-7 abc2ps A.abc 1-3 B.abc 5-7 On the other hand, this will NOT work in the expected way: abc2ps A 1-3 B 5-7 -o because the program has no way of knowing that B is an input file name and not a pattern selector. For complicated selections on multiple input files, it might be better to run the program interactively (see below). ----- Making Postscript output ----- By adding flag '-o', the selected tunes are typeset and written to the output file. To typeset all tunes in file "book1.abc": abc2ps book1 -o To typeset selected tunes, use a command such as abc2ps book1 -e 1-3 5,20- 'House*' Hall -o The idea is to vary the numbers and/or patterns until the desired titles are listed, then add -o to the argument list to make the output file. By default, all selected tunes are written into the same file, with suitable page breaks added. By using the flag -E, EPSF output is made. Each tune is then put into a separate file with a correct bounding box and no page breaks. Flag -O determines where the output goes. The argument to -O can be either a file name or the '=' sign. The latter case tells abc2ps to choose the name by itself. For the PS and EPS modes, the output file names are: PS mode: default Out.ps -O NAME NAME.ps -O = Output for "foo.abc" is written to "foo.ps" EPSF: default Outnnn.eps, where nnn is a running index -O NAME NAMEnnn.eps -O = Outfile name is .eps Note: an output file is overwritten if it already exists. This will happen if two tunes have the same name and flag "-O =" is used for EPSF output. ----- Modifying the output ----- These flags change the output appearance: -x includes the xref numbers in the tune title. -1 writes every tune on a separate page. -n includes historical notes and other stuff at the bottom of each tune. -p generates pretty output, with more whitespace between tunes, larger fonts for titles, and larger music symbols. By default, the layout squeezes the tunes to reduce the number of pages. -s xxx scales the music output by factor xxx. -w www sets the width of the staff to www points. -m mmm sets the left margin to mmm points. -g shrink|space|stretch|fill sets the "glue mode". The default mode is fill, which fills the staff. This flag is useful when changing the layout parameters, to see what effect the changes have for each mode separately. -B n format with n bars on every staff -b forces a staff break at the end of each line, even if the line has the continuation symbol \ at the end. -c append the continuation symbol to all music lines, which amounts to automatic line breaking. -a x set the maximal allowed shrinkage to x, where x lies between 0.0 and 1.0 ----- On-line help ----- Flags for on-line help: -h quick help, equivalent to "abc2ps" without any arguments. This also shows the default settings for some parameters. -v n sets the verbosity for output to the screen to n. Hereby -v0 gives very little, -v1,v2,v3.. show successively more information. Verbosity >= 10 is for debugging. -V shows the version number. ----- Interactive mode ----- If the command list contains the flag -i, abc2ps runs in interactive mode. This makes it possible to build up an output file piece by piece. The disadvantage is that you have to start over if you make a mistake. Interactive mode is started with abc2ps -i The program then prompts for input with the line select tunes: The response should be a row of arguments, which are treated in exactly the same way as in the non-interactive mode. The only difference is that the input is not first run through the shell, so that wildcards are not expanded and quotes are not removed. Consequently Jig* should be used instead of 'Jig*' etc. when specifying strings for selection, and filenames must be written out in full. To exit from interactive mode, enter 'q', 'quit' or an empty input. For example, a "session" could look like this: abc2ps -i start abc2ps interactively book1 list tunes in book1.abc book1 -e 1-10 list tunes with xrefs 1-10 in book1 book1 -e 1-10 -o write these to Out.ps book2 list tunes in book2.abc book2 -e House -o write tunes with 'House' in the title quit exit abc2ps To make things easier, there are three special characters: ? shows the last input used; ! at the start of line is substituted by the last files used; * at the start of line is substituted by the last input. This means that the same effect as above can be obtained in shorter form like this: abc2ps -i start abc2ps interactively book1 list tunes ! 1-10 equivalent to 'book1 1-10' * -o equivalent to 'book1 1-10 -o' book2 list tunes in book2.abc ! -e House -o equivalent to 'book2 -e House -o' q exit abc2ps Note that the -e flag is not needed in the line '* 1-10' because it is clear that '1-10' is a selector (see above). Another point is that if additional flags are used when starting interactively, these function as defaults for the interactive mode. For example, by starting the program with abc2ps -io all selected tunes are immediately written to the output file. The program usage is then very similar to that of abc2mtex. Of course, it is not possible to list the file contents (to help choose among the titles) when using the program in this way. In interactive mode, flags -O -E can be used as before to redirect the output. When switching to another output file, the previous file is closed. Switching back to the same file later will overwrite the file. ----- Examples ----- These examples assume that wildcards '*' in the argument list are automatically expanded out by the operating system, as happens e.g. under the C shell under Unix. If not, the input files should be specified explicitly, that is: abc2ps x1.abc x2.abc x3.abc instead of abc2ps x*.abc To list the contents of file 'mytunes.abc': abc mytunes.abc To typeset all tunes in 'mytunes.abc': abc mytunes.abc -o To typeset all tunes, choosing all line breaks automatically: abc mytunes.abc -o -c To do the same, but squeeze notes together more: abc mytunes.abc -o -c -a0.9 To list the contents of all abc files in the current directory: abc2ps *.abc To search all abc files for tunes containing 'House' in the title: abc2ps *.abc -e House To list the contents of all abc files, showing the Rhythm field also: abc2ps *.abc -R To search all abc files for tunes with rhythm 'jig' or 'Jig': abc2ps *.abc -R jig Jig To do the same while avoiding cases like 'slip jig': abc2ps *.abc -R 'jig*' 'Jig*' To output all tunes by composer 'Carolan' in all abc files: abc2ps *.abc -C Carolan -o To output tunes 1 to 10 in A.abc and 11-20 in B.abc: abc2ps A -e 1-10 -f B -e 11-20 -o or abc2ps A.abc 1-10 B.abc 11-20 -o or abc2ps A 1-10 B.abc 11-20 -o To output all tunes with the string 'House' in the title or with xref numbers 10-12, in all abc files whose name starts with X, including historical notes and xref numbers in the output, forcing a line break at continuation lines, with reduced size of the symbols, putting one tune per page: abc2ps X*.abc -e House 10,11,12 -onx -s0.9 -b1 ----- Differences to abc2mtex ------ Essentially, all features described in the abc2mtex userguide should work. The are a few exceptions: - The slur denotation S was replaced by the syntax (...) (see below) - Key signatures HP and Hp probably aren't treated in exactly the right way. - There is no automatic beam checking. - There is no way to automatically transpose music in this version. ----- Some extra features --- ----- For examples, see file sample.abc. - Codes for decorations: including the ones defined in the standard abc syntax, the following decorations are interpreted: . dot, staccato J slide M bar (M='em-phasis') H hold sign (fermata) ~ gracing R roll u up-bow v down-bow - Escape sequences: embedding a string between two backslashes in a music line delimits an escape sequence. In the present version, these are treated as information fields. This makes it easy to change key, meter, or default length within a line (see sample.abc). - N-tuplets: abc2ps can handle general n-tuplet cases using the syntax (p:q:r abcd .. This means "put p notes into the time of q for the next r notes." If q is not given, it defaults as described in the abc2mtex user guide. If r is not given, it defaults to p. For example: (3::2 = (3:2:2 ; (3 = (3:2:3 The number written over the n-plet is p. This generalized syntax is compatible with the older usage. Actually, q is not used at all here; it is only relevant for programs which play the music. - Chords: The program accepts the +...+ notation, but it seems more intuitive to use some kind of brackets to group together the notes which make a chord. This program will accept square brackets: [ace][adf] in place of the +..+ syntax. The abc notation formally permits notes with different durations on the same stem: [a/bc2] and so on. This program assigns all notes in a chord the duration of the first note in the bracket. A chord with two identical notes makes a union (one head with stems going both up and down), eg: [AA]. - Slurs and ties: in place of the syntax "SabcSd" for a slur over notes abcd, this program uses the notation (abcd) for a slur over the notes abcd. It permits cases such as (ab(cd)) and ((ab)cd) and (a(bc)d) and similar slurs-below-slurs. To connect three or four notes by ties (e.g., for a note held over several bars) use (a(b)c) or by ties a-b-c The rule is that any note alone within brackets like (b) terminates a previous slur and at the same time starts a new one. Note that the slur syntax (..) does not interfere with the (3abc style for n-tuplets. If a bracket '(' is followed by a digit k, it is interpreted as the start of a k-tuplet, otherwise it is the start of a slur. For example, a slur is put over the last two triplets in this line: (3abc ((3cde) ((3efg). An unbalanced parenthesis ')' or '(' indicates the continuation of a slur on a neighboring line. This is needed (for example) in order to make automatic line breaking possible. It will also lead to unexpected strange-looking additional slurs if the input file contains the wrong syntax (3abc) instead of (3abc for triplets. - Bars: The following symbols denote fat double bars at the start or end of a piece (without repeat dots). Namely: [| for thick-thin, |] for thin-thick. For better results when using automatic line breaking, the program will split up some types of bars when these are at the end of a line, for example: :: becomes :| together with |: on the next line |: becomes | together with |: on the next line :|2 becomes :| together with [2 on the next line etc. - Field E: this field can be used to set some parameters from within the file: shrink set glue mode to compress space set to natural glue widths stretch stretched glue mode fill normal mode to fill staffs break ignore continuations xref write xref numbers to output one write one tune per page. newpage start new page for next tune lw ppp set local staff width to ppp points. For example, to output a single tune in a narrower format, put 'E:lw 400' into the header of this tune. If this is put after the header but within the tune body, only the music is set with a different width and the title is written as before. ----- Customization ----- 1. First of all, the horizontal layout of the notes can be changed extensively. This is described in 'layout.txt'. 2. Then there are a number of macros in the main program abc2ps.c which determine the page layout, ie: PAGEHEIGHT height of paper PAGEWIDTH width of paper The following block determines the layout in the "pretty" mode (-p). The numbers are various font sizes, skips between tunes etc., the seperation between staffs, and page margins. A similar block (MAINTITLE2 ...) defines the normal, more compact mode. MAINTITLE1 18 SUBTITLE1 15 SUBSUBTITLE1 12 ASKIP1 0.6 * CM BSKIP1 0.6 * CM CSKIP1 1.2 * CM DSKIP1 0.5 * CM TOP_SEP1 25 BOT_SEP1 25 LSCALE1 0.8 LMARGIN1 1.5 * CM RMARGIN1 2.0 * CM TMARGIN1 2.0 * CM BMARGIN1 1.0 * CM For example, the default staff width is calculated from these parameters as PAGEWIDTH-LMARGIN-RMARGIN. The flags -w and -m change this width and the left margin, respectively. 3. The behavior for underfull lines can be chosen (see "Line breaks"). Also consider these two parameters: ALFA_C default compression when using the -c flag. BETA_X maximal expansion allowed before considering a staff underfull. Thus, setting BETA_X to 100.0 lets lines be stretched to any arbitrary amount quietly. 4. Parameters which influence the musical symbols (all dimensions are in pt, relative to a fundamental spacing between staff lines of 6pt): DECO_IS_ROLL How gracings ~ are interpreted. For 0, draws a trill sign. For 1, draws a roll sign (cap) over the note. LSCALE0 Overall scale factor. The "internal" height for the staff is 24 pt, that is, 6 pt between the lines. This is rather big, so LSCALE0 scales the size down. BASEWIDTH Width of lines within music (bars, stems etc). SLURWIDTH Width of Bezier curves when drawing slurs. STEM_YOFF Offset of stem from note head center, y direction STEM_XOFF Offset of stem from note head center, x direction STEM Standard stem length for single notes. STEM_MIN Minimal stem length when drawing beams. STEM_CH Standard stem length for chords. STEM_CH_MIN Minimal stem length for chords under beams. BEAM_DEPTH Width of the horizontal stroke for beams. BEAM_SHIFT How far the second, third beams are shifted up or down. BEAM_FLATFAC Long beams are drawn with slope reduced by this factor. BEAM_THRESH If the slope of a beam lies below this threshold, it is drawn with slope zero. MAX_SLOPE Upper limit for the slope of a beam. DOTSHIFT Extra shift, to avoid putting the dot into the flag on some notes. GSTEM Grace note stem length. GSTEM_XOFF Offset of grace note stem to head center. GSPACE0 Space between grace note and main note. GSPACE Space between grace notes. ----- Summary of differences to version 1.1 ----- - better page breaking - automatic line breaking possible - EPSF output possible - Slurs improved; slurs to previous/next staff allowed. - New decorations: fermata, bar, up/down bow, roll sign, slide - unions as [aa] - thick-thin and thin-thick bars now [| and |] - normal or pretty output, depending on flag -p - horizontal beams positioned more cleverly - n-plets can contain rests, eg. (3zab or (3azb; uses brackets if the notes are not all on one beam. - general n-plet syntax (p:q:r added ---- Feedback ------- Any suggestions for improvement or bug reports are welcome. Michael Methfessel (msm@ihp-ffo.de), June 1996.