[This describes Michael's last version of abc2ps. It's kept here mostly for historical reasons. -jc] New features in abc2ps 1.3.1 (M. Methfessel, July 1998) ======================================================= The program now supports multi-stave output and has been improved in various other ways. Please look at Changes for more information. New features in abc2ps 1.2.4 (M. Methfessel, Feb. 1997) ======================================================= Please also have a look at file newfeatures.abc, which demonstrates many of these points. ----- Bass clef ----- The bass clef is selected by appending the word "bass" to the key specification. eg. "K:G bass". Notes are then drawn so "C" is below the staff and "c" is in the third space from the top, which is a downward shift by one line relative to the treble clef. For in-line clef changes, use an in-line specification such as [K:G bass] (was formerly \K:G bass\; this still supported). If the key itself does not change, it is enough to write [K:bass] and similarily [K:treble]. Added: [K:alto] makes the alto (viola or C) clef. ----- Vocals ----- Aligned lyrics under the staff are specified using a line directly below the staff, starting with "w:". For example: edc2 edc2 | w: Three blind mice, three blind mice Each blank-delimited word in the "w:" line is associated with one note, in sequence. The following special symbols are available to modify this behaviour: * skips one note - split a word into two syllables, associated with two notes, with '-' drawn between them | tabs forward to the next bar line. ~ is drawn as a space, but contracts words to be written under one note. That is, "hey~ho" gives two words under one note. _ draws a thin "underscore" from the previous note to this one. For more than one line of lyrics, just use several w: lines. To draw a '-' without breaking the word there, escape it as "\-". Note that \\ in the abc music line now defines a staff break. This is useful when typesetting vocals, because it is tedious to split the line explicitly when shifting a staff break about when there are lines with vocals. If a word starts with a digit, this is interpreted as numbering of a stanza and is pushed forward a bit. In other words, use something like w: 1.~~Three blind mice to put a number before "Three". ----- Writing text between the music ----- This can be done using pseudocomments in three ways. First: %%text This is a line of text. writes one line into the output. Second, %%center This is another line of text. again writes one line, but centers it. Finally, %%begintext %%First line of text %%Second line %%And yet another line. %%endtext will write a block of several lines. To avoid conflict with other programs, the text lines themselves are (optionally) prefaced with %%. These can also be spelled %%textbegin and %%textend. Statement "%%begintext" can be given a parameter to determine how the output is done, namely: %%begintext obeylines keeps lines as they are (default) %%begintext ragged puts in own linebreaks to fill the line %%begintext align puts in own breaks and aligns right margin %%begintext skip skips the whole block, no output. For "ragged" and "align", the program has to estimate the number of lines needed in the current font, since the typesetting is done using the PostScript "widthshow" operator by the printer. The estimate should be reasonably reliable for Times-Roman, but might be more dodgy for some other fonts. Also, note that the Ghostview fonts can be quite different than the fonts used by the printer. Strangely, a 13pt font can be smaller than a 12pt font. An empty line in a block ends a paragraph (see parskipfac below). In any case, \\ can be used in a line of text to add line breaks. Thus, two centered lines results from this: %%center First line\\second line As with the other pseudocomments (described below), the text is associated with a specific tune if it is within that tune's block. In that case, it will only be printed if that tune is selected. If the text is outside all tune blocks, it will always be printed. The exception is if -E is used to to make a separate EPS file for each tune. In this case all text outside the blocks is ignored. The font for text output is determined as described below. ----- Other pseudocomments which do something ----- %%sep - draws a short centered line as a separator %%sep h1 h2 len - draws a separator of length len with space h1 above, space h2 below. %%vskip h - adds vertical space of height h %%newpage - writes a page break Dimensions can be given in cm, in, or pt, where pt is the default. Examples: "%%sep 1cm 1cm 4cm" or "vskip 1.5cm". ----- Output formating ----- The user can now tailor the appearance of the output page. This is done by setting formating parameters, for example: pageheight 29cm % height of page staffwidth 5in % width of staff leftmargin 1.8cm % left margin titlefont Times-Roman 14 % the font for the title titlespace 1cm % vertical space before the title scale 0.9 % size of musical symbols staffsep 60pt % space between staves Use abc2ps -H to see the current values of these parameters. To specify the parameters, there are four levels: 1. By default, a predefined set called "standard" is used. With flag -p, an alternative "pretty" set is taken. With flag -P, a third set "pretty2" is used. Users are encouraged to make their own choices for these styles and change the program accordingly (see routines set_standard_format, set_pretty_format, set_pretty2_format in file format.h). 2. Commands to set the parameters can be grouped into a file with extension "fmt", which can then be selected by flag -F. For example: there should be a file landscape.fmt in the distribution. This changes the page orientation to landscape and sets the page height and width accordingly, and also changes the title style a bit. To output file scotland.abc in landscape, the command is abc2ps scotland.abc -F landscape -o 3. An abc file can contain pseudocomments (%%..) such as: %%staffwidth 16cm %%titlespace 1.4cm Depending on the position, the changes to the style parameters are either global for the rest of the file, or local to a single tune. The change is global if the line is outside any tune block (where a tune block starts with "X:" and ends with a blank line). If the pseudocomment is within such a block, the parameter change is only applied for this tune. Note that the program cannot determine if a tune is selected before it knows the title, so such a local pseudocomment should come after the "T:" line. 4. Some of the command-line flags change the style parameters, eg: -s 0.9 (sets symbol scale) -m 2cm (sets left margin) etc. Type "abc2ps -h" for a list of flags. The priorities are in the sequence given above. That is, the ".fmt" file overrides the predefined format, pseudocomments overide that, and a command-line flag overrides everything else. Some more details: 1. Format files are searched in the current directory. In abc2ps.c, the line "#define DEFAULT_FDIR .." can be used to set a default directory which is searched whenever a fmt file is not local. Flag -D can also be used to specify this default directory. (The idea is, even if a PC user only has the executable available, he could make something like an alias to get his standard fmt directory into the path.) 2. To see the settings for all the parameters, use flag -H. When used in conjunction with other flags such as -p, -P, or -F, the corresponding parameters are shown. If you redirect the output to a file and edit out the header line, you immediately have a prototype fmt file which specifies all the parameters. 3. Dimensions can be specified either as pt, cm, or in. Default is pt. So, "%%staffwidth 20" will lead to very short lines! 4. Pseudocomments which are not recognized are ignored silently. The idea is that other program can define their own. It also means that when things frustratingly don't seem to work, the reason might be a spelling mistake. 5. Because ISO fonts are needed for special characters and accents, all fonts must be known when the header of the PS file is written. The program tries to be as clever as it can about this, but a font might be undefined if it is invoked for the first time further down in a file. For this reason, a line like this can be put into the fmt file: font Palatino-Bold or alternatively at the top of the abc file: %%font Palatino-Bold Either of these will define the corresponding ISO font in the header. To make things even easier, the program always looks for a file "fonts.fmt" and loads it if it exists. So, the often-used fonts can be defined there once and for all. 6. The default page dimensions are set by defines in abc2ps.c and then used in format.h to intialize the predefined formats. Change these if the standard paper will not be Din A4. The relevant lines in abc2ps.c are these: #define PAGEHEIGHT 29.7 /* basic page dimensions in cm.. */ #define LEFTMARGIN 1.8 /* .. used in all default formats */ #define STAFFWIDTH 17.4 7. A line consisting of the word "end" in a fmt file skips the rest of the file. ----- List of format parameters ----- Parameters without explanation are deemed obvious. pageheight staffwidth topmargin botmargin leftmargin topspace vertical space at the top of a tune. titlespace space before the title. Note: Usually, one sees only the sum of these two. However, if text is written preceeding a tune, it will come after "topspace" and before "titlespace". subtitlespace space before the subtitle. composerspace space before the composer. musicspace space between the composer and the music. partsspace space ("up") between the "parts" and the music. vocalspace space above a line of vocals. wordsspace space aboove the words at the end of a tune. textspace space above the text such as history (flag -n). Note: these spaces count to the top of a line of text. That is, the relevant text size (eg. "12pt") is added. staffsep separation between staves. One-half of this distance is added above and below each staff. scale symbol size; eg. 1.0 is used in the "pretty" output. maxshrink how much to compress horizontally when staff breaks are chosen automatically. Between 0 and 1. titlefont Font for title, ie: Times-Roman 14 subtitlefont composerfont partsfont vocalfont for vocals under a staff (w: field) gchordfont for guitar chords textfont for text under the tune, or between tunes wordsfont for words under the tune (W: field) lineskipfac dimensionless factor for spacing between lines of text: 1.0 gives single-space output, 2.0 double etc. parskipfac similar factor for space after a paragraph of text. barsperstaff same as flag -B landscape (logical) landscape orientation if true titleleft (logical) title flushed left if true. titlecaps (logical) title in capital letters musiconly (logical) no vocals if true (equivalent to flag -M) stretchstaff (logical) stretches underfull staves across page stretchlast (logical) stretches last staff if underfull. writehistory (logical) writes notes, history etc if true; continueall (logical) continue all lines if true (same as -c). breakall (logical) break at all line ends (same as -b). oneperpage (logical) each tune on separate page (same as -1) withxrefs (logical) print out X: xref number in title (same as -x). Logicals can be specified as follows; One of: 1 yes true gives true One of: 0 no false gives false. If nothing is specified, this is equivalent to true. ----- Summary of tune layout ----- To summarize: the layout of a tune is done as follows. Starting from the current position on the page, First write the header: go down by topspace, write text if any is specified; go down by titlespace, write the main title; for each subtitle, go down subtitlespace and write it; go down composerspace, write the composer lines; go down musicspace and go up by partsspace, write the parts. Next, starting from musicspace below the composer: For each staff: go down by staffsep/2; write the staff; for vocals, go down by vocalspace and write them; go down another staffsep/2. Note that everything here (including the spaces and fonts) are scaled by "scale". Finally: if words are included, go down wordsspace and write them; if history/notes are included, go down textspace and write them. Hereby lineskip and parskip given by "lineskipfac" and "parskipfac".