forked from tallforasmurf/PPQT
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathpqHelp.html
996 lines (981 loc) · 88.4 KB
/
pqHelp.html
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
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
<!--
__version__ = "1.02.0" # refer to PEP-0008
__author__ = "David Cortesi"
__copyright__ = "Copyright 2011, 2012, 2013 David Cortesi"
__maintainer__ = "?"
__email__ = "[email protected]"
__status__ = "first-html-draft"
__license__ = '''
License (GPL-3.0) :
This file is part of PPQT.
PPQT is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You can find a copy of the GNU General Public License in the file
extras/COPYING.TXT included in the distribution of this program, or see:
<http://www.gnu.org/licenses/>.
'''
-->
<html>
<head>
</head>
<body>
<h1>Introduction</h1>
<p>PPQT is a unified tool for use by the volunteers who post-process books for <a href='pgdp.net'>Distributed Proofreaders</a> (PGDP). It provides a text editor that integrates a number of features useful during post-processing, including display of the book's scanned pages, regular expression find/replace, spellcheck, pagination, footnoting, and html preview. This Help is its main documentation. Some additional info can
be found in the <a href='#Extras'>Extras</a> folder in the PPQT folder.</p>
<p>You can read this help text in the Help panel of the program or simply find the file <tt>pqHelp.html</tt> in the PPQT folder and open it in any browser.</p>
<p>While reading this text in the Help panel, if you click on a link, you can get back to the text by keying ctl-[ or ctl-b (mac users see next paragraph).</p>
<h2>Mac Users Note</h2>
<p> Throughout this Help, when you read <b>ctl-</b>
you think <b>cmd-</b>. And when you read <b>alt-</b>, you think <b>opt-</b>.
Qt is quite consistent in these mappings. However, when you see <b>control-</b>
(not <b>ctl-</b>), that really means, the Control key on every platform.</p>
<p>For example, in this Help panel the "back" function is ctl-b or ctl-[. For a mac, that means cmd-[ or cmd-b. Similarly, it says below that to set bookmark 1, you key ctl-alt-1. As a Mac user you will know to substitute cmd- for ctl- and opt- for alt-, and set bookmark 1 using cmd-opt-1.</p>
<h2>Licenses</h2>
<p>PPQT is based on the <a href="http://qt-project.org">Qt platform</a>.
It is coded in Python using <a href="http://riverbankcomputing.co.uk/software/pyqt/intro">PyQt4</a>.
It is packaged for distribution using <a href="http://pyinstaller.org">pyinstaller</a>.</p>
<p><b>The source code of PPQT is licensed under the GPL v3</b>:
see the file <tt>COPYING.TXT</tt> in the distribution folder. Qt itself is licensed for noncommercial use under the LGPL. PyQt4 is licensed for noncommercial use under the GPL v2 and the GPL v3. The <a href='https://fedorahosted.org/liberation-fonts/'>Liberation font</a> included is licensed under the <a href=http://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=OFLe'>SIL Open Font License</a>.
</p>
<h2>Acknowledgements</h2>
<p>First, a deep bow of respect to Steve Shulz (Thundergnat) who created Guiguts, the program from which PPQT takes its inspiration (and lots of ideas). Second, a genuflection to Mark Summerfield for the book <i>Rapid GUI Development with PyQt</i> that showed how to build PPQT.</p>
<h2>Contents</h2>
<ul>
<li style='font-weight:bold;'><a href='#New'>What's New</a> lists what is different about this version of PPQT!</li>
<li><a href='#Files'>Files and Folders</a> says where PPQT looks for the book text, images, and related files.</li>
<li><a href='#Main'>The Main Window</a> describes that.</li>
<li><a href='#Edit'>The Edit Panel</a> tells about selecting text and the use of many special keys.</li>
<li><a href='#Palettes'>Character Palettes</a> tells how to use these modeless dialogs to enter special characters, and how to make new palettes of your own.</li>
<li><a href='#Scannos'>Scanno Highlighting</a> tells how to make "scannos" visible.</li>
<li><a href='#Spellcheck'>Spellcheck</a> explains the use of good and bad words files and spelling dictionaries.</li>
<li><a href='#Pngs'>The Pngs Panel</a> tells how to display scan images.</li>
<li><a href='#Notes'>The Notes Panel</a> tells how to make notes that are saved with the book metadata.</li>
<li><a href='#Find'>The Find Panel</a> tells about the many Find and Replace facilities.</li>
<li><a href='#Chars'>The Characters Panel</a> tells how to use the character census.</li>
<li><a href='#Words'>The Words Panel</a> tells how to find words, similar words, and misspelt words.</li>
<li><a href='#Pages'>The Pages Panel</a> tells how to set the folios for the HTML etext.</li>
<li><a href='#Flow'>The Reflow Panel</a> tells how to mark up the text for format, including <a href='#Table'>Table markup</a> and <a href='#html'>HTML conversion</a></li>
<li><a href='#View'>The Preview Panel</a> tells how to preview the HTML conversion.</li>
<li><a href='#Foot'>The Footnote Panel</a> tells how to find, number and convert footnotes.</li>
<li><a href='#Extras'>The Extras</a> documents the miscellania in the <tt>extras</tt> folder.</li>
</ul>
<h2 id='New'>What's New in This Version</h2>
<p>(See also <a href='#OldNew'>What Was New</a> for previous changes.)</p>
<h3>What's New as of 11 November 2013</h3>
<p>This version (1.3) includes a bug fix, an interface tweak,
and one major new feature!</p>
<p>Bug fix: From the Words panel you can now add a word with an alternate dictionary tag to the good-words list, for example "spumoni/it_IT".</p>
<p>Interface tweaks: You can now slide the central "splitter" bar as far to the
right as you like to get more edit space. If you shrink the right half of the window below about 550 pixels, a scroll bar appears, because the Flow and Find panels are that wide and can't shrink.</p>
<p>New feature: Character entry palettes! At the bottom of the Edit menu is a submenu "Palettes" with, at the moment, two members, "Greek" and "Symbol".
Choosing one of these opens a "virtual keyboard" with a selection of characters. These modeless dialogs have many features, of which perhaps the best is that you can reconfigure them and create new ones. Read about <a href='#Palettes'>Character Palettes</a> below.</p>
<h2 id='Files'>Files and Folders</h2>
<p>PPQT edits one book text at a time, for example <tt>afinebook.txt</tt>.
If you need to open a second document (for example, a commented copy from Smooth Reading), just start a second copy of PPQT.</p>
<h3 id='Encodings'>File Encodings and Suffixes</h3>
<p>PPQT holds the document in memory in Unicode, which supports virtually any alphabet or special characters. There are two restrictions:</p>
<ul>
<li>PPQT can only display characters that are defined in the font you select
(see <a href='#Edit'>Edit Panel</a> below). The DPCustomMono2 font used by PGDP proofers, for example, lacks Greek and Cyrillic.</li>
<li>Although it can display alphabets such as Arabic if they are in the current font, PPQT does not understand right to left editing. The edit cursor only moves left to right during text entry.</li>
</ul>
<p>The characters in documents on disk are encoded in some way. The important encodings are:</p>
<ul>
<li>ASCII, a set of 95 common characters supported by just about all software and hardware.</li>
<li>UTF-8, which can represent any Unicode character. ASCII is a proper subset of UTF-8, so an ASCII file can be treated as if it were UTF-8 for input.</li>
<li>Latin-1, also called ISO-8859-1, is a set of 191 characters. A file encoded as Latin-1 is not compatible with UTF-8. That is, if you open a Latin-1 file assuming it is UTF-8, or vice-versa, some special characters will be displayed incorrectly.</li>
<li>Windows CP1252 contains the same 191 characters as Latin-1 but adds 27 more
that are not in Latin-1. CP1252 is not supported by Project Gutenberg (PG), but Windows utilities such as Wordpad may save files in that encoding.</li>
<li>Mac Roman defines many, but not all, of the characters in CP1252 (but with different numeric values), and also some special characters not in either CP1252 or Latin-1. Mac Roman is not supported by PG, but Mac utilities such as Textedit may save files in that encoding.</li>
</ul>
<p>PPQT can open files with any of these four encodings. If your book is in some other encoding (for example the Microsoft Windows Greek or Turkish codepages, or UTF-16), you must convert it to UTF-8 first.</p>
<p>In order to load a document without garbling its special characters, PPQT must know which encoding the file uses. It has several ways of finding this out.</p>
<ol>
<li>When saving a file, PPQT writes the encoding into the metadata file (next topic). Thus once you have saved a book it always reopens with the same encoding.</li>
<li>PG requires all etext files to have the file suffix <tt>.txt</tt> regardless of their encoding. However PG permits you to end the filename with <tt>-u</tt>, <tt>-utf</tt>, or <tt>-utf8</tt> to indicate UTF-8 encoding, for example, <tt>afinebook-utf.txt</tt>. PPQT recognizes this and opens such a file as UTF-8.</li>
<li>You can also end a filename with <tt>-l</tt>, <tt>-ltn</tt> or <tt>-ltn1</tt> to signal that it is encoded Latin-1, for example <tt>myfinebook-ltn.txt</tt>.</li>
<li>Per the HTML and XML standards, HTML, XHTML and XML files must either be UTF-8, or else they must have a <tt>charset=</tt><i>encoding</i> parameter in the first 1024 characters of the file. When PPQT loads or saves a file of type <tt>.htm</tt>, <tt>.html</tt> or <tt>.xml</tt>, PPQT looks for this parameter and uses the encoding specified. If there is no parameter, it uses UTF-8.</li>
</li>
</ol>
<p>If none of the above rules applies, PPQT shows a warning dialog giving you the option to open the file in Latin-1, UTF-8, or to cancel.</p>
<p>When saving a file, PPQT will only use UTF-8 or Latin-1. It applies rules 2-4 above to discover which you want to use. To force it to save in a certain encoding, save to a filename with the proper suffix or use the File > Properties dialog.</p>
<p>Before saving to a Latin-1 file, PPQT checks the actual file contents and gives you an error message if there are any characters not supported by the Latin-1 encoding.</p>
<h3>Metadata</h3>
When opening <tt>afinebook.txt</tt>, PPQT looks for a file named <tt>afinebook.txt.meta</tt> in the same location (i.e. the full book name
plus <tt>.meta</tt>). If the meta file
is not found, PPQT assumes this is the first time it has opened this book.
It scans the text gathering information including the location of page separator lines, and counting words and characters.</p>
<p>These items and other useful things (defined bookmarks, your notes, the file encoding, etc.) are saved in the <tt>.meta</tt> file when the file is saved. When the <tt>.meta</tt> file does exist, PPQT loads the metadata items from it.</p>
<p>Also saved in the <tt>.meta</tt> file is a unique code that identifies
the document file. If by evil chance you open a book file that does not
match its meta file (for example, if you restored the book from backup
but not the matching meta file), PPQT will notice this and warn you.
You should quit PPQT and resolve the conflict at once.</p>
<p>Feel free to examine or edit the metadata file, but be aware that it is encoded UTF-8. If strange characters appear, your editor app did not use the utf-encoding to load it. Do not save the metadata file unless you are sure you are loading and saving it in UTF-8 format.</p>
<h3>Page Images</h3>
<p>PPQT expects to find a folder named <tt>pngs</tt> in the same location as
the text file, containing the scan images for the book. These are displayed in
the <a href='#Pngs'>Pngs panel</a>.</p>
<h3 id='GGIO'>Guiguts Import and Export</h3>
<p>PPQT can open a project that has been saved by Guiguts. Just use File > Open and select the book file as saved by Guiguts. PPQT will notice that there is no <i>bookname</i><tt>.meta</tt> but there is a <i>bookname</i><tt>.bin</tt>, the Guiguts metadata file. It will ask for permission and then load the book, taking metadata from the <tt>bin</tt> file and also from <tt>good_words</tt> and <tt>bad_words</tt> files if they exist. Not all of the Guiguts meta-information is preserved, but page numbering and bookmark locations should be correct.</p>
<p>Immediately after loading a Guiguts book, go to the Words or Characters panel and click Refresh. Then go to the Pages panel and click Update. These steps bring the metadata up to date.</p>
<p>Select File > Export to Guiguts to save only the metadata of the current book as a Guiguts <i>bookname</i><tt>.bin</tt> file. Follow this with File > Save to save the actual text <i>bookname</i> (and its <i>bookname</i><tt>.meta</tt>). You can then open the book file in Guiguts and the page numbering should be correct.</p>
<p>It is not expected that anyone would alternate between PPQT and Guiguts as part of normal work. These features are meant for testing and debugging. The conversion between editing systems is not perfect and will not be improved.</p>
<h2 id='Main'>The Main Window</h2>
<p>When launched, PPQT displays a single window divided in two by a vertical bar. The left side is the Edit Panel where you edit the document. The right side
is a tabbed set of panels for different functions. All these panels are described below.</p>
<p>You can adjust the size of the main window and its location on the screen. You can drag the vertical "splitter" left and right to give more or less space to each half. These geometry changes are remembered from session to session.</p>
<p>At the bottom is a status area. On the left side, activity messages appear
from time to time to say what PPQT is doing. Further to the right is a progress bar that shows the status of some long-running operations.</p>
<p>In the center of the status area you see four information fields. On the left is "Image" with the filename of the scan image for the page where the cursor is, when a scan image is known. Next is a line-number field displaying the line number of the edit cursor. Type a new number in that field and press Return to jump to a different line.</p>
<p>Next to the line number field is a field showing the cursor column
position. When no text is selected, this is the column number of the character to the right of the insertion point. When there is a selection, the position number is either the left or the right end of the selected text, depending on how the selection was made (e.g. by dragging left to right, or right to left).</p>
<p>Rightmost is the "Folio" field. It displays the logical page number you have assigned to the current page. Page numbers are set in the <a href='#Pages'>Pages panel</a> described later.</p>
<h2 id='Edit'>The Edit Panel</h2>
<p>The left-side panel is a typical modern plain text line-editor.
It requires a monospaced font, defaulting to Liberation Mono when available
or to Courier New.
Use the View > Font... command to select a font; the choice is remembered from session to session. For PGDP post processing you need a monospaced font that has clear visual separation of similar letters (1/l, O/0, B/8 etc.) and also has a good complement of Unicode characters. PGDP handles books with text in Greek including forms with multiple accents (the Greek Extended set, #1F00), Cyrillic, and Hebrew. Few monospaced fonts have all these but the Liberation Mono font has all the needed features, and has a free license. Courier New, while not as good for proofing, has an even wider repertoire including Arabic forms.
</p>
<h3>Selecting Text</h3>
<p>Select text as usual by dragging,
or by click then shift-click,
or by doubleclick (word) or tripleclick (line).
Extend a selection by holding the shift key when using a cursor movement key
or selecting a bookmark (see below).
PPQT does not support rectangular selections or discontinuous selections.</p>
<p>In addition to the usual copy and paste keystrokes and Edit menu commands, you can move text by dragging the selection, and you can copy text by alt-dragging.
.</p>
<h3>Edit Keys</h3>
<p>The Edit panel supports the following special keystrokes.</p>
<h4>Cursor Movement Keys</h4>
The arrow keys, Home, End, PageUp and PageDown keys work together
with the control key to move the edit cursor
following the usual conventions for your operating system.
Add the shift key to any cursor move to extend the selection by that amount.
For example, ctl-right arrow goes to the end of the line, but shift-ctl-right arrow selects text to the end of the line.</p>
<h4>Editing Keys</h4>
<ul>
<li>ctl-c/ctl-x/ctl-v: copy/cut/paste</li>
<li>ctl-z: undo</li>
<li>ctl-y, also shift-ctl-z: redo</li>
<li>ctl-u, ctl-l, ctl-i: change selection to uppercase, lowercase, titlecase (Unicode-aware)</li>
</ul>
<h4>Find/Replace Keys</h4>
<p>The following keys work in conjunction with the <a href="#Find">Find panel</a>.</p>
<ul>
<li>ctl-f: display the Find panel and put the focus there</li>
<li>shift-ctl-f: copy selection to Find panel and put focus there ("find this")</li>
<li>ctl-g: repeat the last search forward (same as Find Next)</li>
<li>shift-ctl-g: repeat last search backward (same as Find Prior)</li>
<li>ctl-=: replace selection (same as Find panel replace #1)</li>
<li>ctl-t: replace selection and repeat find forward</li>
<li>shift-ctl-t: replace selection and repeat find backward</li>
</ul>
<h4>Miscellaneous Keys</h4>
<ul>
<li>ctl-hyphen: display text 1pt smaller</li>
<li>ctl-+: display text 1pt larger</li>
<li>ctl-alt-1 through ctl-alt-9: set bookmark 1-9 to cursor (bookmarks
are saved in the metadata file)</li>
<li>ctl-1 through ctl-9: jump to bookmark 1-9</li>
<li>ctl-shift-1 through ctl-shift-9: extend selection to bookmark 1-9.
(Note to Mac users: cmd-shift-3 is "capture screen" and cmd-shift-4 is "capture selection". If you want to use these as bookmark 3 or 4 with selection, go to System Preferences, Keyboard, Keyboard shortcuts, click on Screen Shots,
and disable these two keys.</li>
</ul>
<h4 id='ContextMenu'>Context Menu</h4>
<p>Right-click (Mac: <b>control</b>-click) anywhere in the Edit pane to
bring up a context menu with some edit commands. If the current
selection is a single word, this context menu has an item that will
enter that word in the good-words list; see <a href='#Spellcheck'>Spellcheck</a>. This cannot be undone (except by editing the meta file).
<h2 id='Palettes'>Character Palettes</h2>
<p>At the bottom of the Edit menu is a sub-menu named "Palettes" that contains at least one member, "Greek". Choose this to open a modeless dialog (that is, an independent window) that contains a simulated keyboard with Greek characters. Hover the mouse over each key to see the name of its character as a "tool tip". Click on a simulated key to put that character into the text-entry field at the bottom of the dialog.</p>
<p>The Insert button inserts the contents of the text field into the book at its present cursor position. You can choose to enter either the Unicode characters or the corresponding HTML entities such as <tt>&rho;</tt>. The Clear button clears the field and the Copy button copies its contents to the system clipboard so you can paste it elsewhere.</p>
<p>As with other PPQT widgets, you can use control-plus and control-minus to change the size of the font in the entry field.</p>
<h3>Palette and the Real Keyboard</h3>
<p>A palette dialog responds to the real keyboard. Press any key A-Z0-9 and the value of the corresponding key button is entered, as if you had clicked it. You can also press non-alphameric keys to enter spaces or punctuation into the dialog.</p>
<p>If you press the Shift key on the keyboard, the simulated keys in the dialog window show their uppercase values. If you press control (Mac: command) they show different values; if you press Alt (Mac: option) they may show others. Each key can display up to eight different symbols, one for each possible combination of Shift, Control and Alt. For example on the Greek palette, pressing Control brings up characters with the Tonos accent. Pressing Alt brings up characters with the Dialytika, and pressing both displays a few characters that have Tonos and Dialytika.</p>
<p>Pressing Return or Enter inserts the present contents of the palette into the book and clears the entry field. Pressing ctl-Return does the insert and appends a newline, and clears the field. (With ctl-Return you can enter a poem without lifting your hands from the keyboard.) To insert without clearing the field use shift-Return, or click the Insert button.</p>
<h3>Unicode Normalization</h3>
<p>Unicode has the concept of character equivalents. For example, the single character <tt>ñ</tt> could be represented as a letter <tt>n</tt> and a combining tilde <tt>~</tt>, Unicode 303. Although both forms look the same on screen or printed, they don't compare equal in a program. (For details, see the <a href='https://en.wikipedia.org/wiki/Unicode_normalization'>Wikipedia article</a>.)</p>
<p>In <i>normalization</i>, characters are either compressed from multi-character form to single-character form, or the opposite, de-compressed from combined forms to a basic letter followed by "combining diacritical" characters. A character palette supports normalization as follows:</p>
<ul>
<li>When you click Insert or press Return, the dialog performs Normalization (NFKC) to compress the input string to its most condensed form, before inserting it in the book.</li>
<li>When you press the Tab key, the dialog also performs compressing normalization.</li>
<li>When you press Shift-Tab, the dialog performs de-compressing normalization, making all characters into their expanded forms.</li>
</ul>
<p>Whether you compress or decompress makes no visual difference to the text in the input field. If you want to examine the decompressed version of a string, key Shift-Tab to decompress and then click the Copy button. Copy does not do the automatic compressing normalization that Insert does.</p>
<p>When a palette does compression, it also does two other things. It makes a special check for a Greek lowercase sigma at the end of a word, and converts it to a Greek final sigma. Second, it checks to see if the string contains two or more identical "combining diacritical" characters in a row, and if so, it deletes the duplicate ones. This is done because it is quite easy to accidentally type two accents in a row, for example, two "combining acute accent" characters. This has to be an error, but there is little visible sign that it has happened.</p>
<h3>Defining and Modifying Palettes</h3>
<p>The contents of a character palette are completely defined by a simple text file in the "extras" folder. When PPQT starts up, it looks in "extras" for all files that have the suffix <tt>.palette</tt>. It uses each one to make a character palette dialog, and adds it to the Edit > Palettes menu. The name of the file is the name of the palette in the menu.</p>
<p>A palette file is a UTF-8 text file with a simple format. As of November 2013 there are only two palette files, <tt>Greek.palette</tt> and <tt>Symbol.palette</tt>. The Symbol palette is intended as a model. It contains text describing the file format. You are invited to use it as the basis for defining other character palettes, for example Cyrillic, Turkish, or any other character set that can be fitted into 36 key-tops.</p>
<p>The <tt>Greek.palette</tt> file contains some text documenting the decisions on how it is laid out. If you don't like its design, feel free to modify it. You can put any Unicode character on any of the 36 key-buttons in any of the eight shift states. Then restart PPQT and try it out.</p>
<h2 id='Scannos'>Scanno Highlighting</h2>
<p>Use the File > Scannos menu command to load a file of scannos: a text file with one word per line (e.g. <tt>extras/en-common</tt>). (You can use any
of the filename or suffix rules listed <a href='#Encodings'>above</a> to indicate the encoding of the scannos file.)</p>
<p>The path to the scannos file is remembered from session to session and it is re-loaded each time PPQT is restarted, if it can be found.</p>
<p>Use the View > Scannos menu command to turn on scanno highlighting. This puts a lilac background on any word that appears in the scannos file. Be patient when initiating scanno highlighting, it may tie up PPQT for several seconds in a large book.</p>
<h2 id='Spellcheck'>Spellcheck</h2>
<p>When PPQT opens a book for the first time (no <tt>.meta</tt> file exists), it looks in the same folder for a file whose name begins with <tt>good_words</tt>
and loads its contents. It looks for a file whose name begins with <tt>bad_words</tt> also. You can use any
of the filename or suffix rules listed <a href='#Encodings'>above</a> to indicate the encoding of these files.</p>
<p>These lists of "good" and "bad" words are saved in the metadata file thereafter. More "good" words can be added from the <a href='#Words'>Words panel</a> or with the <a href='#ContextMenu'>context menu</a>.</p>
<p>Use View > Dictionary (or File > Properties) to select a dictionary for the main language of the book. This choice of main dictionary is saved with the metadata. Dictionaries for several languages are included with PPQT and more can be added by a procedure documented elsewhere. After changing the main dictionary, click Refresh in the <a href='#Words'>Words panel</a> to re-check all spelling.</p>
<p>When building or refreshing its metadata, PPQT checks all words for spelling. A "bad" word is assumed to be misspelt. A "good" word is assumed to be correct. Any word that is not in those lists is presented to the spell-checker for testing against the current dictionary.</p>
<p>Use the View > Spelling command to turn on red-underlining of misspelt words. Be patient, this may lock up PPQT for several seconds in a large book.</p>
<p>You can mark any word, phrase or section to be checked against an alternate dictionary. Just enclose that word, phrase or section in some kind of HTML markup, <tt>span</tt> or <tt>div</tt> for example, and include the <tt>lang="</tt><i>dict_tag</i><tt>"</tt> property. For example,
<blockquote><tt>He whispered <span lang="fr_FR"><i>Je t'aime</i></span></tt></blockquote>
The <i>dict_tag</i> must be one of the dictionary tags (filenames) displayed by the View > Dictionary dialog. You must remove these HTML tags from the plain text version of the book, but they can remain in the HTML version because <tt>lang=</tt> is a valid HTML and XML attribute.</p>
<h2 id='Pngs'>The Pngs Panel</h2>
<p>Click the Pngs tab to display the Pngs panel, which displays scan images loaded from the <tt>pngs</tt> folder. It normally displays the image that corresponds to the present edit cursor position. The heading line displays the image filename and the corresponding folio, or logical page number. Use the <a href='#Pages'>Pages panel</a> to set the folio values for each page.</p>
<p>When the focus is in the Pngs panel (click in it), ctl-hyphen zooms out and ctl-plus zooms in. The current zoom setting is remembered from session to session. If the image is larger than the panel, scroll bars appear. Use them to center the text. The scroll position is kept as pages change.</p>
<p>At the bottom of the panel is a slider with which you can adjust the zoom from 15% to 250%. Beside it, the button "To Width" causes the display to zoom to fill the width of the panel with the text. "To Height" zooms it to fill the height of the panel with the text. Both of these buttons work by scanning the image pixel by pixel to find the outermost dark spots. Many scan images have random blots and dots in the margins that make PPQT think the text is wider or taller than it looks to your eye.</p>
<p>You can use the PgUp and PgDn keys in the Pngs panel to flip backward and forward through the scan images. However, as soon as you move the text edit cursor, the Pngs panel snaps back to the image corresponding to the cursor.</p>
<h2 id='Notes'>The Notes Panel</h2>
<p>Click the Notes tab. This panel is a simple plain-text editor to hold notes on the book in progress. Whatever contents you type here are saved
in the <tt>.meta</tt> file and reloaded with the book.</p>
<p>When the focus is in the Notes panel, the alt-ctl-m key causes the
current line number of the Edit panel cursor position to be entered, in curly braces: <tt>{1475}</tt>. The alt-ctl-p key causes the current scan image number to be entered in square brackets: <tt>[214]</tt>. Use these keys to relate your notes to locations in the book, for example <blockquote>
<tt>oe lig near {1475} <br />
big table on [214]</tt>.</blockquote>
</p><p>
Place the cursor in or to the right of a {nnn} line number in the notes and key ctl-m. The Edit panel cursor jumps to that line. Place the cursor in or to the right of a [ppp] page number and key ctl-p. The Edit panel cursor jumps to the top of that page's text.</p>
<p>Key ctl-f for a simple Find dialog for searching in the notes.
If text is selected, it is pre-loaded in the find-text field. The search
starts at the cursor and wraps around at the end of the notes.</p>
<h2 id='Find'>The Find Panel</h2>
<p>The Find panel has controls for search and replace, including saved searches.</p>
<p>Searching and Replacing are done within top and bottom boundaries which are initially the beginning and end of the document.</p>
<p>Upon doing any search, keyboard focus returns to the Edit panel.</p>
<h3>Find Controls</h3>
<p>The top row of five checkboxes affect the search.</p>
<table border='1' style='border-collapse:collapse;'>
<tr><td style='width:6em;'>Respect Case</td><td>When checked, search is case-sensitive.</td></tr>
<tr><td>Whole Word</td><td>When checked, normal searches only match whole words.
Does not apply to regex searches (use <tt>\b</tt> in the expression)</td></tr>
<tr><td>In Sel'n</td><td>When checked, search and replace occur within the span of text that is selected when you click the First or Last button.</td></tr>
<tr><td>Regex</td><td>When checked, the Find string is treated as a regular expression.</td></tr>
<tr><td>Greedy</td><td>When checked, a regular expression matches all it can;
otherwise as little as it can.</td></tr>
</table>
<p>The Find text field is below the checkboxes. Here enter the text pattern
to look for. At the left is a popup menu
containing the last 10 find values you explicitly typed in the field.
(These are remembered from session to session.)
The Find text field turns pink when Regex is checked and the syntax is not valid.</p>
<p>Below the text field are four buttons that perform searches:</p>
<table border='1' style='border-collapse:collapse;'>
<tr><td style='width:4em;'>Next</td><td>Search for the Find text beginning at the edit cursor and going toward the bottom boundary. Pressing Return in the Find text field is the same as clicking Next.</td></tr>
<tr><td>Prior</td><td>Search for the Find text beginning at the edit cursor and going back toward the top boundary.</td></tr>
<tr><td>First</td><td>If In Sel'n is checked, set the top and bottom of the
current selection as the search boundaries; otherwise set to the whole document.
Search for the Find text beginning at the top boundary and going forward.</td></tr>
<tr><td>Last</td><td>If In Sel'n is checked, set the top and bottom of the
current selection as the search boundaries; otherwise set to the whole document.
Search for the Find text beginning at the bottom boundary and going backward.</td></tr>
</table>
<p>To simply search forward from the cursor position, press Return while in the Find text field, or click Next. To search backward, click Prior. To search from the top, use First. To search backward from the bottom, use Last. Search does not "wrap around" at the end of the document. When any search succeeds, the focus moves to the Edit panel.</p>
<p>When the focus is in the Edit panel, keying ctl-F makes the Find panel visible and puts the focus in it. Keying shift-ctl-F does the same but also copies the current text selection into the Find text field.</p>
<p>When the focus is in the Edit panel, keying ctl-G is the same as Next and shift-ctl-G is the same as Prior.</p>
<h3>Replace Controls</h3>
<p>There are three Replace fields. They are identical in use. Each is a text field to enter the replacement text. On the left of each field is a popup menu with the last 10 replacement strings you used out of that field.
(These are remembered from session to session.)
On the right of each field is a Repl button that causes the current edit selection to be replaced with the field contents.</p>
<p>Further right are three checkboxes. When &Next is checked, use of any Repl button is followed by the effect of the Next button. When &Prior is checked, use of any Repl button is followed by the effect of the Prior button.</p>
<p>When the focus is in the Edit panel, ctl-= has the effect of clicking Repl on the first replace field; ctl-t is like clicking Repl and then Next; and shift-ctl-t is like clicking Repl and then Prior.</p>
<p>When ALL! is checked, clicking any Repl button causes all instances of the Find text within the search boundaries to be looked up and replaced. The replace-all operation is a single undo/redo step. Before the replacement is done, a message is shown: "Replace <i>nn</i> occurrences of <i>find-text</i> with <i>repl-text</i>?" and you have the option of cancelling the operation.</p>
<p>To replace every occurrence of a string, but only within a portion of the document:</p>
<ul><li>Put the text to find in the Find text field.</li>
<li>Put the replace text in a Replace field.</li>
<li>In the Edit panel, select the span of text where replacements are to happen (for example, drag to select the Table of Contents).</li>
<li>Set the In Sel'n switch on.</li>
<li>Click First (or Last) to establish the boundaries. Also jumps to and selects the first (or last) occurrence of the string.</li>
<li>Optionally, keep clicking Next (or Prior) to step through the span of text and verify all the locations to be changed.</li>
<li>Set the ALL! checkbox on.</li>
<li>Click Repl on the appropriate Replace field.</li>
<li>Note the count of replacements in the dialog and if they look right, click OK.</li>
<li>Inspect the result and if wrong, key ctl-Z (or Edit > Undo).</li>
</ul>
<h3>User-defined Buttons</h3>
<p>Below the Replace controls is an array of 24 pushbuttons.
Here you can store find/replace operations to be used again later.
To store an operation, right-click (Mac users: <b>control</b>-click)
a button. A message pops up asking you to give a short label for the button.
When you do so and click OK, that label is assigned to the button,
and the state of all the find/replace controls—all checkboxes
and entry fields—is stored in that button. Whenever you want to
repeat that operation, click the button. All the find/replace
controls are returned to the stored settings.
The button contents are remembered from session to session.</p>
<p>To clear the contents of a button, right-click it, clear the label field to empty, and click OK.</p>
<p>To save the button settings to a file, select File > Save Find Buttons. Provide the name and location for the saved file. PPQT uses its <a href='#Encodings'>encoding rules 2-5</a> to select between UTF-8 and Latin-1 for this file. A suffix of <tt>.utf</tt> is the simplest way to make sure all special characters are preserved. In the saved file each non-empty button is represented in text form. (Feel free to edit it.)</p>
<p>To load button settings from a file, select File > Load Find Buttons and choose a file of saved buttons. The file's encoding can be indicated by the name or suffix, or will be assumed to be UTF-8. Any valid button definitions in the file are assigned to the buttons. Rather strict controls are applied, but no diagnostics are issued. An invalid button definition is just silently ignored.</p>
<p>
The intent of saving and loading buttons is to be able to save
and re-use complex search operations, and to exchange them with other
users. See the <a href='#Extras'>Extras</a> folder in the PPQT folder for some saved button definitions and a note on the format of a file of saved buttons.</p>
<h3>Regex Syntax</h3>
<p>The Regular Expression (regex) support provided by Qt4 is similar to, but has fewer features than, the Perl regexes used in guiguts. (Qt version 5, planned for 2013, has better support.) The following forms are used to match text.</p>
<table border='1' style='border-collapse:collapse;'>
<tr><td style='width:4em;'>non-special characters</td><td>match themselves</td></tr>
<tr><td><b>\</b><i>c</i></td><td>Escape for special characters: except as documented below, <b>\</b><i>c</i> matches <i>c</i>. Use <b>\\</b> to match a slash.</td></tr>
<tr><td><b>\n</b> </td><td>Matches between lines. <tt>\n\n</tt> matches an empty line.</td></tr>
<tr><td><b>\x</b><i>xxxx</i></td><td>matches Unicode character with hexadecimal value <i>xxxx</i></td></tr>
<tr><td><b>.</b> (dot)</td><td>Matches any one character <i>including newline!</i> </td></tr>
<tr><td><b>\d</b> </td><td> matches a decimal digit (Unicode-aware).</td></tr>
<tr><td><b>\D</b> </td><td> matches a non-digit (Unicode-aware). </td></tr>
<tr><td><b>\s</b></td><td> matches any whitespace character <i>including newline</i> (Unicode-aware).</td></tr>
<tr><td><b>\S</b></td><td> matches a non-whitespace character (Unicode-aware) </td></tr>
<tr><td><b>\w</b></td><td> matches a word character (any Unicode letter, number, or Mark) </td></tr>
<tr><td><b>\W</b></td><td>matches anything <b>\w</b> will not.</td></tr>
<tr><td><b>\</b><i>n</i> </td><td> matches the <i>n</i>-th captured text string (same as perl/guiguts <b>$</b><i>n</i>)</td></tr>
<tr><td><b>[</b><i>chars</i><b>]</b></td><td> matches any one of the <i>chars</i>; may use ranges e.g. <tt>[A-Z1-9]</tt> </td></tr>
<tr><td><b>[^</b><i>chars</i><b>]</td><td> matches any character except <i>chars</i></td></tr>
<tr><td> <b>\b</b></td><td>matches the zero-width boundary between a
word and non-word character. <tt>\bon\b</tt> matches only the word "on".</td></tr>
<tr><td><b>\B</b></td><td> matches what <b>\b</b> doesn't. <tt>\Bon\B</tt> will not match the word "on" but will match inside "tone". </td></tr>
</table><p>Any of the above expressions
can be or'd with stiles: <tt>alpha|beta</tt> means alpha or beta.
Any of those expressions may be put in parentheses to capture
the matching text for use in replacements. Any expression <i>E</i> can be quantified with these suffixes:</p>
<table border='1' style='border-collapse:collapse;'>
<tr><td style='width:5em;'> <i>E</i><b>?</b></td><td> zero or one of <i>E</i> </td></tr>
<tr><td><i>E</i><b>+</b></td><td> one or more of <i>E</i> </td></tr>
<tr><td> <i>E</i><b>*</b> </td><td> zero or more of <i>E</i> </td></tr>
<tr><td> <i>E</i><b>{</b><i>n</i><b>,</b><i>m</i><b>}</b> </td><td>from <i>n</i> to <i>m</i> of <i>E</i>, and <i>n</i> or <i>m</i> can be omitted:
<i>E</i><b>{</b><i>n</i><b>,}</b> at least <i>n</i> of <i>E</i>; <i>E</i><b>{,</b><i>m</i><b>}</b> at most <i>m</i> of <i>E</i></td></tr>
</table>
<p>Non-capturing parentheses force a match but do not capture the matching
text: <tt>(?:The color is)\s(red|green|blue)</tt> can only match a string
that begins "The color is" but the first capture, <b>\1</b>, is what
matched <tt>(red|green|blue)</tt>.</p>
<p>Lookahead tests with <b>(?=</b><i>E</i><b>)</b> and <b>(?!</b><i>E</i><b>)</b> are supported: <tt>Fred(?=\n)</tt>
matches "Fred" only at the end of a line; <tt>Fred(?!\n)</tt> only when
not at end of line. However the lookbehind tests of Perl regexes are not supported.</p>
<p>Note: owing to some tricks PPQT plays with the Qt regex support,
the caret and dollar codes, which usually match at beginning and end
of a line, only match at top and bottom search boundary respectively.
Use <tt>\n</tt> to match at beginning and end of line.</p>
<p>As usual, replacement text for a regex match may contain <b>\</b><i>i</i> to refer to the <i>i</i>th captured (parenthesized) text. However, none of the special replacements supported by guiguts (such as <tt>\U...\E</tt> to uppercase
the text) are available.</p>
<h2 id='Chars'>The Characters Panel</h2>
<p>Click the Char tab to show the Characters panel.
This panel displays a table of all characters seen in the document,
in six columns. Click on the heading of any column to sort the table on that column. The columns are:</p>
<ul>
<li><b>Glyph</b>: The character symbol (if it can be displayed in the current font).</li>
<li><b>Value</b>: The hex value of the Unicode character.</li>
<li><b>Count</b>: The number of times the character appears in the document.</li>
<li><b>Entity</b>: The HTML/XML Entity code for this character.</li>
<li><b>Unicode category</b>: The Unicode category of the character.</li>
<li><b>Unicode Character</b>: The official Unicode character name, for example "Masculine Ordinal Indicator". Long names may be truncated, but if you hover the mouse over that cell, the full name appears as a tool-tip.</li>
</ul>
<p>After you have edited the document, the table is out of date.
Click the Refresh button
to rebuild all metadata and make the counts accurate.</p>
<p>In the upper right is a popup menu with three choices:<p>
<ul>
<li>All: show all characters</li>
<li> ¬ 7-bit: show only characters not in 7-bit ASCII</li>
<li> ¬ Latin-1: show only characters not in the Latin-1 set</li>
</ul>
<p>Use this menu to easily find characters that are not allowed
in a 7-bit file or a Latin-1 file, or to discover if the file needs
to be saved as UTF-8.</p>
<p>If you double-click the character glyph or value, the character
is copied into the Find text field and a First search is done so the first
use of the character is highlighted in the document. Do this to search for the character in the document.</p>
<p>If you double-click on the Entity column, the glyph is copied to
the Find text field while the Entity code is copied to the first
Replace text. This makes it easy to replace a character with its Entity code.</p>
<h2 id='Words'>The Words Panel</h2>
<p>Click the Word tab to see the Words panel.
This is a table of all words in the document, in three columns:</p>
<ul>
<li><b>Word</b>: text of the word</li>
<li><b>Count</b>: the number of times the word appears</li>
<li><b>Features</b>: a string of letters showing information about the word,
for example <tt>Aa---X</tt>. These codes contain, from left to right:
<ul>
<li>A if the word contains an uppercase letter, else hyphen</li>
<li>a if the word contains a lowercase letter, else hyphen</li>
<li>9 if the word contains a digit, else hyphen</li>
<li>h if the word contains a hyphen, else hyphen</li>
<li>p if the word contains an apostrophe, else hyphen</li>
<li>X if the word is in bad_words or fails spellcheck, else hyphen</li>
</ul>
</ul>
Click on any column to sort on that column. Set the Respect Case
checkbox to decide if the Word column sort is case-sensitive.
When the table is large you can quickly locate words beginning with
a particular letter. With the keyboard focus is in the Words panel
and the table sorted ascending on the first column, key the
initial letter you want. The table scrolls to show the first word
beginning with that letter. The jump is case-sensitive when the
Respect Case switch is checked; that is, use shift-E to find words
beginning with uppercase E.</p>
<p>Double-click a word to copy that word into the paste buffer, load the word in the Find text, and do a First search to highlight the first use of the word in the document.</p>
<p>
After the text is edited the table is out of date.
Click Refresh to rebuild all metadata
and make the table current.</p>
<p>Use the popup menu in the upper right
to filter the table to these categories:</p>
<ul>
<li>ALL: show all words</li>
<li>UPPERCASE: show only all-cap words</li>
<li>lowercase: show only lowercase words</li>
<li>mIxEdcase: show words having both upper and lowercase letters</li>
<li>Numbers: show only all-numeric words</li>
<li>Alnumeric: show words having both letters and digits</li>
<li>Hyphenated: show words containing a hyphen</li>
<li>Apostrophes: show words containing an apostrophe</li>
<li>Misspelt: show words that fail <a href='#Spellcheck'>spellcheck</a></li>
</ul>
<p>You can select one or more words by clicking, dragging, shift-clicking or
ctl-clicking in the first column. When a word or words are selected, you can key
<b>shift-</b>ctl-c to copy the selected words for pasting elsewhere.</p>
<p>Right-click (Mac users: <b>control</b>-click) on a word in the first
column to open a context menu with these options:</p>
<ul>
<li>Add to goodwords: Add all selected words to the good-words list
and show them as correctly spelled.</li>
<li>Similar words: Filter the word list to show only words that match the
clicked word when letter case, hyphens, and apostrophes are ignored.</li>
<li>First harmonic: Filter the word list to show only words that are
within one edit of difference from the clicked word.</li>
<li>Second harmonic: Show only words that are within one or two edits
of the clicked word.</li>
</ul>
<p>Use Similar words to find inconsistent use of hyphens. Use
First and Second Harmonic to find likely misspellings of a word. (For example,
use Second Harmonic on the word Footnote to find some improperly-coded
Footnote markups.)
After viewing Similar or First or Second Harmonic, select
All from the popup menu above the table to see all words again.</p>
<h2 id='Pages'>The Pages Panel</h2>
<p>Click the Page tab to display the Pages panel.
The body of this panel is a table showing the information extracted from the page separator lines the first time the file was opened. The information is retained in the metadata even after the text of the page separator lines has been deleted. </p>
<p>The first column, headed Scan#, is the number of the scanned image, usually three or four digits; this
is the filename of the <tt>.png</tt> image file in the <tt>pngs</tt> folder. The table is always in scan image order. Double-click a cell in the Scan# column to make the Edit panel jump to the top of that page's text.</p>
<p>The next three columns are:</p>
<ul>
<li>Format: the display format for a visible folio: arabic or roman numerals.</li>
<li>Action: how to compute and display the folio for this page</li>
<li>Folio: the folio (book page number) for this scanned page</li>
</ul>
<p>The very first time you open a book, the first page of the book is set as Format: Arabic, Action: Set @, and Folio 1. All the other pages are set to Format: (same), Action: Add 1, and consecutive numbers.</p>
<p>
Double-click a cell in the Action column to set the folio action to one of:</p>
<ul>
<li>Add 1: this page's folio is +1 over the preceding page's</li>
<li>Set @: set this page's folio to the number in column 4</li>
<li>Skip folio: show no visible page number for this image</li>
</ul>
<p>Double-click a cell in the Format column to set the format to
one of Arabic, roman (lowercase) or ROMAN (uppercase). Except for the very first page, you can set the format also to "(same)" meaning, same format as the row above. When a book is first opened all rows except the first are set to "(same)". This is a convenience. You can change the format of a whole range of pages by setting the format of just the first one.</p>
<p>Double-click a number in the folio column to set a specific
numeric value to go with the Set @ action.</p>
<p>After making one or more of these changes, click the Update
button to update the table to reflect the changes. Using these
controls you can get the folios of the file to exactly match
the folios in the original book.</p>
<p>The final column of the table is Proofers: a list of the PGDP user-ids who proofed this page at its various stages.</p>
<h3>Inserting Folio Text</h3>
<p>At the top of the panel is a text-entry field and an Insert button.
Use these to insert a text pattern at the start of every page (except
pages for which the Action is Skip folio). The text pattern may contain <tt>\n</tt> to insert a line-break, and it may contain <tt>%f</tt> to insert the
folio number for that page. Insert
any unique pattern that you can extend later with regular expression
replacements, for example <tt>[=%f=]</tt>. The full pattern for
HTML folios in the side margin is:<br /><pre>
<tt><span class='pagenum'><a id='Page_%f' name='Page_%f' href='#Page_%f'>[Pg&nbsp;%f]</a></span>\n</tt>
</pre></p>
<p>Inserting folio text is a single undo/redo operation.</p>
<h2 id='Flow'>The Reflow Panel</h2>
<p>Click the Flow tab to display the Reflow panel.
This panel has controls related to reflowing paragraphs and marked-up
sections in the ASCII etext, and for HTML conversion.
</p>
<h3>Markup Codes</h3>
<p>Use the following codes to mark sections for special treatment in the
reflow of ASCII etext and during HTML conversion. During reflow, normal paragraphs are flowed within a maximum width, usually 72 characters. Other markup sections are supported as follows:</p>
<table border='1' style='border-collapse:collapse;'>
<tr><th>Markup</th><th>Usage</th></tr>
<tr><td><b>/Q..Q/</b></td><td>Block Quote: paragraphs are reflowed
within left and right indents as set in the top row of controls.</td></tr>
<tr><td><b>/U..U/</b></td><td>Unsigned list: text is reflowed by paragraphs,
with the first line of each paragraph indented 2 and other lines indented 4.</td></tr>
<tr><td><b>/P..P/</b></td><td>Poetry:single lines are indented as given
in the second row of controls. Line numbers are pushed to the right margin.</td></tr>
<tr><td><b>/R..R/</b></td><td>Each line is aligned right.</td></tr>
<tr><td><b>/*..*/</b></td><td>No-flow: the entire section may be indented
by an amount specified in the third control, otherwise no change.</td></tr>
<tr><td><b>/C..C/</b></td><td>Centering: single lines are indented so
as to be centered, with at least a 2-space indent.</td></tr>
<tr><td><b>/T..T/</b><br /><b>/TM..T/</b></td>
<td>Table formatting, see discussion below</td>
<tr><td><b>/X..X/</b></td><td>Preformatted section, left entirely alone.</td></tr>
<tr><td><b>/F..F/</b></td><td>Footnote section, left entirely alone.</td></tr>
</table>
<h3>ASCII Reflow</h3>
<p>ASCII reflow involves arranging the text to fit in a maximum width and also
formatting quotes, tables, and other special sections.</p>
<h4>Setting Margins and Indents</h4>
<p>The top row of controls set the default indents for block quotes.
The <i>First</i> indent applies to the first line of a paragraph;
<i>Left</i> to the other lines. The <i>Right</i> indent causes lines to
be shorter than the maximum width by this amount.</p>
<p>The second row of controls set the indents for poetry, in which the <i>First</i> indent applies to every line; the <i>Left</i> indent is used only if a line is too long to fit in the maximum width and is folded.</p>
<p>At the left of the third row is a pair of Text width controls, one for the
optimal (preferred) line length, and a second for the absolute maximum line of text. When reflowing paragraphs most lines will around the optimal length and none will exceed the maximum. Typical settings are 72 and 75. The maximum length is the default width for tables.</p>
<p>For Centered text, setting the "doc" button causes each line to be centered on the text width value. Setting the "self" button adjusts
a centered section as far to the left as possible leaving a 2-space indent.
</p>
<p>You can specify the First, Left and/or Right indent for any markup section
by writing <b>F:</b><i>nn</i> <b>L:</b><i>nn</i> <b>R:</b><i>nn</i> following
the start of the markup. For example <tt>/Q F:8 L:6</tt> starts a
block-quote markup with those margins, overriding the <i>First</i> and <i>Left</i> margins set with the visible controls, but using the <i>Right</i> from the control.</p>
<p>You can write these explicit indent values on Quote, Poetry and List markups. You can also use <b>R:</b><i>nn</i> on Right markup to set a right margin; and <b>L:</b><i>nn</i> on no-reflow (/*) markup to set a left margin.</p>
<h4>Reflowing</h4>
<p>Select a portion of text and click Reflow Now: Selection, or use
Reflow Now: Document to reflow the whole document. Reflow is a single
undo/redo operation: perform it; inspect the result; use ctl-z to undo; adjust the markup and try again. During reflow, the markup codes are retained, and you can apply reflow multiple times without harm.</p>
<p>Before doing reflow you can
set the switches on the left center to skip over special sections. For example set the skip-Tables checkbox so that /T markup is treated the same as /X and left alone.</p>
<p>Normally you reflow after removing <i>, <b>, and <sc> markup.
However you can preview reflow while these are still in place by setting
the controls on the right center. For example if <sc> markup will
be converted to uppercase, set the control to treat this markup as 0 length.
(This does not work for tables at this time. Set the skip button for tables
until you have removed the i/b/sc markup from the text.)</p>
<p>Paragraphs of normal text and paragraphs in block quotes and lists are reflowed within the text margin settings. First, Left and Right margin settings are deducted from both numbers, so if the text widths are set to 72 and 74 (for example), and the Left and Right margins are 4 and 4, the effective margins are optimal 64 and maximum 66.</p>
<p>Paragraph text is reflowed within the effective margins using an optimal algorithm which gives more even line-breaks than the usual "greedy" algorithm.</p>
<h4>Nesting Markups</h4>
<p>To a limited degree you can nest the markups. For example you can nest
a /P poetry section within a /Q block quote section or a /U list section.
You can nest a /R right align section in poetry or a quote to provide a signature or letterhead line. Multiple levels of nesting (/R within /P within /Q) are possible. The First, Left and Right indents for a nested section are taken relative to the indents for its containing section.</p>
<h3 id='Table'>Table Markup</h3>
PPQT treats tables as a special kind of reflow. You mark up the table text with <b>/T...T/</b> and some other parameters. During reflow the table is formatted. If the result is not perfect, undo, adjust the markup, try again.</p>
<p>A table is a series of column values arranged in rows. The column values within each row are separated in one of two ways: by strings of two or more spaces, or with stile (|) characters.</p>
<p>A single-line table has one table row per text line. It is marked up with <b>/T..T/</b> Here is a simple table with two rows and two columns.</p>
<pre>/T
column 1 755.00
another row 2000.00
T/</pre><p>A multi-line table has one or more text lines per logical row,
and the rows are separated by blank lines. The markup starts with <b>/TM</b>.
Here is a multiline table, a typical table of contents:</p>
<pre>/TM
Introduction.--The Present Need xiii
Chapter I. Applied Art 1
Chapter IV. The Nature and
Properties of Clay 29
T/
</pre>
<p>PPQT indents a table two spaces, an etext requirement that prevents an etext reader from reflowing formatted text. It indents more if the table is nested in another markup. By default the table is formatted to fill the maximum paragraph width set in the controls, or narrower when the table is nested in a markup with left and right indents.</p>
<p>By default column text is aligned left, and columns are given widths
roughly in proportion to their contents. However, you can specify detailed controls on the opening markup line.</p>
<p>Specify properties of the whole table with <b>T(</b><i>properties</i><b>)</b> where the <i>properties</i> can be:</p>
<ul><li><b>W:</b><i>nn</i> for the width of the table.</li>
<li><b>S:'|'</b> (a stile in single quotes) to have the right side of the finished table be a column of
stile characters.</li>
<li><b>T:'-'</b> to have the top line of the table be a row of hyphens.</li>
</ul>
<p>For example <tt>/TM T(W:50)</tt> begins a multi-line table with a width of 50. The width specified here can be wider than the text margin, and this is not checked.</p>
<p>Set the default properties for all columns with <b>C(</b><i>properties</i><b>)</b>, where
the <i>properties</i> can be:</p>
<ul><li><b>W:</b><i>nn</i> for the minimum width of every column.
(PPQT will give columns more width than this to fill the table width, or to fit the contents of the widest cell.)</li>
<li><b>A:R/L/C/D</b> to align the cell contents left, right, centered or decimal.</li>
<li><b>B:'-'</b> to have each cell have a line of hyphens under it.</li>
<li><b>S:'|'</b> to have the left side of each column be a column of stiles.</li>
</ul>
<p>You can set the width and alignment properties of a specific column <i>n</i> by writing <i>n</i><b>(</b><i>properties</i><b>)</b>. The properties you can give for a specific column are:</p>
<ul><li><b>W:</b><i>nn</i> for the minimum width of that column.</li>
<li><b>A:R/L/C/D</b> to align the cell contents left, right, centered or decimal.</li>
<li><b>S:' '</b> to have the left side of this column be blank.</li>
</ul>
Here is a fully-specified table before reflow:</p>
<pre>/TM TABLE(TOP:'-' WIDTH:40 SIDE:'|') COL(B:'-' S:'|') 2(A:R W:12)
cell cell now is the time for all
one two good parties to end
row 2 cell @ some more exciting
prose
T/</pre>
<p>and after reflow:</p>
<pre>/TM TABLE(TOP:'-' WIDTH:40 SIDE:'|') COL(B:'-' S:'|') 2(A:R W:12)
----------------------------------------
|cell one | cell two|now is the time|
| | |for all good |
| | |parties to end |
----------------------------------------
|row 2 | @|some more |
|cell | |exciting |
|prose | | |
----------------------------------------
T/</pre>
<p>You can omit the contents of empty cells on the right end of a row. However, you cannot leave blank a cell or cells on any line within a row, or PPQT will assign
text to the wrong column (as in the example above where "prose" fell
from column 3 to column 1 because columns 1 and 2 were blank).
To fill in for a cell that is logically empty,
use a single @ character on every line, as in the above example.</p>
<p>PPQT assigns horizontal space to columns using some brain-dead heuristics.
To get exactly the spacing you want, specify the width of the table and
of each column individually.</p>
<p>As suggested by the example, you can spell out the names of properties,
for example <tt>WIDTH:50</tt> instead of <tt>W:50</tt>. (Actually, only
the initial letter is checked, so <tt>WATERMELON:50</tt> works, too.)</p>
<p>Decimal alignment makes the decimal separators line up vertically in a column. When you specify <tt>A:D</tt> for a column, you can also specify
the width in two parts, for example <tt>W:7.3</tt> where the first number (7)
says the minimum width for the integer part, and the second (3) sets the
minimum width for the decimal and the fraction digits. You may also
specify <tt>D:'<i>x</i>'</tt> to set a different decimal separator character <i>x</i>, for example in a European text where comma is the conventional
decimal "point". Here is a simple table with decimal alignment before reflow:</p>
<pre>
/T TABLE(WIDTH:30) 1(A:R) 2(A:D W:8.4 D:',')
Persimmons € 24,20
Marshmallows € 124,80
T/</pre>
<p>And after:</p>
<pre>
/T TABLE(WIDTH:30) 1(A:R) 2(A:D W:8.4 D:',')
Persimmons € 24,20
Marshmallows € 124,80
T/
</pre>
<p>Sadly, decimal alignment is not supported in HTML, and such cells are aligned left. Also, decimal alignment can produce odd results when applied to cells that contain text, especially in a multi-line table.</p>
<p>Getting a table to flow properly can be tedious. The first time you flow it, it is likely to have many errors, often because there are extra spaces that cause false column breaks, or missing spaces that cause column values to run together. But with work it is usually possible to get a table to look right. Post a sample of a recalcitrant table to the forum and ask for advice.</p>
<p>If the contents of a table start on one page of the book
and end on another page, PPQT will display the scanned images in
the Pngs panel incorrectly. When the cursor is in the table contents,
the first scanned image will be displayed. The image of the second table
page will not appear until the cursor is at the end of the table contents.</p>
<h3 id='html'>HTML Conversion</h3>
<p>ASCII reflow is designed so you can do it repeatedly. HTML conversion
is a one-shot deal that wipes out the reflow markup lines and the spacing
of tables. Select a range of text and click HTML Convert: Selection, or
click Convert: Document to do the whole thing. HTML conversion is a single
undo/redo operation: apply it; check the result in the <a href='#View'>Preview panel</a>; key ctl-z to undo and fix the markup.</p>
<p>Footnotes are converted in a separate step using the <a id='fnhtml'>Footnote Panel</a>.</p>
<p>During conversion the following changes are made
for the different markup types.</p>
<table border='1' style='width:100%;border-collapse:collapse;'>
<tr><th style='width:25%;'>Markup</th><th>Converted to:</th></tr>
<tr><td>text paragraphs</td><td><tt><p></tt><i>para text</i><tt></p></tt></td></tr>
<tr><td><b>/Q</b></td><td><tt><div class="blockquote"></tt></tr>
<tr><td>text in /Q..Q/</td><td><tt><p></tt><i>para text</i><tt></p></tt></td></tr>
<tr><td><b>Q/</b></td><td><tt></div></tt></tr>
<tr><td><b>/U</b></td><td><tt><ul></tt></tr>
<tr><td>text in /U..U/</td><td><tt><li></tt><i>para text</i><tt></li></tt></td></tr>
<tr><td><b>U/</b></td><td><tt></ul></tt></tr>
<tr><td><b>/R</b></td><td><tt><div class="ralign"></tt></tr>
<tr><td>text in /R..R/</td><td><tt><p></tt><i>each line of text</i><tt></p></tt></td></tr>
<tr><td><b>R/</b></td><td><tt></div></tt></tr>
<tr><td><b>/P</b></td><td><tt><div class="poetry"><div class="stanza"></tt></td></tr>
<tr><td>blank lines in /P..P/</td><td><tt></div><div class="stanza"></tt></td></tr>
<tr><td>text lines in /P..P/</td><td><tt><span class="i<i>nn</i>"></tt><i>text of line</i><tt></span><br /></tt></td></tr>
<tr><td>poem line #s</td><td><tt><span class='linenum'></tt><i>nbr</i><tt></span></tt></td></tr>
<tr><td><b>P/</b></td><td><tt></div></div></tt></td></tr>
<tr><td><b>/F</b></td><td><tt></div class='footnotes'></tt></td></tr>
<tr><td>text lines in /F..F/</td><td>not touched</td></tr>
<tr><td><b>F/</b></td><td><tt></div></tt></tr>
<tr><td><b>/X</b>, <b>/C</b>, <b>/*</b></td><td><tt><pre></tt></td></tr>
<tr><td>text in these</td><td>not touched</td></tr>
<tr><td><b>X/</b>, <b>C/</b>, <b>*/</b></td><td><tt></pre></tt></td></tr>
<tr><td><b>/T</b>, <b>/TM</b></td><td><tt><table></tt> or <tt><table style="width:<i>pp</i>%;"></tt> where <i>pp</i> is based on the indents and the specified table width.</tt></td></tr>
<tr><td><b>T/</b></td><td><tt></table></tt></td>
</table>
<p>Within a table, the cell values are enclosed appropriately in <tt><tr></tt> and <tt><td></tt> codes. Where a specific width was given for a column, the first row of that column is coded <tt><td style="width:<i>pp</i>%;"></tt> where
<i>pp</i> is based on the specified width divided by the table width.
When a column has right alignment or center alignment, every cell in it is
coded with <tt>class="r"</tt> or <tt>class="c"</tt> respectively.
This assumes CSS of<pre>td.r {text-align:right}
td.c {text-align:center}</pre>
<p>Decimal alignment in a table could be coded in HTML as
<tt><td char='<i>x</i>'></tt> on each cell of a decimal column, but
this element of the HTML 4.0 standard is not supported by any browsers, so Decimal-aligned columns just default to left-alignment. Too bad.</p>
<h3>Chapter and Subhead Markup</h3>
<p>PPQT marks a Chapter Title with <tt><h2></tt>. It detects a Chapter Title as a paragraph of one or more lines, preceded by exactly 4 empty lines.</p>
<p>PPQT marks a Subhead with <tt><h3></tt>. It detects a Subhead as a paragraph of one or more lines preceded by exactly 2 empty lines, and not following a Chapter Title.</p>
<p>These rules are subtly different from those given in the PGDP Formatting Guidelines, which are ambiguous about whether or how a Subhead might follow a Chapter head. With PPQT, the paragraph following a Chapter Title will <i>always</i> be converted to a normal <tt><p></tt> paragraph. If you must have a Subhead immediately following a Chapter Title you have to edit the HTML manually after conversion. (<i>n.b.</i> Guiguts applies the same rule for Chapter Titles, but Guiguts <i>never</i> marks up Subheads, leaving that entirely to the user.)</p>
<h2 id='View'>The Preview Panel</h2>
<p>Click the Pvw tab to display the HTML Preview panel. Whenever
you click either Refresh button on this panel, the complete contents of the
Edit document are copied into this panel and displayed as HTML.</p>
<p>The default font is set to Palatino and the initial text font size is set to 16 points. When the focus is in the Preview panel, you can key ctl-minus and ctl-plus to zoom the display.
Each time you use a zoom key, the text and images increase or
decrease by 1/16th.</p>
<p>
The HTML rendering is done by the open-source <a href='http://www.webkit.org'>WebKit engine</a>, the same HTML rendering code that is used by Apple's Safari and by KDE. It fully supports CSS and
standard HTML code. Java and Javascript are disabled in the Preview panel, however.</p>
<p>The base URL for image references is the base path of the book text file,
so the <tt>images</tt> folder should be located at the same place as the book text.</p>
<p>If you click a link in the preview (for example, to open a high-resolution image)
the browser follows the link and displays the linked page or image.
To return to the book preview, key ctl-B or ctl-[ (control-left bracket).</p>
<p>The Refresh button only refreshes the HTML. When you click Refresh + Clear,
the browser's memory cache is cleared and any images are reloaded from disk.
Use this button if you make changes in the images.</p>
<p>Key ctl-F in the Preview panel to open a simple Find dialog. Key ctl-G to search again for the found text.</p>
<h2 id='Foot'>The Footnote Panel</h2>
<p>Click the Fnote tab to display the Footnote management panel.</p>
<h3>Definitions</h3>
<p>The following terms are important. A <i>Note</i> is a section of text that begins with <tt>[Footnote</tt> and ends with a right-bracket, for example,</p>
<pre>[Footnote <b>z</b>: ... some text possibly mutiple lines,
ending with -- ]</pre>
<p>A Note is only recognized when <tt>[Footnote</tt> begins in column zero, and the final right-bracket is the last character on its line. (Additional square brackets within a Note are not a problem so long as they don't come at the end of a line.) A Note may contain other types of markup, for example quotes, poems or tables.</p>
<p>An <i>Anchor</i> is a reference to a Note enclosed in brackets thus<tt>[<b>z</b>]</tt>. Anchors may appear in tables, quotes, and poetry as well as normal text.
<p>A Note should not be coded inside /Q or /T or any other markup section that gets indented, because after reflow the <tt>[Footnote</tt> will no longer be at the left margin, and the note will not be recognized. If an Anchor appears in some markup section, place its matching Note after the end of the markup.</p>
A Note may contain an Anchor to another Note (that is, a footnote has a footnote—yes, it really happens). However, Notes cannot be nested. The referenced Note to the Note must be outside the referring Note, perhaps immediately after it.</p>
<p>A <i>Key</i> is that letter or number or symbol that links an Anchor to its Note, <tt><b>z</b></tt> in these examples. We connect an Anchor to its Note by matching the Keys.</p>
<p>A key falls into one of several <i>Classes</i>:</p>
<ul>
<li>The letters <tt>IVXLCD</tt> are in the Upper Roman class</li>
<li>The letters <tt>ABCDEFGHIJKLMNOPQRSTUVWXYZ</tt> are Upper Alpha Class</li>
<li>The letters <tt>ivxlcd</tt> are Lower Roman class</li>
<li>The letters <tt>abcdefghijklmnopqrstuvwxyz</tt> are Lower Alpha Class</li>
<li>The digits <tt>0123456789</tt> are Decimal Class</li>
<li>The six symbols <tt>*¤§¶†‡</tt> (asterisk, currency, section, paragraph, dagger and double-dagger) are Symbol Class</li>
</ul>
<p>Only the Latin alphabet, digits, and the symbols shown are recognized as Key values. (Most PGDP books are proofed using only the letters A, B and occasionally C; some scholarly books might have lowercase roman keys or decimal keys as well.)</p>
<p>The alphabetic classes are ambiguous; that is, a Key that is a letter might be either an alpha or a roman, depending on how you want your book to work. This is resolved when renumbering, see below.</p>
<p>PG texts sometimes contain <tt>[oe]</tt> or <tt>[OE]</tt> to stand for the Œ ligature. This is ambiguous; <tt>[OE]</tt> might be an Anchor to the 395th note in an alphabetic series. (26*15+5—it could happen in a large book!). PPQT does not recognize <tt>[oe]</tt> or <tt>[OE]</tt> as Anchors. When renumbering, it will not generate either one as a renumbered key.</p>
<h3>The Footnote Table</h3>
<p>When you click the Refresh button at the top of the panel, PPQT scans the document for Anchors and Notes. It matches the anchors and notes and displays the result in the table. The columns of the table are:</p>
<ul>
<li><b>Key</b>: the letters or numbers of the key.</li>
<li><b>Class</b>: the Key Class that PPQT has assigned based on the Key.</li>
<li><b>Ref Line</b>: the line number where the Anchor was seen.</li>
<li><b>Note Line</b>: the first line number of the Note.</li>
<li><b>Length</b>: the number of lines in the Note.</li>
<li><b>Text</b>: the first few characters of the Note text.</li>
</ul>
<p>When PPQT finds an Anchor but cannot match it to a Note, the Note Line column has a question mark. When it found a Note but no Anchor refers to it, the Ref Line column has a question mark. In these unmatched cases, the row of the table is pink to show there is a problem. You must resolve these problems before the action buttons at the bottom of the panel will work.</p>
<p>When a Note has more than 10 text lines, or an Anchor is more than 50 lines from its Note, the table row is pale green to suggest a possible problem. You should check these cases to make sure PPQT has recognized the Note properly and matched it to the correct Anchor.</p>
<p>When you click on a Ref Line cell, the document jumps to the line with that Anchor, with the Key selected. Click on a Note Line cell; the document jumps to that Note with the Note selected. Click repeatedly on a Key cell and the document jumps back and forth between the Anchor and the Note.</p>
<h3>Renumbering</h3>
<p>When you click the Renumber button, provided there are no pink lines in the table, PPQT sweeps through all the Keys in the document and renumbers them sequentially according to their Class. PPQT has five counters that are set to 1 when you click Renumber. Each time a counter is used it is increased by 1. The number streams are:</p>
<ul>
<li><b>1,2,..999</b> produces a series of decimal numbers.</li>
<li><b>A,B,..ZZ</b> produces a series of uppercase letters.</li>
<li><b>a,b,..zz</b> produces a series of lowercase letters.</li>
<li><b>I,II,..M</b> produces a series of uppercase Roman numerals.</li>
<li><b>i,ii,..m</b> produces a series of lowercase Roman numerals.</li>
</ul>
<p>Below the table are six popup menus that let you specify how the Keys of each Class are to be renumbered. During the renumbering sweep, PPQT looks at each Key in sequence and decides its Class. Then it replaces that key with the next value from the number stream you have assigned to that Class.</p>
<p>If the book has only uppercase alpha keys (the usual situation) then set Classes ABC and IVX both to use the A,B..ZZ stream. Each Key will be replaced with the next alphabetic value in sequence, from <tt>A</tt> through <tt>ZZZ</tt>. However, if the book has a separate set of lowercase Roman keys, set that Class to use the i,ii,..m stream.</p>
<p>If the uppercase or lowercase alphabetic stream generates an <tt>[oe]</tt> or <tt>[OE]</tt> key, PPQT skips over it, so the sequence of renumbered alphabetic Keys runs from <tt>[od]</tt> to <tt>[of]</tt>.
<p>You can use renumbering to change the Class of keys in use. If the book has only uppercase alpha, you could set that Class to use the 1,2,..999 stream. After renumbering, those keys will all be Decimals.</p>
<p>Renumbering is a single-undo operation. After renumbering, examine the results; if they are not satisfactory, click in the text and key ctl-z.</p>
<h3>Footnote Sections and Moving Footnotes</h3>
<p>Proofers leave Notes on the page where they appear. You move them to follow the paragraph that references them. However for some books you want to move all Notes to a special section at the end of each chapter, or at the end of the book.</p>
<p>To do this, you must edit the book to show where the footnotes are to go using the markup codes <tt>/F</tt> and <tt>F/</tt>. For example, a section of notes at the end of a chapter might be coded:</p>
<pre>...last line of chapter text.
NOTES
/F
F/</pre><p>Here, <tt>NOTES</tt> represents a subhead (because it is preceded and followed by two blank lines). The text "NOTES" does not matter; it is the <tt>/F..F/</tt> markup codes that tell where the Notes from the preceding chapter should be moved. Alternatively you might have a single chapter of notes at the end of the book text.</p>
<p>When you click the Move Notes button, PPQT scans the document and locates all the <tt>/F..F/</tt> sections you have coded. (If it cannot find any, it displays an error.) Then it goes through the footnote table and finds any Notes that are not already enclosed in a <tt>/F..F/</tt> section. It moves these into the Footnote section next below them in the document. (If there is no section below a Note, it is not moved.)</p>
<p>Moving notes is a single-undo operation. Inspect the result and use ctl-z if it is not satisfactory.</p>
<h3>ASCII Conversion</h3>
<p>Click ASCII Cvt in the Footnote Panel to convert all Notes to block-quote /Q..Q/ markup. Each note is changed from:<pre>
[Footnote key: Text of the note... ]</pre> into:<pre>/Q Fnote <i>xxx</i>
[key] Text of the note...
Q/</pre>The code <i>xxx</i> shows the class of the key: <tt>ABC</tt>,
<tt>123</tt>, <tt>ivx</tt> etc.
These /Q..Q/ sections can be reflowed in the <a href='#Flow'>Reflow Panel</a> ASCII reflow.
The <tt>Fnote</tt> <i>xxx</i> text is ignored by reflow.
You can use it with Find to step through the converted Notes,
or you could replace it with explicit First, Left and Right margins.
</p>
<p>Do this as the very last footnote operation in the plain text fork of the book. Afterward, the Footnote Panel is of no use because the Notes can no
longer be recognized.</p>
<h3 id='fnhtml'>HTML Conversion</h3>
<p>HTML conversion of footnotes is divided between the Footnote Panel and the Reflow Panel.</p>
<p>In the Footnote panel click HTML Cvt to convert all Anchors and Notes to HTML. This is a single-undo operation. Do this as the very last footnote operation in the HTML fork of the book. Afterward, the Footnote Panel is of no use, because the Notes can no longer be recognized.</p>
<p>This does not convert the the markup tags <tt>/F..F/</tt>. Later, when you use HTML Convert in the <a href='#html'>Reflow Panel</a>, it converts those tags to <tt><div></tt> markup.</p>
<h2 id='Extras'>The Extras Folder</h2>
<p>
Within the distribution folder <tt>PPQT</tt> there is a folder named <tt>extras</tt> with some miscellaneous documents:</p>
<li><tt>en-common.txt</tt> is the file of common English scannos, pretty much the same as that distributed with Guiguts.</li>
<li><tt>suggested-workflow.rtf</tt> describes the steps of post-proofing with PPQT in a logical sequence.</li>
<li><tt>empty-buttons.utf</tt> is a Find Buttons file that will clear all 24 buttons to <tt>(empty)</tt> status. Use it before setting up your own buttons to save, so as to avoid saving superfluous definitions.</li>
<li><tt>unbalancedRE.utf</tt> loads a set of Find buttons to look for unbalanced markup.</li>
<li><tt>fixupRE.utf</tt> loads a set of Find buttons to look for common formatting errors, modelled after Guiguts Fixup.</li>
<li><tt>find-psep.utf</tt> loads a set of Find buttons to find and delete page separators.</li>
<li><tt>clearTextMarkups.utf</tt> loads a set of Find buttons to find and delete block markup.</li>
<li><tt>htmlFixes.utf</tt> loads Find buttons to convert small-cap text,
superscripts, subscripts, Side notes, Illustrations, and typo markups to HTML.</li>
<li><tt>syntax-of-find-button-files.txt</tt> has sketchy documentation of the format of a Find button file.</li>
<li><tt>header.html</tt> contains the opening of an HTML etext including the <tt><!DOCTYPE></tt> and<tt><head></tt> statements and the full CSS style section described in the PGDP Wiki under "CSS Cookbook" (but with some classnames modified to match what PPQT generates).</li>
</ul>
<h2 id='OldNew'>What Was New</h2>
<h3>What's New as of 18 September 2013</h3>
<ul>
<li>There is now a File > Properties dialog that gives access to a few important facts about the current document. This may be expanded in the future.</li>
<li>The status bar now shows Image (scan file) number and Folio (logical page number). You can jump to a page by entering its number in the Image field.</li>
<li>The <a href='#Pages'>Pages panel</a> now initializes any sequence of pages that have the same folio format with "(same)". This makes it easier to change formats; you only have to set an explicit format on the pages where the format changes.</li>
<li>When you save a file that should be encoded Latin-1, PPQT checks the file contents, and if it contains a non-Latin-1 character, it warns you and you must either save in UTF, or cancel the save.</li>
<li>When you select a file to open, and PPQT can't determine its character encoding, you get a warning dialog. You can specify Latin-1 or UTF encoding, or cancel.</li>
<li>You now specify an alternate spelling dictionary with syntax that is valid HTML, replacing the nonstandard syntax previously used. See <a href='#Spellcheck'>Spellcheck</a>.</li>
<li>The keystrokes for inserting and jumping to line numbers in the Notes tab have been changed from alt-ctl-L and ctl-L to alt-ctl-m and ctl-m, to avoid conflict with the Edit menu where ctl-L means change selection to lowercase.</li>
<li>Annnnnddd... it's version 1.2. The accumulated tweaks and fixes add up to enough to call this a new version. Also this is likely the last version before version 2.0.</li>
</ul>
<h3>What's New on 19 August 2013</h3>
<ul>
<li>The <a href='#Chars'>Characters Panel</a> now displays a new column, Unicode Character Name. This can help you tell the difference between some characters that are hard to distinguish by their shapes.</li>
<li>You can launch PPQT from the command line (linux or Mac OS) without having to invoke Python, e.g. just enter <tt>ppqt</tt>. If you enter <tt>ppqt --version</tt> it prints the version info and exits.</li>
<li>If you launch PPQT from the command line you can specify a book to open, for example <tt>ppqt abook-utf.txt</tt>. If the book is not in the current directory you must give an absolute or relative path to it.</li>
<li>Support for loading Guiguts projects and saving to Guiguts format is added; see <a href='#GGIO'>Guiguts Import and Export</a>.</li>
<li>Support for setting the file encoding based on file suffixes <tt>.win</tt> and <tt>.mac</tt> has been removed. You can still open files with these encodings using File > Open With Encoding.</li>
<li>If the book is opened with Latin-1 encoding, you are warned before saving if the book now has characters that are not valid for Latin-1. The warning might not appear if the count of characters is not up to data (Refresh in the <a href='#Chars'>Characters panel</a>).</li>
</ul>
<h3>What's new as of 10 July 2013</h3>
<p>When converting to HTML, we now apply a new, simplified rule to detect chapter heads and subheads. The new rule is subtly different from the wording of the PGDP Formatting Guidelines. See <a href='#html'>HTML Conversion</a> for details.</p>
<p>When converting Footnotes to HTML, we no longer include a <tt>name=</tt> property in the anchor or the footnote <tt><div></tt>. The <tt>name</tt> property is not supported in XHTML Strict and prevented the document from validating.</p>
<h3>What's New as of 30 April 2013</h3>
<p>Several small but annoying bugs have been fixed:</p>
<ul>
<li>The HTML conversion had basic logic errors in the way it detected chapter heads and subheads.</li>
<li>Another bug could crash HTML conversion in very rare circumstances.</li>
<li>A bug that caused bad output in HTML conversion of a multi-line table when the table started with a blank line.</li>
<li>The png image for the current page is displayed as soon as a book is opened, rather than waiting for the cursor to move.</li>
<li>A bug that kept the first page image from displaying in certain cases was fixed.</li>
<li>The "zoom to width" feature of the Pngs panel is slightly faster.</li>
</ul>
<h3>Liberty Mono Bundled</h3>
<p> With this update PPQT now includes Liberation Mono. You can select it with the View > Fonts... menu choice, whether it is officially installed in your system or not.</p>
<p>Note that of the common monospaced fonts, only Courier New and Everson Mono have the Arabic letterforms. Arabic aside, Liberation Mono is a good choice.</p>
<h3>What's New for 8 April 2013</h3>
<p>Fix for a rather obscure bug in HTML conversion.
In the event your document ended with an end-of-markup line
such as <tt>Q/</tt> or <tt>F/</tt> with no newline after it, HTML conversion
could thoroughly mess the document up.</p>
<h3>What's New as of 5 April 2013</h3>
<p>Multiple minor changes and fixes, again thanks to the
diligence of <i>bibimbop</i>:</p>
<ul>
<li>The Words panel sort now respects accents ("locale-aware" sorting).</li>
<li>When you double-click a hyphenated word in the Words panel, the search
now properly finds the whole phrase.</li>
<li>Insertion of page numbers from the Pages panel now
behaves correctly when the inserted text includes a newline.</li>
<li>The Footnotes panel, when moving the notes, now recognizes a /F..F/
section that is at the very end of the document.</li>
<li>Moving footnotes now moves the blank line preceding a note as well as the note.</li>
<li>It was possible for the document hash string saved in the .meta file to
include a curly brace as part of its valid content. File>Open now allows for that.</li>
<li>Major footnote operations (renumber, move, ASCII- or html-convert)
now automatically refresh the footnote table if necessary.</li>
<li>Footnote conversion to ASCII no longer inserts explicit margin and
indent values.</li>
</ul>
<h3>What's New as of 27 March, 2013</h3>
<p>The Preview window now zooms both text and images when
you use the ctl-plus and ctl-minus keys. Previously it only zoomed the text
and left the images unchanged; but that is not what most browsers do.</p>
<p>Bug fixes, thanks to user <i>bibimbop</i>:</p>
<p>When copying documents between disks,
for example when restoring from backup,
it is possible to copy the document file
but not the matching metadata file.
When the meta file is not of the same generation as the book,
page breaks, bookmarks and many other things are all wrong.
Now, when saving a document, PPQT writes a hash signature
of the document into the metadata file.
When loading a document, it compares the hash in the metadata
to a hash of the actual document.
If they differ, it warns you that you have likely got the wrong metadata
file and should immediately close without saving.</p>
<p>After a reflow, the internal markers for page breaks were
moving so that the scan images were no longer in sync
with the text cursor. This is now fixed for reflow, but remains
broken for two cases.</p>
<p>
The first is Table reflow. If a Table spans a page break,
after reflow you will have to move the cursor past the end of
the complete table before the scan image of the second table page
appears. The second is Find/Replace.
If you use Find/Replace to replace text that spans a page break,
the marker for the page break moves to the end of the
replaced text. You have to move the cursor pas the end of
the replaced text for the scan image of the next page
to appear.</p>
<h3>What's New as of 22 December 2012</h3>
<ul>
<li>The status bar of the main window now has both a line number and
a column number display. The column number reflects the nominal position
of the edit cursor. When there is a selection, the nominal position may be the
left or the right end of the selected text, depending on how the selection was made.</li>
<li>After any successful
search the found text is centered in the text window. If the found selection is
large, the top of the selection is always visible although the end of the selection might be out of sight.</li>
<li>The Preview panel has a new button, "Refresh + Clear," which clears
the browser cache so that images are reloaded from disk.</li>
<li>Fixed a minor bug with the display of text after performing a replace
of text at the end of a line with a newline.</li>
<li>The file-open dialog for Load Find Buttons and Save Find Buttons is
initialized to the PPQT "extras" folder, or to the last-used folder for loading
or saving find buttons.</li>
</ul>
<h3>What's New as of 10 December 2012</h3>
<ul>
<li>Clicking one of the Replace buttons in the Find panel (or using ctl-= or ctl-t in the edit panel, which are the same) will only do the replace if the current selection was created by a find. If the selection has changed since a find was last done, the replace is not done and PPQT beeps.</li>
<li>When you double-click a character in the Chars panel, or a word
in the Words panel, PPQT does a find-first for that character or word as before,
but it does not make the Find panel visible. You still see the Chars or Words
panel.</li>
<li>Also, the Respect Case switch is set for these searches, and the
Whole Word switch is set for a Word search.</li>
<li>The File menu shortcuts for Open, New etc. now work as soon as the
program starts up, without having to display the File menu once.</li>
<li>The keyboard shortcuts for the various panels have been removed because they potentially or actually conflict with standard menu shortcuts. Panels can only be displayed by clicking on their tabs.</li>
<li>The find buttons in extras/unbalancedRE.utf have been extended to find some more cases of unbalanced markup. However they can't find everything, see the notes in the file.</li>
</ul>
<h3>What's New as of 4 December 2012</h3>
<p>A number of small fixes thanks to input from users julo and Bibimbop:</p>
<ul>
<li>Corrected the label of the zoom slider on the Pngs panel.</li>
<li>Cleared the default filename from the Save Find Buttons dialog to reduce the chance of saving over the document(!).</li>
<li>Moved the line number field to the left of the status bar.</li>
<li>Fixed ctl-s and ctl-shift-s to work as shortcuts for File>Save and Save-As in Ubuntu and Windows.</li>
<li>Fixed the previous-strings popups in Find and Replace to work correctly on Windows, and to not show a scrap of a character on Ubuntu.</li>
<li>On ctl-f when focus goes to the Find panel, the Find text is all-selected so it is easy to type a new find string.</li>
<li>The View > Dictionary dialog presents dictionary names in sorted order and with the current dictionary selected.</li>
<li>Proper CRLF line-ends written on Windows.</li>
<li>The document-modified indicator turns on more reliably in some cases.</li>
</ul>
<h3>What's New in 1.01.01 (6 Nov. 2012)</h3>
<p>The Edit > Titlecase command now operates correctly when the selected words are uppercase or mixed-case.</p>
<p>The Pngs panel now features new zoom controls, see <a href='#Pngs'>The Pngs Panel</a> below.</p>
<h3>What's New in 1.01 (24 Oct. 2012)</h3>
<p>Fixes:</p>
<ul>
<li>When you select a font with the View > Font... dialog the font size you
pick is remembered for the next session.</li>
<li>When you place the edit cursor above the text of the first page,
the Pngs panel shows the gray "No Image" image instead of showing
the image of the last page.</li>
<li>Zooming in and out with ctl-plus and ctl-minus (supported in the
Edit, Notes, Pngs, Preview and Help panels) works with keys on the keypad as well as on the main keyboard.</li>
<li>When you load a different file of scannos, the hiliting of the words
from the previous scanno file is cleared out.</li>
<li>The save-needed status in the title bar changes correctly as changes occur in the notes and other metadata, as well as with changes in the document.</li>
<li>PPQT now remembers whether a census of words and characters or a spellcheck is needed over save/load. If you change the text or the good-words
list and save the file, when you next load it and click Refresh, the
census and spellcheck are done.</li>
</ul>
<p>New or changed function:</p>
<ul>
<li>There have been major changes in how the encoding for an input file is chosen, and a new command has been added to the File menu: Open With Encoding. See the <a href='#Encodings'>File Encodings</a> topic below.</li>
<li>When a single word is selected in the Edit panel, the standard <a href='#ContextMenu'>context menu</a> has an option to add that word to the good-words list.</li>
<li>When the keyboard focus is in the <a href='#Words'>Words panel</a> and the table is sorted ascending on column 0, keying a letter jumps to the approximate position of words beginning with that letter.</li>
<li>Holding the shift key when going to a bookmark causes the current selection to be extended to the bookmark location.</li>
</ul>
</body>
</html>