ReadMe.abc2ps - abc2ps - A powerful sheet setting tool using the simple abc not… | |
git clone git://vernunftzentrum.de/abc2ps.git | |
Log | |
Files | |
Refs | |
--- | |
ReadMe.abc2ps (27131B) | |
--- | |
1 | |
2 | |
3 Description of abc2ps (version 1.2) | |
4 =================================== | |
5 | |
6 Program abc2ps reads an input file containing music in abc format | |
7 and typesets it directly in PostScript. It can also be used to list | |
8 the contents of an abc file. | |
9 | |
10 For a description of the abc syntax, please see the abc userguide | |
11 which is a part of the abc2mtex package written by Chris Walshaw. | |
12 | |
13 | |
14 ----- Files ----- | |
15 | |
16 ReadMe.abc2ps this file | |
17 License GNU general public license | |
18 Changes history of changes to the program | |
19 New.Features description of new features in 1.2.5 | |
20 layout.txt information about the music layout | |
21 abc2ps.c main program | |
22 buffer.h routines to control the output buffer | |
23 format.h routines for output formatting | |
24 syms.h routines to define postscript macros | |
25 subs.h general routines | |
26 util.h more general routines | |
27 pssubs.h routines for postscript output | |
28 parse.h routines to parse input lines | |
29 music.h routines to typeset music | |
30 style.h parameters for music layout | |
31 style.pure alternative style file for "puristic" layout | |
32 sample.abc input for demo and test | |
33 <others>.abc sample input files | |
34 | |
35 | |
36 ----- Installation ----- | |
37 | |
38 This is a single C program, consisting of file abc2ps.c and some | |
39 include files *.h. It can be compiled in the usual way to make | |
40 the executable abc2ps: | |
41 | |
42 cc -o abc2ps abc2ps.c | |
43 | |
44 To test the program, unleash it on file sample.abc like this: | |
45 | |
46 ./abc2ps sample -o | |
47 | |
48 The result can be inspected by using a PostScript previewer such as | |
49 ghostview on the output file Out.ps. | |
50 | |
51 | |
52 Possible problems: | |
53 | |
54 By default, the generated PostScript is level 2 since it uses | |
55 the operator "selectfont". If you want level 1 output instead, set | |
56 macro PS_LEVEL to 1 in abc2ps.c. | |
57 | |
58 Sometimes problems arise with the "stat" function. This used at the | |
59 end of the program to determine the size of the output file. | |
60 The call to 'stat' is in routine get_file_size in file subs.h. | |
61 This file also contains an alternative plodding version of | |
62 get_file_size, which can be used if the 'stat' version causes problems. | |
63 Alternatively, just throw out the call to get_file_size in the bottom | |
64 of abc2ps.c and change the printf statement accordingly... printing | |
65 out the file size is only for user information. | |
66 | |
67 | |
68 ----- Program structure ----- | |
69 | |
70 The program defines a number of PostScript macros for drawing | |
71 elementary components like note heads, stems, flags, bars, | |
72 rests etc. These definitions are written to the output | |
73 file Out.ps first. The symbols are mostly defined using Bezier | |
74 curves. At some stage, the macros should probably be changed | |
75 to user paths for more efficiency. | |
76 | |
77 The input lines are read and interpreted one at a time. | |
78 The processing of the info fields is straightforward. | |
79 | |
80 The main work is done for lines of music. Such a line is parsed | |
81 into a list of symbols. To position the symbols horizontally along | |
82 the staff, the program uses a method adapted from the "glue" used | |
83 Donald E. Knuth in the TeX program. The algorithm calculates | |
84 three separate sets of spacings: | |
85 | |
86 "shrink": put the symbols as close together as is acceptable; | |
87 "space": space the symbols "naturally", whereby the space | |
88 behind a note reflects its length; | |
89 "stretch": make a similar but stretched layout which still looks good. | |
90 | |
91 To fill the staff, the spacings are interpolated between the "shrink" | |
92 and "space" cases (if the sum of the natural spacings is larger than | |
93 the staff length) or between the "space" and "stretch" cases (if the | |
94 sum of the natural spacings is too short). | |
95 | |
96 After the positions of all symbols are decided, lines are written to | |
97 Out.ps to invoke the previously defined PostScript macros with | |
98 suitable parameters. | |
99 | |
100 File "layout.txt" gives information on the positioning and how to | |
101 modify the layout. | |
102 | |
103 | |
104 ----- Page breaking ----- | |
105 | |
106 Page breaking: version 1.2 avoids splitting a tune over pages | |
107 as much as possible. For each tune, the program checks whether | |
108 the remaining space on the page is large enough to fit it in. | |
109 If not, a page break is put in before the tune. | |
110 | |
111 To do this, the Postscript output is accumulated in a buffer first. | |
112 For really large tunes, the buffer might overflow. In that case, | |
113 the output is just written out without attempting to place the | |
114 page breaks cleverly. | |
115 | |
116 | |
117 ----- Line breaking ----- | |
118 | |
119 The best output is usually obtained if the staff breaks are | |
120 chosen explicitly by suitable line breaks in the input file. | |
121 In this standard usage, the program tries to set the music as well | |
122 as possible for each line separately. The symbols '*' and '**' at | |
123 the end of a line are ignored, as well as the field 'E:' for | |
124 the elementary length. | |
125 | |
126 However, if a line is too long to fit onto one staff, the overhang | |
127 is spilled onto the next staff in this version. This makes it possible | |
128 to get reasonable output even when the input is one long logical line. | |
129 In practice, this is equivalent to automatic line breaking. | |
130 | |
131 To control line breaking, the following flags are available: | |
132 | |
133 -b break at all line ends, even if they end with the | |
134 continuation symbol '\'. | |
135 | |
136 -c consider the input as one long line, ie., implicitly append | |
137 the continuation symbol '\' to every line of music. | |
138 | |
139 -B n try to typeset with n bars on each line. | |
140 | |
141 -a x set the maximal amount of permitted shrinking to x, | |
142 where x lies between 0 and 1. | |
143 | |
144 If none of these is specified, the standard line-by-line procedure | |
145 is followed, ie: | |
146 | |
147 abc2ps infile -o | |
148 | |
149 For completely automatic line breaking, use the command | |
150 | |
151 abc2ps infile -c -o | |
152 | |
153 This should produce reasonable staff breaks in most cases. However, | |
154 repeat bars, 1st and 2nd endings, and slurs might not be positioned | |
155 very nicely. | |
156 | |
157 When doing automatic line breaking with -c, the user can control the | |
158 spacing of the symbols along the staff by specifying the "compression | |
159 parameter" alfa with the -a flag. A value of 0.0 means that no | |
160 shrinking is allowed, and a value of 1.0 allows shrinking until | |
161 the symbols are almost touching. When -c is used, by default alfa | |
162 is set to an intermediate value (displayed with 'abc2ps -c -h'). | |
163 When -c is not used, maximal shrinking and stretching are allowed. | |
164 | |
165 Thus, to really squeeze everything as much as possible, that is, | |
166 to get automatic line breaking together with maximal shrinking, use | |
167 | |
168 abc2ps infile -c -o -a1 | |
169 | |
170 For more stretched output, use (for example) | |
171 | |
172 abc2ps infile -c -o -a 0.2 | |
173 | |
174 | |
175 The flag "-B n" formats with n bars on each line. This is useful | |
176 e.g. to try various spacings before deciding on how to set the | |
177 linebreaks explicitly in the file. | |
178 | |
179 There is not complete agreement on what output should be generated | |
180 when a staff is underfull, which happens when maximal stretching | |
181 is not sufficient to fill the staff. The behaviour can be determined | |
182 by the following macros in abc2ps.c: | |
183 | |
184 STRETCH_MODE: allowed values are | |
185 0 music for undefull staves is bunched to the left. | |
186 1 music for underfull staves is left-bunched for the last staff onl… | |
187 2 underfull staves are spread over the whole staff. | |
188 | |
189 STRETCH_STAFF: allowed values are | |
190 0 when music is bunched to the left, the staff is also shortened. | |
191 1 staff lines are always drawn all the way across the page. | |
192 | |
193 | |
194 Abc2ps 1.2 tries to take care of slurs and 1st & 2nd endings at the | |
195 line breaks. But in general, a tune will look a substantially better | |
196 when the breaks are chosen by hand. | |
197 | |
198 | |
199 ----- General usage ----- | |
200 | |
201 Basically, the usage is: | |
202 | |
203 abc2ps file1 file2.. | |
204 | |
205 where file1, file2.. are the abc input files. This will list | |
206 the file contents. To generate Postscript output, add flag -o: | |
207 | |
208 abc2ps file1 file2.. -o | |
209 | |
210 Note that most flags (see below) can be used in any sequence. | |
211 Of course, the position does matter for flags e,f,C,S,R,T since | |
212 these determine how the following arguments are interpreted. | |
213 | |
214 Flags can be contracted together if the meaning is clear, | |
215 and a numerical argument for the last flag can be appended. | |
216 That is, '-b -s 0.7 -v 1' can be contracted to '-bs0.7 -v1'. | |
217 | |
218 | |
219 ----- Tune selection ----- | |
220 | |
221 To select specific tunes from the files, use | |
222 | |
223 abc2ps file1 file2.. -e selector1 selector2 ... | |
224 | |
225 where each selector is a set of xref numbers or a pattern. Without -o, | |
226 this will list only the selected tunes found in the files. With -o, | |
227 output is generated only for the selected tunes. | |
228 | |
229 Examples: | |
230 | |
231 To list all the tunes in a file, say book1 or book1.abc (whichever exist… | |
232 abc2ps book1 | |
233 | |
234 To list selected tunes: | |
235 | |
236 abc2ps book1 -e 1-3 5,20- 'House*' Hall | |
237 | |
238 This selects xref numbers 1 to 3, 5, and 20 and above, | |
239 as well as those tunes whose title either starts with "House" or | |
240 contains the string "Hall". A pattern without wildcards such | |
241 as 'Hall' is treated as '*Hall*' | |
242 | |
243 Optionally, the search can be done on other fields using these flags | |
244 in place of -e: | |
245 flag -R seaches the rhythm field | |
246 flag -C searches the composer field | |
247 flag -S searches the source field. | |
248 flag -T seaches the title field (default) | |
249 | |
250 Thus | |
251 abc2ps book1 -C "John" | |
252 | |
253 selects all tunes whose composer string contains "John". | |
254 If the -C flag is used, the composer field is also displayed when | |
255 the file are listed. The same goes for the flags -R and -S. | |
256 | |
257 Flag -A selects all tunes, overriding other selectors. | |
258 | |
259 | |
260 ----- Selection on multiple input files ----- | |
261 | |
262 To filter several files with the same set of selectors, the format is: | |
263 | |
264 abc2ps file1 file2 -e selectors... | |
265 | |
266 To use a different set of selectors for the separate files, | |
267 use a command such as | |
268 | |
269 abc2ps file1 -e 1-3 -f file2 file3 -R Jig | |
270 | |
271 This will select tunes 1-3 from file1 and the tunes with 'Jig' in the | |
272 rhythm field from file2 and file3. More precisely, flag -f indicates | |
273 that the following arguments (up to the next -e flag) are file names. | |
274 Each set of selectors is applied to the files preceeding it. | |
275 As before, the flags -C -S -R can be used in place of -e to change | |
276 the searched field. | |
277 | |
278 For convenience, there are two conventions: | |
279 | |
280 1. An argument with the extension .abc is always assumed to be a | |
281 file name, and is treated as if it were preceeded by the flag -f. | |
282 | |
283 2. An argument which is obviously a set of xref numbers is assumed | |
284 to be a selector, and is treated as if it were preceeded by the | |
285 flag -e. | |
286 | |
287 For example, these three commands all select tunes 1-3 from A.abc | |
288 and tunes 5-7 from B.abc: | |
289 | |
290 abc2ps A.abc -e 1-3 -f B.abc -e 5-7 | |
291 | |
292 abc2ps A.abc -e 1-3 B.abc -e 5-7 | |
293 | |
294 abc2ps A.abc 1-3 B.abc 5-7 | |
295 | |
296 On the other hand, this will NOT work in the expected way: | |
297 | |
298 abc2ps A 1-3 B 5-7 -o | |
299 | |
300 because the program has no way of knowing that B is an input | |
301 file name and not a pattern selector. | |
302 | |
303 For complicated selections on multiple input files, it might be | |
304 better to run the program interactively (see below). | |
305 | |
306 | |
307 ----- Making Postscript output ----- | |
308 | |
309 By adding flag '-o', the selected tunes are typeset and written | |
310 to the output file. To typeset all tunes in file "book1.abc": | |
311 | |
312 abc2ps book1 -o | |
313 | |
314 To typeset selected tunes, use a command such as | |
315 | |
316 abc2ps book1 -e 1-3 5,20- 'House*' Hall -o | |
317 | |
318 The idea is to vary the numbers and/or patterns until the desired | |
319 titles are listed, then add -o to the argument list to make the | |
320 output file. | |
321 | |
322 By default, all selected tunes are written into the same file, | |
323 with suitable page breaks added. By using the flag -E, EPSF output | |
324 is made. Each tune is then put into a separate file with a correct | |
325 bounding box and no page breaks. | |
326 | |
327 Flag -O determines where the output goes. The argument to -O can be | |
328 either a file name or the '=' sign. The latter case tells abc2ps | |
329 to choose the name by itself. | |
330 | |
331 For the PS and EPS modes, the output file names are: | |
332 | |
333 PS mode: | |
334 default Out.ps | |
335 -O NAME NAME.ps | |
336 -O = Output for "foo.abc" is written to "foo.ps" | |
337 | |
338 EPSF: | |
339 default Outnnn.eps, where nnn is a running index | |
340 -O NAME NAMEnnn.eps | |
341 -O = Outfile name is <tune_title>.eps | |
342 | |
343 Note: an output file is overwritten if it already exists. | |
344 This will happen if two tunes have the same name and flag "-O =" | |
345 is used for EPSF output. | |
346 | |
347 | |
348 ----- Modifying the output ----- | |
349 | |
350 These flags change the output appearance: | |
351 | |
352 -x includes the xref numbers in the tune title. | |
353 | |
354 -1 writes every tune on a separate page. | |
355 | |
356 -n includes historical notes and other stuff at the bottom | |
357 of each tune. | |
358 | |
359 -p generates pretty output, with more whitespace between tunes, | |
360 larger fonts for titles, and larger music symbols. By defaul… | |
361 the layout squeezes the tunes to reduce the number of pages. | |
362 | |
363 -s xxx scales the music output by factor xxx. | |
364 | |
365 -w www sets the width of the staff to www points. | |
366 | |
367 -m mmm sets the left margin to mmm points. | |
368 | |
369 -g shrink|space|stretch|fill sets the "glue mode". | |
370 The default mode is fill, which fills the staff. | |
371 This flag is useful when changing the layout parameters, | |
372 to see what effect the changes have for each mode separately. | |
373 | |
374 -B n format with n bars on every staff | |
375 | |
376 -b forces a staff break at the end of each line, even if | |
377 the line has the continuation symbol \ at the end. | |
378 | |
379 -c append the continuation symbol to all music lines, | |
380 which amounts to automatic line breaking. | |
381 | |
382 -a x set the maximal allowed shrinkage to x, where x lies | |
383 between 0.0 and 1.0 | |
384 | |
385 | |
386 ----- On-line help ----- | |
387 | |
388 Flags for on-line help: | |
389 | |
390 -h quick help, equivalent to "abc2ps" without any arguments. | |
391 This also shows the default settings for some parameters. | |
392 | |
393 -v n sets the verbosity for output to the screen to n. | |
394 Hereby -v0 gives very little, -v1,v2,v3.. show successively | |
395 more information. Verbosity >= 10 is for debugging. | |
396 | |
397 -V shows the version number. | |
398 | |
399 | |
400 ----- Interactive mode ----- | |
401 | |
402 If the command list contains the flag -i, abc2ps runs in | |
403 interactive mode. This makes it possible to build up an output | |
404 file piece by piece. The disadvantage is that you have to start | |
405 over if you make a mistake. | |
406 | |
407 Interactive mode is started with | |
408 | |
409 abc2ps -i | |
410 | |
411 The program then prompts for input with the line | |
412 | |
413 select tunes: | |
414 | |
415 The response should be a row of arguments, which are treated | |
416 in exactly the same way as in the non-interactive mode. | |
417 The only difference is that the input is not first run through | |
418 the shell, so that wildcards are not expanded and quotes are | |
419 not removed. Consequently Jig* should be used instead of 'Jig*' etc. | |
420 when specifying strings for selection, and filenames must be written | |
421 out in full. | |
422 | |
423 To exit from interactive mode, enter 'q', 'quit' or an empty input. | |
424 | |
425 For example, a "session" could look like this: | |
426 | |
427 abc2ps -i start abc2ps interactively | |
428 book1 list tunes in book1.abc | |
429 book1 -e 1-10 list tunes with xrefs 1-10 in book1 | |
430 book1 -e 1-10 -o write these to Out.ps | |
431 book2 list tunes in book2.abc | |
432 book2 -e House -o write tunes with 'House' in the title | |
433 quit exit abc2ps | |
434 | |
435 | |
436 To make things easier, there are three special characters: | |
437 ? shows the last input used; | |
438 ! at the start of line is substituted by the last files used; | |
439 * at the start of line is substituted by the last input. | |
440 | |
441 This means that the same effect as above can be obtained in | |
442 shorter form like this: | |
443 | |
444 abc2ps -i start abc2ps interactively | |
445 book1 list tunes | |
446 ! 1-10 equivalent to 'book1 1-10' | |
447 * -o equivalent to 'book1 1-10 -o' | |
448 book2 list tunes in book2.abc | |
449 ! -e House -o equivalent to 'book2 -e House -o' | |
450 q exit abc2ps | |
451 | |
452 Note that the -e flag is not needed in the line '* 1-10' | |
453 because it is clear that '1-10' is a selector (see above). | |
454 | |
455 | |
456 Another point is that if additional flags are used when starting | |
457 interactively, these function as defaults for the interactive mode. | |
458 For example, by starting the program with | |
459 | |
460 abc2ps -io | |
461 | |
462 all selected tunes are immediately written to the output file. | |
463 The program usage is then very similar to that of abc2mtex. Of course, | |
464 it is not possible to list the file contents (to help choose among | |
465 the titles) when using the program in this way. | |
466 | |
467 In interactive mode, flags -O -E can be used as before to redirect | |
468 the output. When switching to another output file, the previous | |
469 file is closed. Switching back to the same file later will overwrite | |
470 the file. | |
471 | |
472 | |
473 ----- Examples ----- | |
474 | |
475 These examples assume that wildcards '*' in the argument list | |
476 are automatically expanded out by the operating system, as | |
477 happens e.g. under the C shell under Unix. If not, the input files | |
478 should be specified explicitly, that is: | |
479 abc2ps x1.abc x2.abc x3.abc instead of abc2ps x*.abc | |
480 | |
481 To list the contents of file 'mytunes.abc': | |
482 | |
483 abc mytunes.abc | |
484 | |
485 To typeset all tunes in 'mytunes.abc': | |
486 | |
487 abc mytunes.abc -o | |
488 | |
489 To typeset all tunes, choosing all line breaks automatically: | |
490 | |
491 abc mytunes.abc -o -c | |
492 | |
493 To do the same, but squeeze notes together more: | |
494 | |
495 abc mytunes.abc -o -c -a0.9 | |
496 | |
497 To list the contents of all abc files in the current directory: | |
498 | |
499 abc2ps *.abc | |
500 | |
501 To search all abc files for tunes containing 'House' in the title: | |
502 | |
503 abc2ps *.abc -e House | |
504 | |
505 To list the contents of all abc files, showing the Rhythm field also: | |
506 | |
507 abc2ps *.abc -R | |
508 | |
509 To search all abc files for tunes with rhythm 'jig' or 'Jig': | |
510 | |
511 abc2ps *.abc -R jig Jig | |
512 | |
513 To do the same while avoiding cases like 'slip jig': | |
514 | |
515 abc2ps *.abc -R 'jig*' 'Jig*' | |
516 | |
517 To output all tunes by composer 'Carolan' in all abc files: | |
518 | |
519 abc2ps *.abc -C Carolan -o | |
520 | |
521 To output tunes 1 to 10 in A.abc and 11-20 in B.abc: | |
522 | |
523 abc2ps A -e 1-10 -f B -e 11-20 -o | |
524 or | |
525 abc2ps A.abc 1-10 B.abc 11-20 -o | |
526 or | |
527 abc2ps A 1-10 B.abc 11-20 -o | |
528 | |
529 To output all tunes with the string 'House' in the title or with | |
530 xref numbers 10-12, in all abc files whose name starts with X, | |
531 including historical notes and xref numbers in the output, | |
532 forcing a line break at continuation lines, with reduced size | |
533 of the symbols, putting one tune per page: | |
534 | |
535 abc2ps X*.abc -e House 10,11,12 -onx -s0.9 -b1 | |
536 | |
537 | |
538 ----- Differences to abc2mtex ------ | |
539 | |
540 Essentially, all features described in the abc2mtex userguide | |
541 should work. The are a few exceptions: | |
542 | |
543 - The slur denotation S was replaced by the syntax (...) | |
544 (see below) | |
545 | |
546 - Key signatures HP and Hp probably aren't treated | |
547 in exactly the right way. | |
548 | |
549 - There is no automatic beam checking. | |
550 | |
551 - There is no way to automatically transpose music in this version. | |
552 | |
553 | |
554 ----- Some extra features --- ----- | |
555 | |
556 For examples, see file sample.abc. | |
557 | |
558 - Codes for decorations: including the ones defined in the | |
559 standard abc syntax, the following decorations are interpreted: | |
560 . dot, staccato | |
561 J slide | |
562 M bar (M='em-phasis') | |
563 H hold sign (fermata) | |
564 ~ gracing | |
565 R roll | |
566 u up-bow | |
567 v down-bow | |
568 | |
569 | |
570 - Escape sequences: embedding a string between two backslashes | |
571 in a music line delimits an escape sequence. In the present versio… | |
572 these are treated as information fields. This makes it easy to | |
573 change key, meter, or default length within a line (see sample.abc… | |
574 | |
575 | |
576 - N-tuplets: abc2ps can handle general n-tuplet cases using the synt… | |
577 | |
578 (p:q:r abcd .. | |
579 | |
580 This means "put p notes into the time of q for the next r notes." | |
581 If q is not given, it defaults as described in the abc2mtex | |
582 user guide. If r is not given, it defaults to p. For example: | |
583 | |
584 (3::2 = (3:2:2 ; (3 = (3:2:3 | |
585 | |
586 The number written over the n-plet is p. This generalized | |
587 syntax is compatible with the older usage. Actually, q is not used | |
588 at all here; it is only relevant for programs which play the music. | |
589 | |
590 | |
591 - Chords: The program accepts the +...+ notation, but it seems more | |
592 intuitive to use some kind of brackets to group together the notes | |
593 which make a chord. This program will accept square brackets: | |
594 | |
595 [ace][adf] | |
596 | |
597 in place of the +..+ syntax. | |
598 The abc notation formally permits notes with different durations | |
599 on the same stem: [a/bc2] and so on. This program assigns all | |
600 notes in a chord the duration of the first note in the bracket. | |
601 | |
602 A chord with two identical notes makes a union (one head | |
603 with stems going both up and down), eg: [AA]. | |
604 | |
605 | |
606 - Slurs and ties: in place of the syntax "SabcSd" for a slur | |
607 over notes abcd, this program uses the notation | |
608 | |
609 (abcd) | |
610 | |
611 for a slur over the notes abcd. It permits cases such as | |
612 | |
613 (ab(cd)) and ((ab)cd) and (a(bc)d) | |
614 | |
615 and similar slurs-below-slurs. To connect three or four notes | |
616 by ties (e.g., for a note held over several bars) use | |
617 | |
618 (a(b)c) or by ties a-b-c | |
619 | |
620 The rule is that any note alone within brackets like (b) | |
621 terminates a previous slur and at the same time starts a new one. | |
622 | |
623 Note that the slur syntax (..) does not interfere with the (3abc | |
624 style for n-tuplets. If a bracket '(' is followed by a digit k, | |
625 it is interpreted as the start of a k-tuplet, otherwise it is the | |
626 start of a slur. For example, a slur is put over the last two | |
627 triplets in this line: (3abc ((3cde) ((3efg). | |
628 | |
629 An unbalanced parenthesis ')' or '(' indicates the continuation | |
630 of a slur on a neighboring line. This is needed (for example) | |
631 in order to make automatic line breaking possible. It will also | |
632 lead to unexpected strange-looking additional slurs if the input | |
633 file contains the wrong syntax (3abc) instead of (3abc for triplet… | |
634 | |
635 | |
636 - Bars: The following symbols denote fat double bars | |
637 at the start or end of a piece (without repeat dots). | |
638 Namely: [| for thick-thin, |] for thin-thick. | |
639 | |
640 For better results when using automatic line breaking, the program | |
641 will split up some types of bars when these are at the end of a li… | |
642 for example: | |
643 :: becomes :| together with |: on the next line | |
644 |: becomes | together with |: on the next line | |
645 :|2 becomes :| together with [2 on the next line etc. | |
646 | |
647 | |
648 - Field E: this field can be used to set some parameters from | |
649 within the file: | |
650 | |
651 shrink set glue mode to compress | |
652 space set to natural glue widths | |
653 stretch stretched glue mode | |
654 fill normal mode to fill staffs | |
655 break ignore continuations | |
656 xref write xref numbers to output | |
657 one write one tune per page. | |
658 newpage start new page for next tune | |
659 lw ppp set local staff width to ppp points. | |
660 | |
661 For example, to output a single tune in a narrower format, | |
662 put 'E:lw 400' into the header of this tune. If this is put | |
663 after the header but within the tune body, only the music is set | |
664 with a different width and the title is written as before. | |
665 | |
666 | |
667 ----- Customization ----- | |
668 | |
669 1. First of all, the horizontal layout of the notes can be changed | |
670 extensively. This is described in 'layout.txt'. | |
671 | |
672 2. Then there are a number of macros in the main program abc2ps.c | |
673 which determine the page layout, ie: | |
674 | |
675 PAGEHEIGHT height of paper | |
676 PAGEWIDTH width of paper | |
677 | |
678 The following block determines the layout in the "pretty" mode (-p). | |
679 The numbers are various font sizes, skips between tunes etc., | |
680 the seperation between staffs, and page margins. A similar | |
681 block (MAINTITLE2 ...) defines the normal, more compact mode. | |
682 | |
683 MAINTITLE1 18 | |
684 SUBTITLE1 15 | |
685 SUBSUBTITLE1 12 | |
686 ASKIP1 0.6 * CM | |
687 BSKIP1 0.6 * CM | |
688 CSKIP1 1.2 * CM | |
689 DSKIP1 0.5 * CM | |
690 TOP_SEP1 25 | |
691 BOT_SEP1 25 | |
692 LSCALE1 0.8 | |
693 LMARGIN1 1.5 * CM | |
694 RMARGIN1 2.0 * CM | |
695 TMARGIN1 2.0 * CM | |
696 BMARGIN1 1.0 * CM | |
697 | |
698 For example, the default staff width is calculated from these | |
699 parameters as PAGEWIDTH-LMARGIN-RMARGIN. The flags -w and -m change | |
700 this width and the left margin, respectively. | |
701 | |
702 | |
703 3. The behavior for underfull lines can be chosen (see "Line breaks"). | |
704 Also consider these two parameters: | |
705 | |
706 ALFA_C default compression when using the -c flag. | |
707 BETA_X maximal expansion allowed before considering a staff | |
708 underfull. | |
709 | |
710 Thus, setting BETA_X to 100.0 lets lines be stretched to any | |
711 arbitrary amount quietly. | |
712 | |
713 | |
714 4. Parameters which influence the musical symbols (all dimensions | |
715 are in pt, relative to a fundamental spacing between staff lines of 6pt): | |
716 | |
717 DECO_IS_ROLL How gracings ~ are interpreted. For 0, draws a trill si… | |
718 For 1, draws a roll sign (cap) over the note. | |
719 LSCALE0 Overall scale factor. The "internal" height for the | |
720 staff is 24 pt, that is, 6 pt between the lines. This | |
721 is rather big, so LSCALE0 scales the size down. | |
722 BASEWIDTH Width of lines within music (bars, stems etc). | |
723 SLURWIDTH Width of Bezier curves when drawing slurs. | |
724 STEM_YOFF Offset of stem from note head center, y direction | |
725 STEM_XOFF Offset of stem from note head center, x direction | |
726 STEM Standard stem length for single notes. | |
727 STEM_MIN Minimal stem length when drawing beams. | |
728 STEM_CH Standard stem length for chords. | |
729 STEM_CH_MIN Minimal stem length for chords under beams. | |
730 BEAM_DEPTH Width of the horizontal stroke for beams. | |
731 BEAM_SHIFT How far the second, third beams are shifted up or down. | |
732 BEAM_FLATFAC Long beams are drawn with slope reduced by this factor. | |
733 BEAM_THRESH If the slope of a beam lies below this threshold, | |
734 it is drawn with slope zero. | |
735 MAX_SLOPE Upper limit for the slope of a beam. | |
736 DOTSHIFT Extra shift, to avoid putting the dot into the flag | |
737 on some notes. | |
738 GSTEM Grace note stem length. | |
739 GSTEM_XOFF Offset of grace note stem to head center. | |
740 GSPACE0 Space between grace note and main note. | |
741 GSPACE Space between grace notes. | |
742 | |
743 | |
744 | |
745 ----- Summary of differences to version 1.1 ----- | |
746 | |
747 - better page breaking | |
748 | |
749 - automatic line breaking possible | |
750 | |
751 - EPSF output possible | |
752 | |
753 - Slurs improved; slurs to previous/next staff allowed. | |
754 | |
755 - New decorations: fermata, bar, up/down bow, roll sign, slide | |
756 | |
757 - unions as [aa] | |
758 | |
759 - thick-thin and thin-thick bars now [| and |] | |
760 | |
761 - normal or pretty output, depending on flag -p | |
762 | |
763 - horizontal beams positioned more cleverly | |
764 | |
765 - n-plets can contain rests, eg. (3zab or (3azb; | |
766 uses brackets if the notes are not all on one beam. | |
767 | |
768 - general n-plet syntax (p:q:r added | |
769 | |
770 | |
771 ---- Feedback ------- | |
772 | |
773 Any suggestions for improvement or bug reports are welcome. | |
774 | |
775 Michael Methfessel ([email protected]), June 1996. | |
776 | |
777 | |
778 |