New.Features - abc2ps - A powerful sheet setting tool using the simple abc notation
(HTM) git clone git://vernunftzentrum.de/abc2ps.git
(DIR) Log
(DIR) Files
(DIR) Refs
---
New.Features (13234B)
---
1
2 New features in abc2ps 1.3.1 (M. Methfessel, July 1998)
3 =======================================================
4
5 The program now supports multi-stave output and has been improved
6 in various other ways. Please look at Changes for more information.
7
8
9 New features in abc2ps 1.2.4 (M. Methfessel, Feb. 1997)
10 =======================================================
11
12
13 Please also have a look at file newfeatures.abc, which
14 demonstrates many of these points.
15
16
17 ----- Bass clef -----
18
19 The bass clef is selected by appending the word "bass" to the
20 key specification. eg. "K:G bass". Notes are then drawn so
21 "C" is below the staff and "c" is in the third space from the top,
22 which is a downward shift by one line relative to the treble clef.
23
24 For in-line clef changes, use an in-line specification such as
25 [K:G bass] (was formerly \K:G bass\; this still supported).
26 If the key itself does not change, it is enough to write
27 [K:bass] and similarily [K:treble].
28
29 Added: [K:alto] makes the alto (viola or C) clef.
30
31
32 ----- Vocals -----
33
34 Aligned lyrics under the staff are specified using a line directly
35 below the staff, starting with "w:". For example:
36
37 edc2 edc2 |
38 w: Three blind mice, three blind mice
39
40 Each blank-delimited word in the "w:" line is associated with
41 one note, in sequence. The following special symbols are available
42 to modify this behaviour:
43
44 * skips one note
45 - split a word into two syllables, associated with two notes,
46 with '-' drawn between them
47 | tabs forward to the next bar line.
48 ~ is drawn as a space, but contracts words to be written under
49 one note. That is, "hey~ho" gives two words under one note.
50 _ draws a thin "underscore" from the previous note to this one.
51
52 For more than one line of lyrics, just use several w: lines.
53 To draw a '-' without breaking the word there, escape it as "\-".
54
55 Note that \\ in the abc music line now defines a staff break. This is
56 useful when typesetting vocals, because it is tedious to split
57 the line explicitly when shifting a staff break about when there
58 are lines with vocals.
59
60 If a word starts with a digit, this is interpreted as numbering of a
61 stanza and is pushed forward a bit. In other words, use something like
62 w: 1.~~Three blind mice
63 to put a number before "Three".
64
65
66 ----- Writing text between the music -----
67
68 This can be done using pseudocomments in three ways. First:
69
70 %%text This is a line of text.
71
72 writes one line into the output. Second,
73
74 %%center This is another line of text.
75
76 again writes one line, but centers it. Finally,
77
78 %%begintext
79 %%First line of text
80 %%Second line
81 %%And yet another line.
82 %%endtext
83
84 will write a block of several lines. To avoid conflict with other
85 programs, the text lines themselves are (optionally) prefaced with %%.
86
87 Statement "%%begintext" can be given a parameter to determine
88 how the output is done, namely:
89
90 %%begintext obeylines keeps lines as they are (default)
91 %%begintext ragged puts in own linebreaks to fill the line
92 %%begintext align puts in own breaks and aligns right margin
93 %%begintext skip skips the whole block, no output.
94
95 For "ragged" and "align", the program has to estimate the number of
96 lines needed in the current font, since the typesetting is done
97 using the PostScript "widthshow" operator by the printer.
98 The estimate should be reasonably reliable for Times-Roman, but might
99 be more dodgy for some other fonts. Also, note that the Ghostview fonts
100 can be quite different than the fonts used by the printer.
101 Strangely, a 13pt font can be smaller than a 12pt font.
102
103 An empty line in a block ends a paragraph (see parskipfac below).
104 In any case, \\ can be used in a line of text to add line breaks.
105 Thus, two centered lines results from this:
106 %%center First line\\second line
107
108 As with the other pseudocomments (described below), the text is
109 associated with a specific tune if it is within that tune's block.
110 In that case, it will only be printed if that tune is selected.
111 If the text is outside all tune blocks, it will always be printed.
112 The exception is if -E is used to to make a separate EPS file for
113 each tune. In this case all text outside the blocks is ignored.
114
115 The font for text output is determined as described below.
116
117
118 ----- Other pseudocomments which do something -----
119
120 %%sep - draws a short centered line as a separator
121
122 %%sep h1 h2 len - draws a separator of length len with space
123 h1 above, space h2 below.
124
125 %%vskip h - adds vertical space of height h
126
127
128 %%newpage - writes a page break
129
130
131 Dimensions can be given in cm, in, or pt, where pt is the default.
132 Examples: "%%sep 1cm 1cm 4cm" or "vskip 1.5cm".
133
134
135 ----- Output formating -----
136
137 The user can now tailor the appearance of the output page.
138 This is done by setting formating parameters, for example:
139
140 pageheight 29cm % height of page
141 staffwidth 5in % width of staff
142 leftmargin 1.8cm % left margin
143 titlefont Times-Roman 14 % the font for the title
144 titlespace 1cm % vertical space before the title
145 scale 0.9 % size of musical symbols
146 staffsep 60pt % space between staves
147
148 Use abc2ps -H to see the current values of these parameters.
149
150 To specify the parameters, there are four levels:
151
152 1. By default, a predefined set called "standard" is used.
153 With flag -p, an alternative "pretty" set is taken.
154 With flag -P, a third set "pretty2" is used.
155 Users are encouraged to make their own choices for these styles
156 and change the program accordingly (see routines
157 set_standard_format, set_pretty_format, set_pretty2_format
158 in file format.h).
159
160 2. Commands to set the parameters can be grouped into a file
161 with extension "fmt", which can then be selected by flag -F.
162 For example: there should be a file landscape.fmt in the
163 distribution. This changes the page orientation to landscape
164 and sets the page height and width accordingly, and also changes
165 the title style a bit. To output file scotland.abc in landscape,
166 the command is
167 abc2ps scotland.abc -F landscape -o
168
169 3. An abc file can contain pseudocomments (%%..) such as:
170 %%staffwidth 16cm
171 %%titlespace 1.4cm
172 Depending on the position, the changes to the style parameters
173 are either global for the rest of the file, or local to a single
174 tune. The change is global if the line is outside any tune block
175 (where a tune block starts with "X:" and ends with a blank line).
176 If the pseudocomment is within such a block, the parameter change
177 is only applied for this tune.
178 Note that the program cannot determine if a tune is selected
179 before it knows the title, so such a local pseudocomment should
180 come after the "T:" line.
181
182 4. Some of the command-line flags change the style parameters, eg:
183 -s 0.9 (sets symbol scale)
184 -m 2cm (sets left margin) etc.
185 Type "abc2ps -h" for a list of flags.
186
187 The priorities are in the sequence given above. That is, the ".fmt"
188 file overrides the predefined format, pseudocomments overide that,
189 and a command-line flag overrides everything else.
190
191
192 Some more details:
193
194 1. Format files are searched in the current directory. In abc2ps.c,
195 the line "#define DEFAULT_FDIR .." can be used to set a default
196 directory which is searched whenever a fmt file is not local.
197 Flag -D can also be used to specify this default directory.
198 (The idea is, even if a PC user only has the executable available,
199 he could make something like an alias to get his standard
200 fmt directory into the path.)
201
202 2. To see the settings for all the parameters, use flag -H.
203 When used in conjunction with other flags such as -p, -P, or -F,
204 the corresponding parameters are shown. If you redirect the
205 output to a file and edit out the header line, you immediately
206 have a prototype fmt file which specifies all the parameters.
207
208 3. Dimensions can be specified either as pt, cm, or in. Default is pt.
209 So, "%%staffwidth 20" will lead to very short lines!
210
211 4. Pseudocomments which are not recognized are ignored silently.
212 The idea is that other program can define their own.
213 It also means that when things frustratingly don't seem to work,
214 the reason might be a spelling mistake.
215
216 5. Because ISO fonts are needed for special characters and
217 accents, all fonts must be known when the header of the PS file
218 is written. The program tries to be as clever as it can
219 about this, but a font might be undefined if it is invoked
220 for the first time further down in a file. For this reason,
221 a line like this can be put into the fmt file:
222
223 font Palatino-Bold
224
225 or alternatively at the top of the abc file:
226
227 %%font Palatino-Bold
228
229 Either of these will define the corresponding ISO font in the header.
230 To make things even easier, the program always looks for a file
231 "fonts.fmt" and loads it if it exists. So, the often-used fonts
232 can be defined there once and for all.
233
234 6. The default page dimensions are set by defines in abc2ps.c
235 and then used in format.h to intialize the predefined formats.
236 Change these if the standard paper will not be Din A4.
237 The relevant lines in abc2ps.c are these:
238
239 #define PAGEHEIGHT 29.7 /* basic page dimensions in cm.. */
240 #define LEFTMARGIN 1.8 /* .. used in all default formats */
241 #define STAFFWIDTH 17.4
242
243 7. A line consisting of the word "end" in a fmt file skips the
244 rest of the file.
245
246
247 ----- List of format parameters -----
248
249 Parameters without explanation are deemed obvious.
250
251 pageheight
252 staffwidth
253 topmargin
254 botmargin
255 leftmargin
256 topspace vertical space at the top of a tune.
257 titlespace space before the title.
258
259 Note: Usually, one sees only the sum of these two.
260 However, if text is written preceeding a tune, it
261 will come after "topspace" and before "titlespace".
262
263 subtitlespace space before the subtitle.
264 composerspace space before the composer.
265 musicspace space between the composer and the music.
266 partsspace space ("up") between the "parts" and the music.
267 vocalspace space above a line of vocals.
268 wordsspace space aboove the words at the end of a tune.
269 textspace space above the text such as history (flag -n).
270
271 Note: these spaces count to the top of a line of text.
272 That is, the relevant text size (eg. "12pt") is added.
273
274 staffsep separation between staves. One-half of this
275 distance is added above and below each staff.
276 scale symbol size; eg. 1.0 is used in the "pretty" output.
277 maxshrink how much to compress horizontally when staff breaks
278 are chosen automatically. Between 0 and 1.
279
280 titlefont Font for title, ie: Times-Roman 14
281 subtitlefont
282 composerfont
283 partsfont
284 vocalfont for vocals under a staff (w: field)
285 gchordfont for guitar chords
286 textfont for text under the tune, or between tunes
287 wordsfont for words under the tune (W: field)
288 lineskipfac dimensionless factor for spacing between lines of text:
289 1.0 gives single-space output, 2.0 double etc.
290 parskipfac similar factor for space after a paragraph of text.
291 barsperstaff same as flag -B
292 landscape (logical) landscape orientation if true
293 titleleft (logical) title flushed left if true.
294 titlecaps (logical) title in capital letters
295 musiconly (logical) no vocals if true (equivalent to flag -M)
296 stretchstaff (logical) stretches underfull staves across page
297 stretchlast (logical) stretches last staff if underfull.
298 writehistory (logical) writes notes, history etc if true;
299 continueall (logical) continue all lines if true (same as -c).
300 breakall (logical) break at all line ends (same as -b).
301 oneperpage (logical) each tune on separate page (same as -1)
302 withxrefs (logical) print out X: xref number in title (same as -x).
303
304 Logicals can be specified as follows;
305 One of: 1 yes true gives true
306 One of: 0 no false gives false.
307 If nothing is specified, this is equivalent to true.
308
309
310 ----- Summary of tune layout -----
311
312 To summarize: the layout of a tune is done as follows.
313 Starting from the current position on the page,
314
315 First write the header:
316 go down by topspace, write text if any is specified;
317 go down by titlespace, write the main title;
318 for each subtitle, go down subtitlespace and write it;
319 go down composerspace, write the composer lines;
320 go down musicspace and go up by partsspace, write the parts.
321
322 Next, starting from musicspace below the composer:
323 For each staff:
324 go down by staffsep/2;
325 write the staff;
326 for vocals, go down by vocalspace and write them;
327 go down another staffsep/2.
328 Note that everything here (including the spaces and fonts)
329 are scaled by "scale".
330
331 Finally:
332 if words are included, go down wordsspace and write them;
333 if history/notes are included, go down textspace and write them.
334 Hereby lineskip and parskip given by "lineskipfac" and "parskipfac".