summaryrefslogtreecommitdiff
path: root/support/pstab/manual.pst
blob: f7ea9085988d4aa2364cb9c76d53bacaa7040447 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
NewDoc Centred
(PStab v2.0
A system for typesetting tablature.
(c) 1994 Brian Ewins.

Contents)
NewStyle Text
(
Introduction
Writing PStab files
The Verbatim Style
The Centred Style
The Verses Style
The ChordPro Style
The Chords Style
The Guitar Tablature Style
The ASCIItab Style
Getting Control of The Layout
Writing Tablature Styles
Writing General Styles
Copyrights & Copylefts
About the Author
)
NewStyle Centred
(Introduction:
or
Zen and the Art of Programming)
NewStyle Text
(
For me, there are some things you must obey when writing \
a program:
*It must be original.
Well, that rules out most shareware stuff.
*It must be backwards compatible.
Hello, Microsoft?
*It must be portable.
*If it needs a manual, it sucks.
Hello, Microsoft (again)?

I have attempted in this program to address all these \
questions. I've certainly never seen anything like this \
program before, and it can make sense of ChordPro, and \
ASCII'd tablature. \
I chose to write it in PS and not in TeX because some \
people out there don't have TeX, and I didn't write it \
in C because some people don't have compilers. However, \
almost everyone has access to a PS printer, and anyone \
can get hold of GhostScript for free to view this stuff. \
In fact, I didn't know PS at all before I wrote this, \
which shows how seriously I took the choice of language. \
As for the manual. Well, this is more of an ideal than \
something you can ever manage to stick to. I did put \
a lot of thought into the syntax for entering tab, chords, \
etc, and hopefully this shows through in ease of use. \
And now, with a tinge of regret, the manual.
)
NewStyle Centred
(Writing PStab files)
NewStyle Text
(
This is the manual for PStab, a program for typesetting tablature. \
PStab is very flexible, and it's not limited to having only one \
guitar, or to using guitar tab instead of, say, bass tab. It can also \
typeset words of songs in a nice way, and is backwards compatible \
with ChordPro, and can even make ASCII tablature look nice for \
printing too. As an example of how flexible this program is: \
since this manual contains many examples of \
PStab's output, it seemed only natural to use PStab to typeset it, \
and PStab was up to the task ! O.K. so TeX it ain't, but if you can \
read this, then you can use PStab --- the program is written in \
PostScript, and so is more portable than most.
),
(PStab is designed somewhat along the line of LaTeX, for those who \
are familiar with that system.That is to say, there is a core system \
for typesetting, on top of which you layer 'styles' which use \
the core functions, to hide the intimate workings of the program \
from the end user. Since the commands that you 'see' depend on which \
style you are using, you should read the sections on each style to \
learn how they work. To make this easy, they all follow pretty much \
the same design.
),
(Firstly, though, I should describe how to write the bare bones of \
a PStab document. Here is a small document:
)
NewStyle
(GetPageMargins
/LeftMargin 1 inch smaller
/RightMargin 1 inch smaller
/TopMargin 1 inch smaller
/BottomMargin 1 inch smaller
0.1 setlinewidth
NewDoc
\(Hello World\)
EndDoc)
NewStyle Text
(
What does this do? GetPageMargins is a command to find out the \
size of page your printer uses. You don't have to tell PStab that \
you've got A4 instead of US Letter, or any other size, it figures \
it out for itself. You must use this command, to give values to \
the margins. The next step was to move the margins in a bit. They're \
only a couple of mm in on my printer, so output would look ugly if \
I left them as they were. If you want to have them some other distance \
than 1 inch in from the page edge, change the 1 to something else. \
PostScript doesn't 'know' inches, or 'smaller', I put those in the \
program to make this easier to understand. 'setlinewidth' is a \
PostScript command to change the width of lines it draws. \
The 0.1 sets it to be 1/720 of an inch. Next, I used NewDoc and \
EndDoc. These set up the program to expect PStab, and clean up \
afterwards. Notice that Hello World is enclosed in brackets.

To print this '.pst' file, you attatch it to the end of the \
program, and send the whole thing to the printer. The end of \
the program in this case would be at the comment saying \
'DOCUMENT SETUP'. However, you are the only person ever \
likely to want to adjust your page margins, so '.pst' documents \
will commonly start with a 'NewDoc' command, and should be \
tagged on to the program after the 'DOCUMENT' comment. If you \
look at this file with an editor, this should all become \
clear, since the manual itself is tagged on in this way.

The example described above \
gets displayed at the top left of a page in the default style, \
which looks like this:
)
NewStyle Verbatim
(Hello World)
NewStyle Text
(
This style, which I use in the manual to indicate what you should \
type, is called Verbatim. It performs simple linebreaking on plain text.\
In fact, all of the text in this manual uses this style, with the font \
changed to make the difference between the text and examples clear. \
How do you change styles then ? Here is an example:
)
NewStyle
(NewStyle Verbatim)
NewStyle Text
(
This cleans up after the last style used, and changes to Verbatim.\
Generally, you replace Verbatim by the name of the style you want to \
use. There are seven styles distributed with this program, but I expect \
others to make up their own for particular documents, just as I did \
to make the text you're reading appear in this font. I will describe \
how to write a style towards the end of this document.

Now I'll go on to describe all of the distributed styles individually.
)
NewStyle Centred
(The Verbatim Style)
NewStyle Text
(
Commands to begin Style:
)
NewStyle
(NewDoc
NewDoc Verbatim
NewStyle
NewStyle Verbatim)
NewStyle Text
(
Any of these commands start up the Verbatim style. \
Note however that you only use the NewDoc command at \
the start of a PStab file: repeated use without an \
accompanying EndDoc will cause an error. The NewStyle \
command cleans up whats left at the end of each section \
of a style, and then starts up in the new one. I have \
put an identical 'commands' section at the start of each \
style decription, the comments in this paragraph apply \
to all of them.

The Verbatim style is the is the default, since it displays \
plain text acceptably. Here is an example of its use:
)
NewStyle
((Hello \\\(),(I break lines wherever I see a comma outside),
(the brackets ( and ), or at a newline
in the input, or),
(I break very very very very very very very very very\\
 very very very very very very very very very very very\\
 very very very very very very very very very very very\\
 very very very very very very very very very very very\\
 very very very very very very very very very very very\\
 long lines up if I have to.),
(the last piece of text has no comma after it.))
NewStyle Text
(
Which displays like this:
)
NewStyle
(Hello \(),(I break lines wherever I see a comma outside),
(the brackets ( and ), or at a newline
in the input, or),
(I break very very very very very very very very very\
 very very very very very very very very very very very\
 very very very very very very very very very very very\
 very very very very very very very very very very very\
 very very very very very very very very very very very\
 long lines up if I have to.),
(the last piece of text has no comma after it.)
NewStyle Text
(
Note the use of backslashes to protect unpaired brackets,\
while paired brackets are OK. Backslashes also prevent automatic \
line breaks at newlines in the input, in the styles which do that. \
The backslash character itself is also has to be protected \
by a backslash. For more about character escapes, as these \
are called, you should read 'The PostScript Language Tutorial \
and CookBook' by Adobe Systems Inc. You shouldn't need to \
know these for normal use of the program.
)
NewStyle Centred
(The Centred Style)
NewStyle Text
(
Commands to begin Style:
)
NewStyle
(NewDoc Centred
NewStyle Centred)
NewStyle Text
(
This is the style which produced the title at the top of this \
page. It's very similar to the Verbatim style. Here is an \
example of its use :
)
NewStyle
((Hello),(I break lines wherever I see a comma outside),
(the brackets ( and ), or at a newline
in the input, or),
(I break very very very very very very very very very\\
 very very very very very very very very very very very\\
 very very very very very very very very very very very\\
 very very very very very very very very very very very\\
 very very very very very very very very very very very\\
 long lines up if I have to.),
(the last piece of text has no comma after it.))
NewStyle Text
(
Which displays like this:
)
NewStyle Centred
(Hello),(I break lines wherever I see a comma outside),
(the brackets ( and ), or at a newline
in the input, or),
(I break very very very very very very very very very\
 very very very very very very very very very very very\
 very very very very very very very very very very very\
 very very very very very very very very very very very\
 very very very very very very very very very very very\
 long lines up if I have to.),
(the last piece of text has no comma after it.)
NewStyle Text
(
I'm kinda pleased with the linebreaking algorithm here, \
it uses up very little in terms of memory. Not that anyone \
out there really cares about this - do you ? 
)
NewStyle Centred
(The Verses Style)
NewStyle Text
(
Commands to begin Style:
)
NewStyle
(NewDoc Verses
NewStyle Verses)
NewStyle Text
(
This style is for printing the verses of songs. It tries to place as \
many verses as it can alongside each other, and if placing the next \
would go across the right margin, it moves down to the next available \
space before printing it. Each verse is contained between a single \
pair of brackets. Here is an example of its use:
)
NewStyle
(I print verses in a row,
The next line gets put down below,
Mumble mumble rhymes with grow
Done this verse, now on we go!),
(I print verses in a row,
The next line gets put down below,
Mumble mumble rhymes with grow
Done this verse, now on we go!
This ones longer than the rest,
To put my linebreaks to the test.
Where's the next line? yes, you've guessed,
I print it in the place that's best!),
(I print verses in a row,
The next line gets put down below,
Mumble mumble rhymes with grow
Done this verse, now on we go!),
(I print verses in a row,
The next line gets put down below,
Mumble mumble rhymes with grow
Done this verse, now on we go!)
NewStyle Text
(
Which generates this:
)
NewStyle Verses
(I print verses in a row,
The next line gets put down below,
Mumble mumble rhymes with grow
Done this verse, now on we go!),
(I print verses in a row,
The next line gets put down below,
Mumble mumble rhymes with grow
Done this verse, now on we go!
This ones longer than the rest,
To put my linebreaks to the test.
Where's the next line? yes, you've guessed,
I print it in the place that's best!),
(I print verses in a row,
The next line gets put down below,
Mumble mumble rhymes with grow
Done this verse, now on we go!),
(I print verses in a row,
The next line gets put down below,
Mumble mumble rhymes with grow
Done this verse, now on we go!)
NewStyle Centred
(The ChordPro Style)
NewStyle Text
(
Commands to begin Style:
)
NewStyle
(NewDoc ChordPro
NewStyle ChordPro)
NewStyle Text
(
This style is meant to reproduce the output of the ChordPro program \
directly from chordpro files. If you're not familiar with that \
program, basically the idea is that you type the text of the \
song with chord names in square brackets at the point where \
you change chord. The program's main function is to place \
these chord names above the text at that position, as you \
would see in many guitar books. Here's an example:
)
NewStyle
(({title:The Manual Song}
{st:No-one has yet claimed responsibility}
[D]I print verses [A7]in a [D]row,
The next line gets put [A7]down be[D]low,
Mumble mumble [A7]rhymes with [D]grow [G][G#][A][Bb][C][D]
Done this verse, now [A7susX]on we [quietly]go!

{c:chorus}

[D]The second verse is [A7]like the [D]first,
The music poor, the [A7]verse is [D]worse,
I wrote this since [A7]I'd get [D]sued,
If I used real songs. [A7]This'll [D]do.
))
NewStyle Text
(
Which generates this:
)
NewStyle ChordPro
({title:The Manual Song}
{st:No-one has yet claimed responsibility}
[D]I print verses [A7]in a [D]row,
The next line gets put [A7]down be[D]low,
Mumble mumble [A7]rhymes with [D]grow [G][G#][A][Bb][C][D]
Done this verse, now [A7susX]on we [quietly]go!

{c:chorus}

[D]The second verse is [A7]like the [D]first,
The music poor, the [A7]verse is [D]worse,
I wrote this since [A7]I'd get [D]sued,
If I used real songs. [A7]This'll [D]do.
)
NewStyle Text
(
Note how the chord placing is done properly, but other \
commands are ignored. Whole ChordPro files can be encapsulated \
this way, and printed without using ChordPro at all. \
PStab does not automatically generate a chord table, as \
ChordPro does, even though I could support this. There are very \
good reasons for not doing so, \
to do with printer memory, but none for reproducing this \
feature, other than laziness on your part, I guess.

The style also spaces out the run of chords \
in the first verse properly, which is there to \
show you how you're supposed to type sharps and \
flats. The line after this shows that you can put \
anything above the text, not just chords.
)
NewStyle Centred
(The Chords Style)
NewStyle Text
(
Commands to begin Style:
)
NewStyle
(NewDoc Chords
NewStyle Chords)
NewStyle Text
(
This style prints chord diagrams. It knows all of the chords that \
ChordPro did, over 130 of them. There were a couple of mistakes in \
the table in that program, which I corrected, but there may be more \
that I haven't spotted that are still wrong. Here's the example:
)
NewStyle
((A#m),(Bbm),(N),(N) [ 5 6 7 5 ], (Asus2) [ -1 [7 3] [7 4] [6 4] 0 0])
NewStyle Text
(
Which displays like this:
)
NewStyle Chords
(A#m),(Bbm),(N),(dunno) [ 5 6 7 5 ], (Asus2) [ -1 [7 3] [7 4] [6 4] 0 0]
NewStyle Text
(
The first two are examples of chords that PStab knows, with \
showing how to type sharps and flats. The third is a name that \
ChordPro doesn't know, which produces a blank, labelled, chord. \
I think this is more useful than not displaying anything. \
The last two are examples of specifying a chord: you just type \
the frets that are to be used, from left to right. Note that they \
don't have to be guitar chords! The program is intended to be \
independent of which instrument you use it for. Notice in the \
final example, I specified which fingers I wanted to hold down \
certain strings with. Finally, the order matters: you must give \
the name of the chord before the fingering, if you give both. 
)
NewStyle Centred
(The Guitar Tablature Style)
NewStyle Text
(
Commands to begin Style:
)
NewStyle
(NewDoc Guitar Tablature
NewStyle Guitar Tablature)
NewStyle Text
(
Go on, admit it, you flicked straight to this page, right? \
This is \(a\) style for setting out tablature. The Tablature \
engine is in fact a general engine capable of printing \
for multiple instruments, adding lyrics, comments, and \
symbols, etc. This page actually describes a substyle I \
wrote as an example. A substyle provides information \
about which lines contain text, and which are frets, \
and also what each of these are called.

This particular substyle -Guitar- describes a line of text called \
'chord', 6 rows of frets called 'e,B,G,D,A,E' in that order, \
and a row of text called 'lyric'. Ok, now for some examples:
)
NewStyle Guitar Tablature
(E 0 D 2 {lyric:see how a note run is typed}, E 3,4,5,6),
(E 0 A 2 D 2 {lyric:here's a picking pattern}, E,A,D,E,D,A),
(E 0 A 2 D 2 {lyric:watch me justify this}, E,A,D,E,D,A),
(E 0 A 2 D 2 {lyric:at 12 point it happened there}, E,A,D,E,D,A),
({lyric:heres some symbols} D {tie},{up},{down},{vib}),
({harm} {lyric:harmonic},\(3\){tie} {lyric:bend},2),
({chord:hammer on} {h},{lyric:pull off} {p}),
({0}{lyric:fingering},{1},{2},{3},{4})
NewStyle Text
(
That was generated from this:
)
NewStyle
((E 0 D 2 {lyric:see how a note run is typed}, E 3,4,5,6),
(E 0 A 2 D 2 {lyric:here's a picking pattern}, E,A,D,E,D,A),
(E 0 A 2 D 2 {lyric:watch me justify this}, E,A,D,E,D,A),
(E 0 A 2 D 2 {lyric:at 12 point it happened there}, E,A,D,E,D,A),
({lyric:heres some symbols} D {tie},{up},{down},{vib}),
({harm} {lyric:harmonic},\(3\){tie} {lyric:bend},2),
({chord:hammer on} {h},{lyric:pull off} {p}),
({0}{lyric:fingering},{1},{2},{3},{4}))
NewStyle Text
(
The main things to notice here, are:
* Bars of tablature are in brackets. The program can \
only break lines at the end of bars. It is actually possible \
to write a system which can optionally break anywhere, but \
it is much more complicated.
* Columns of tablature (notes which are played simultaneously) \
are separated by commas.
* Text rows and tablature rows align separately. This means \
that song lyrics can run under several columns of tab. Unfortunately, \
it also means that a long lyric followed by a column with a chord in \
it will leave a big gap in the tab. I know how to fix this, but it \
makes writing styles less idiot-proof. If I can think of a good way \
of doing it, it may eventually appear in another release. Don't hold \
your breath though, because it would probably involve changing how \
you write styles, and other people will probably have written their \
own by then.
* lyrics, chords, etc are written in the column in which they begin.
* PStab 'remembers' the last thing you played on each string, \
and also the last string you picked. This is to allow easy \
entry of note runs (you don't have to keep saying the string) \
and picking patterns (you don't have to keep sying the notes).
* PStab interprets anything that isn't the name of a string,
or a 'special command' (something in curly brackets) as an object \
to be written on a string - which is why the (3) worked. You
could even write text in the tab this way.
* if a special command does not include a colon, then it's some \
mark to be placed on a string. (the ties, harmonics, etc). Some \
of the marks I use are non-standard, but they are a compromise \
between what I should print, and what can be programmed easily.
* tie marks and slide marks stretch to fill the gap between notes \
if this changes.

If you use this syntax, the main advantages are that PStab \
can align lyrics and chords, and place nice-looking marks \
in the music. However, if you're lazy and have some ASCII'd \
tablature you want to prettify, PStab has ways of dealing with \
that too. This is described in the next section.
)
NewStyle Centred
(The ASCIItab Style)
NewStyle Text
(
Commands to begin Style:
)
NewStyle
(NewDoc ASCIItab
NewStyle ASCIItab)
NewStyle Text
(
I promised I'd do this in this release, and here it is. I have \
provided a way of defining a Tablature substyle which \
uses the ASCIIparser instead if the StdParser (the Guitar substyle \
in the last section used the StdParser). The ASCIIparser takes \
several rows of text and assumes they are all tab - it doesn't care \
how many rows there are, as long as it's been told beforehand. It
then strips out all the minus signs and tries to recognise when objects \
are lined up in columns. This is difficult, espescially to do quickly \
as this program must, and there are a few cases where you can make \
the algorithm do odd things. None of them crash the program, or stop \
it recognising bar lines - it makes bar lines where it sees a column
of pipe symbols ( aka logical OR signs ). In fact, a bit after \
I wrote that piece of code, I found I could easily alter it so \
that it actually split into lines where it thought there was a bar line, \
and consequently would break lines better. This works so well, \
that I can see my own format being redundant (even though it \
does look nicer, people will always prefer to send ASCII tab). \
The ASCIItab style I have written to demostrate this assumes that it's \
looking at guitar tablature-ie 6 rows of text at a time. Heres an \
example which shows off its capabilities, and its weaknesses:
)
NewStyle ASCIItab
(E ||--0-2-|-3---2-0-----0-2-|---------0-------|-----------------|
B ||------|---------4-------|-0---2-4-----3-1-|-0---------------|
G ||@-----|-----------------|-----------------|-----2-0-----0-2-|
D ||@-----|-----------------|-----------------|---------4-------|
A ||------|-----0---2---0---|-----------------|-----0---2---0---|
E ||--3-2-|-0---------------|-3---2---0---2---|-3---------------|),

(|--0--2-|-
|-------|-
|-------|-
|-------|-
|-------|-
|--3--2-|-),
(|---------------0---|
|-4---0---(0)-----0-|
|-------------------|
|-------------------|
|-2-----3--2--0-----|
|---------------4---|),
(|---------------0---|-----------------|-----------------|------------------|
|-4---0---(0)-----0-|-1---3---0---1---|-----------------|------------------|
|-------------------|-------2-------0-|-2---4-----------|------------------|
|-------------------|---2-4-----1-2---|-------4-5---4-2-|-1---2-4-5---4--2-|
|-2-----3--2--0-----|-0---------------|---4-6-------0---|-2---0---2--(2)---|
|---------------4---|---------3-------|-2-------0-------|------------------|),
(|---------------0---|
|-4---0---(0)-----0-|
|-------------------|
|-------------------|
|-2-----3--2--0-----|
|---------------4---|)
NewStyle Text
(
Which was generated from this source:
)
NewStyle
((E ||--0-2-|-3---2-0-----0-2-|---------0-------|-----------------|
B ||------|---------4-------|-0---2-4-----3-1-|-0---------------|
G ||@-----|-----------------|-----------------|-----2-0-----0-2-|
D ||@-----|-----------------|-----------------|---------4-------|
A ||------|-----0---2---0---|-----------------|-----0---2---0---|
E ||--3-2-|-0---------------|-3---2---0---2---|-3---------------|),

(|--0--2-|-
|-------|-
|-------|-
|-------|-
|-------|-
|--3--2-|-),
(|---------------0---|
|-4---0---(0)-----0-|
|-------------------|
|-------------------|
|-2-----3--2--0-----|
|---------------4---|),
(|---------------0---|-----------------|-----------------|------------------|
|-4---0---(0)-----0-|-1---3---0---1---|-----------------|------------------|
|-------------------|-------2-------0-|-2---4-----------|------------------|
|-------------------|---2-4-----1-2---|-------4-5---4-2-|-1---2-4-5---4--2-|
|-2-----3--2--0-----|-0---------------|---4-6-------0---|-2---0---2--(2)---|
|---------------4---|---------3-------|-2-------0-------|------------------|),
(|---------------0---|
|-4---0---(0)-----0-|
|-------------------|
|-------------------|
|-2-----3--2--0-----|
|---------------4---|))
NewStyle Text
(
Note that each set of 6 rows is enclosed by brackets. You must do this. \
It is possible to interpret whole chunks of text and find the tab - \
even to the extent that you wouldn't need to say how many lines to \
expect, and so that it would handle lyrics. \
However, that is beyond the scope of this program. 

Now we play spot the deliberate mistakes. There are 6. Firstly, the \
tuning in the first line wasn't reproduced: the algorithm is to ignore \
everything up to the first column of minus signs, so that bar lines \
don't get displayed. Note that it ignored the 'at' symbols that \
were intended to denote a repeat for precisely the same reason. \
In the next line, there is an unfinished empty bar. The program \
ignores empty bars (part of the algorithm accidentally generates \
lots of these, so this is necessary). Finally, all of the \
bracketed numbers appeared in the wrong place. This is because the \
bracket sticks out over the left edge of the column of things it \
is supposed to align with. The program decides that the object \
with the bracket, and the one without the bracket, are in fact \
in different coulumns, and displays them that way.

All in all, this does a really good job of printing ASCII'd tab, and \
the things that cause the errors can be easily corrected by you. \
I think this ought to be enough to satisfy most people.

Incidentally, parts of this tab were from a piece by Bach, tabbed \
by Michael S. Zraly. Unlike Woodward & Bernstein, I always name \
my sources !
)
NewStyle Centred
(Getting Control of The Layout)
NewStyle Text
(
You don't have to read this. it contains optional info on \
generating page breaks and changing fonts.

How to generate a page break: there is no way for me to safely \
do this, generally, while preserving the current style. Instead, \
I have written a command which basically ends the current document, \
and starts again. As an example of how this works, if we were \
in the Verses style and wanted a page break, we would write:
)
NewStyle
(PageBreak Verses)
NewStyle Text
(
Which generates the required page break, and puts us back into \
the verses style. Of course, you can actually change to any style \
at this point - typically you would say 'PageBreak Centred' instead \
to put a title at the start of the new page.

Changing fonts: there is a command for changing font, called \
'ChooseFont'. For those who know some PostScript: you should use \
this instead of 'setfont', since ChooseFont also tells the program \
the font size for internal use. Here is an example of its use:
)
NewStyle
(/Times-Roman 12 ChooseFont)
NewStyle Text
(
This changes to the font this text is in, in a 12 point size. \
A point is 1/72 of an inch, and most text in books is somewhere \
from 8 to 12 points high. Larger sizes are generally used for \
titles. Note the slash before the name of the font. Obviously, \
this command will only work if your printer actually has the font. \
PostScript printers should come with the following fonts:
Times-Roman,Times-Italic,Times-Bold,Times-BoldItalic,
Helvetica,Helvetica-Oblique,Helvetica-Bold,Helvetica-BoldOblique,
Courier,Courier-Oblique,Courier-Bold,Courier-BoldOblique,
Symbol.

To give you an idea of what these are, this text is Times-Roman, \
the Centred style produced the titles in this document by default \
in Helvetica, and the Verbatim style produces Courier. Symbol is \
not an appropriate font for writing text in. For more on \
fonts, you should really read 'The PostScript Language Reference \
Manual', by Adobe Systems Inc.

WARNING:You can only use this command in certain places, or you will \
confuse the typesetter in the program. A safe place to use it \
is immediately after you set a style. You can also use it in \
the Centred and Verbatim styles outside of brackets. As in LaTeX, \
it is the intention in this program to take your mind off \
changing fonts by using sensible ones for each section of a \
document. Hopefully, you'll heed this and use ChooseFont sparingly, \
but if you don't, your problems are your own. I just described this \
command so that you know what it does. A better way of using this \
information, would be to look for the ChooseFont command in the \
program, in the defnition of each style, and change them there. \
This isn't recommended, but if you have particularly small or \
large paper you may want to scale the output accordingly.

Note that the Chords style, and all of the Tablature styles, \
take account of the font size when drawing diagrams, so they \
are the right size to fit the characters.
)
NewStyle Centred
(Writing Tablature Styles)
NewStyle Text
(
As usual, I'll proceed by example. Here's a style which would work \
for guitar and bass with lyrics:
)
NewStyle
(/GtrBass
{	% a tab style. this must come BEFORE 'Tablature'

	/Times-Roman 8 ChooseFont
	StdParser % usual method of entry.
	/TextHandler
	{% what to do with text.depends how many text objects you have.
		{
			{ (lyric) {pop 11 IsTextRow} }
		} ifcase
	} def
	
	/TabHandler
	{% what you call the rows that contain strings.
		{
			{ (e) {pop 0 IsRow} }
			{ (B) {pop 1 IsRow} }
			{ (G) {pop 2 IsRow} }
			{ (D) {pop 3 IsRow} }
			{ (A) {pop 4 IsRow} }
			{ (E) {pop 5 IsRow} }
			{ (GG) {pop 7 IsRow} }
			{ (DD) {pop 8 IsRow} }
			{ (AA) {pop 9 IsRow} }
			{ (EE) {pop 10 IsRow} }
			{ /default {IsFret}}
		} ifcase
	} def
	%template

	[[()][()][()][()][()][()] () [()][()][()][()] ()]
} def)

NewStyle Text
(
What's going on here ? I defined the tab layout to be: 6 rows of \
text with lines through, 1 row of text, 4 rows of text with lines \
through, and another row of text. I gave the second purely text \
row (row 11) a name, but not the first (row 6). Why ? Row 6 is always \
left blank: so we should not make it possible to use it. \
The program draws bar lines from the top of the staff to the \
bottom ignoring any such gaps, which is what you expect to \
see on a score. The object made purely of square and \
round brackets, if you haven't \
figured it, tells the program if its looking at text or \
a fretting: its as simple as that. This line must come immediately \
before you say 'Tablature' - look at the definitions of ASCIItab \
and Guitar to see other examples. Normally, all of your \
homebrew styles will look like this, adding or removing \
lines from the case statements as necessary. 

This style also defines names for all the strings. I have \
stuck to the same names for each of the guitar strings \
as before, and have added the names 'EE' 'AA' 'DD' and 'GG' \
for the bass strings.

Finally, just to prove that the style I defined works, here \
is a bar of it:
)
NewStyle
	% a tab style. this must come BEFORE 'Tablature'

	/Times-Roman 8 ChooseFont
	StdParser % usual method of entry.
	/TextHandler
	{% what to do with text.depends how many text objects you have.
		{
			{ (lyric) {pop 11 IsTextRow} }
		} ifcase
	} def
	
	/TabHandler
	{% what you call the rows that contain strings.
		{
			{ (e) {pop 0 IsRow} }
			{ (B) {pop 1 IsRow} }
			{ (G) {pop 2 IsRow} }
			{ (D) {pop 3 IsRow} }
			{ (A) {pop 4 IsRow} }
			{ (E) {pop 5 IsRow} }
			{ (GG) {pop 7 IsRow} }
			{ (DD) {pop 8 IsRow} }
			{ (AA) {pop 9 IsRow} }
			{ (EE) {pop 10 IsRow} }
			{ /default {IsFret}}
		} ifcase
	} def
	%template

	[[()][()][()][()][()][()] () [()][()][()][()] ()]
Tablature
( D 1 DD 7 {lyric:An example},A 5 EE 0)
NewStyle Text
(
ASCIItab is different in that it uses a different parser. \
to rewrite this style, you should just be changing the \
number of objects in the template. Look at the definition \
of ASCIItab to see what I mean. The number of these held in the outer \
pair of brackets is just the number of strings used in the tab.
)
NewStyle Centred
(Writing General Styles)
NewStyle
(
This is very hard - it should only be attempted by PS gurus.\
I'll explain here a little of the innards of the program, so\
we can see what functions are essential to a working style.\
The comma or the end of a style (which calls Flush) should\
first cause entry to the Parse command. This usually breaks\
down complex objects into simple objects, and in particular,\
into objects which should not be broken up by line or page\
breaks, such as bars or words. For each of these, you should\
call 'Atom' -and yes, I know you can split Atoms- which\
in turn immediately calls GetAtom. This function should\
set, at the very minimum, hbox and vbox, the horizontal\
and vertical sizes of the object. These should be measured\
in units of fbox, which is the size of the font. You don't\
need to set fbox - that gets done by ChooseFont.

Atom decides, given this information, whether or not to\
split lines, when it calls NewLine, or start a new page,\
when it calls NewPage. Usually, you then call Display,\
which prints the object, but some styles I have supplied\
print out a whole line together, so that Display is\
called by NewLine and by Flush (it must be called by\
Flush or the last line will not appear).

And that's it. To summarize, you must define:

*',' (the comma)
*Flush
*Parse
*GetAtom
*NewLine
*NewPage
*Display

Actually, you can call Display anything you like,\
and not define comma, sice these aren't called by\
core functions, but in the interest of legibility\
by others you should at least consider this.
)
NewStyle Centred
(Copyrights & Copylefts)
NewStyle Text
(
Sorry about this, but it's got to be done.

PStab is Copyright (c) 1994 Brian Ewins.  All rights reserved.

PStab is distributed in the hope that it will be useful, but \
WITHOUT ANY WARRANTY.  No author or distributor accepts responsibility \
to anyone for the consequences of using it or for whether it serves any \
particular purpose or works at all, unless he says so in writing.  Refer \
to the PStab General Public License for full details. 

Everyone is granted permission to copy, modify and redistribute \
PStab, but only under the conditions described in the PStab \
General Public License.  A copy of this license is supposed to have been \
iven to you along with PStab so you can know your rights and \
responsibilities.  It should be in a file named COPYING.  Among other \
things, the copyright notice and this notice must be preserved on all \
copies.

This manual is part of the distribution of PStab, and is covered by \
the same licensing agreement.

ChordPro is (c) 1992 Martin Leclerc and Mario Dorion.

PostScript is a registered trademark of Adobe Systems Incorporated.
)
NewStyle Centred
(About the Author)
NewStyle Text
(
I'm a 25 year old balding, bespectacled student, currently late \
writing up my Ph.D. (on Computational Theoretical Nuclear \
Physics - I kid you not). I've been playing guitar \
since I was about 5 years old, and though I've never been \
great, I can still hack out some Pixies or Tarrega when \
the mood takes me. But it's always annoyed me how difficult \
it was to get hold of tab for songs - I have for instance, \
a copy of a Hendrix music book I got as a present, which \
just shows the tune he sings, along with chords - and what \
use is that? Beginners will probably disagree, but anyone can figure \
out the chords to (most) songs - it easy. So, I was really impressed \
when I discovered the tab I could get over the net. Never \
satisfied, however, I thought it was a waste to print out \
most of it as it stood, because you couldn't make it fit \
the page properly. After a year or so of saying 'I should \
do that' I reached breaking point when the other guy in
my office started writing a Chinese word processor instead
of writing _his_ thesis. As you can tell, not much real \
work gets done round here. So, this is what I wrote, and\
I hope you enjoy it.

I'm releasing this as CardWare - it's actually freeware, \
and there's no legal obligation on you to do this, but \
if you liked it, send me a postcard. Preferably with \
your favourite joke on it. (no need to translate if \
it's not in English). My home adress is:

23 Tantallon Drive
Falkirk FK2 8DJ
Scotland,
U.K.

I'm just curious who uses it, really.

If you really feel it's worth cash, make a donation to \
the charity of your choice. Mine would be a Multiple \
Sclerosis charity.

Comments, and suggestions for a next release, if there \
ever is one, should be sent to:
)
NewStyle
(gapv64@udcf.gla.ac.uk)
NewStyle Text
(
All the best to you and yours,
Baz.
(Brian Ewins) March 14, 1994.
)
EndDoc