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
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><style xmlns="" type="text/css">
div.added { background-color: #ffff99; }
div.deleted { text-decoration: line-through;
background-color: #FF7F7F; }
div.changed { background-color: #99ff99; }
div.off { }
span.added { background-color: #ffff99; }
span.deleted { text-decoration: line-through;
background-color: #FF7F7F; }
span.changed { background-color: #99ff99; }
span.off { }
pre.literallayout {
background-color: #E8E8D0;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
div[class=changed] pre.literallayout {
background-color: #99ff99;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
div.literallayout {
background-color: #E8E8D0;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
div[class=changed] div.literallayout {
background-color: #99ff99;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
</style>
<title>
The xfpt plain text to XML processor</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1" />
</head>
<body>
<div class="book" title="The xfpt plain text to XML processor">
<div class="titlepage">
<div>
<div>
<h1 class="title">
<a id="idm3387464">
</a>
The xfpt plain text to XML processor</h1>
</div>
<div>
<div class="author">
<h3 class="author">
<span class="firstname">
Philip</span>
<span class="surname">
Hazel</span>
</h3>
</div>
</div>
<div>
<p class="copyright">
Copyright © 2012 University of Cambridge</p>
</div>
<div>
<div class="revhistory">
<table border="1" width="100%" summary="Revision history">
<tr>
<th align="left" valign="top" colspan="3">
<strong>
Revision History</strong>
</th>
</tr>
<tr>
<td align="left">
Revision 0.09</td>
<td align="left">
18 May 2012</td>
<td align="left">
PH</td>
</tr>
</table>
</div>
</div>
</div>
<hr />
</div>
<div class="toc">
<p>
<strong>
Table of Contents</strong>
</p>
<dl>
<dt>
<span xmlns="" class="chapter">
<a id="toc0001" href="#ID00">
1. Introduction</a>
</span>
</dt>
<dd>
<dl>
<dt>
<span xmlns="" class="section">
<a id="toc0002" href="#ID01">
1.1. The <span xmlns="http://www.w3.org/1999/xhtml" class="emphasis">
<em>
xfpt</em>
</span>
command line</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0003" href="#ID02">
1.2. A short <span xmlns="http://www.w3.org/1999/xhtml" class="emphasis">
<em>
xfpt</em>
</span>
example</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0004" href="#SECTliteralprocessing">
1.3. Literal and non-literal processing</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0005" href="#ID04">
1.4. Format of directive lines</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0006" href="#SECTcallingmacro">
1.5. Calling macros</a>
</span>
</dt>
</dl>
</dd>
<dt>
<span xmlns="" class="chapter">
<a id="toc0007" href="#ID06">
2. Flag sequences</a>
</span>
</dt>
<dd>
<dl>
<dt>
<span xmlns="" class="section">
<a id="toc0008" href="#ID07">
2.1. Flag sequences for XML entities and <span xmlns="http://www.w3.org/1999/xhtml" class="emphasis">
<em>
xfpt</em>
</span>
variables</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0009" href="#ID08">
2.2. Flag sequences for calling macros</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0010" href="#ID09">
2.3. Other flag sequences</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0011" href="#ID10">
2.4. Unrecognized flag sequences</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0012" href="#ID11">
2.5. Standard flag sequences</a>
</span>
</dt>
</dl>
</dd>
<dt>
<span xmlns="" class="chapter">
<a id="toc0013" href="#ID12">
3. Built-in directive processing</a>
</span>
</dt>
<dd>
<dl>
<dt>
<span xmlns="" class="section">
<a id="toc0014" href="#ID13">
3.1. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
<strong>
.arg</strong>
</span>
directive</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0015" href="#ID14">
3.2. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
<strong>
.eacharg</strong>
</span>
directive</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0016" href="#ID15">
3.3. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
<strong>
.echo</strong>
</span>
directive</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0017" href="#ID16">
3.4. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
<strong>
.endarg</strong>
</span>
directive</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0018" href="#ID17">
3.5. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
<strong>
.endeach</strong>
</span>
directive</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0019" href="#ID18">
3.6. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
<strong>
.endinliteral</strong>
</span>
directive</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0020" href="#ID19">
3.7. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
<strong>
.flag</strong>
</span>
directive</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0021" href="#ID20">
3.8. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
<strong>
.include</strong>
</span>
directive</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0022" href="#ID21">
3.9. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
<strong>
.inliteral</strong>
</span>
directive</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0023" href="#ID22">
3.10. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
<strong>
.literal</strong>
</span>
directive</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0024" href="#SECTmacro">
3.11. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
<strong>
.macro</strong>
</span>
directive</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0025" href="#ID24">
3.12. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
<strong>
.nest</strong>
</span>
directive</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0026" href="#ID25">
3.13. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
<strong>
.nonl</strong>
</span>
directive</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0027" href="#ID26">
3.14. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
<strong>
.pop</strong>
</span>
directive</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0028" href="#ID27">
3.15. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
<strong>
.push</strong>
</span>
directive</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0029" href="#SECTrevision">
3.16. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
<strong>
.revision</strong>
</span>
directive</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0030" href="#ID29">
3.17. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
<strong>
.set</strong>
</span>
directive</a>
</span>
</dt>
</dl>
</dd>
<dt>
<span xmlns="" class="chapter">
<a id="toc0031" href="#CHAPstdmac">
4. The standard macros for DocBook</a>
</span>
</dt>
<dd>
<dl>
<dt>
<span xmlns="" class="section">
<a id="toc0032" href="#ID31">
4.1. Overall setup</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0033" href="#idp3069176">
4.2. Processing instructions</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0034" href="#ID32">
4.3. Chapters, sections, and subsections</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0035" href="#ID33">
4.4. Prefaces, appendixes, and colophons</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0036" href="#idp3081992">
4.5. Terminating chapters, etc.</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0037" href="#ID34">
4.6. URL references</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0038" href="#ID35">
4.7. Itemized lists</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0039" href="#ID36">
4.8. Ordered lists</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0040" href="#ID37">
4.9. Variable lists</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0041" href="#ID38">
4.10. Nested lists</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0042" href="#ID39">
4.11. Displayed text</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0043" href="#ID40">
4.12. Block quotes</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0044" href="#SECTrevmacs">
4.13. Revision markings</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0045" href="#ID42">
4.14. Informal tables</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0046" href="#ID43">
4.15. Formal tables</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0047" href="#ID44">
4.16. Figures and images</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0048" href="#ID45">
4.17. Footnotes</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
<a id="toc0049" href="#ID46">
4.18. Indexes</a>
</span>
</dt>
</dl>
</dd>
</dl>
</div>
<div class="chapter" title="1. Introduction"><div class="titlepage"><div><div><h2 class="title"><a href="#" id="ID00">1. Introduction</a></h2></div></div></div><p><span class="emphasis"><em>xfpt</em></span> is a program that reads a marked-up ASCII source file, and converts it into
XML. It was written with DocBook XML in mind, but can also be used for other
forms of XML. Unlike <span class="emphasis"><em>AsciiDoc</em></span> (<span class="bold"><strong><a class="ulink" href="http://www.methods.co.nz/asciidoc/" target="_top">http://www.methods.co.nz/asciidoc/</a></strong></span>),
<span class="emphasis"><em>xfpt</em></span> does not try to produce XML from a document that is also usable as a
freestanding ASCII document. The input for <span class="emphasis"><em>xfpt</em></span> is very definitely <span class="quote">“<span class="quote">marked
up</span>”</span>. This makes it less ambiguous for large and/or complicated documents. <span class="emphasis"><em>xfpt</em></span>
is also much faster than <span class="emphasis"><em>AsciiDoc</em></span> because it is written in C and does not
rely on pattern matching.
</p><p>
<span class="emphasis"><em>xfpt</em></span> is aimed at users who understand the XML that they are generating. It makes
it easy to include literal XML, either in blocks, or within paragraphs. <span class="emphasis"><em>xfpt</em></span>
restricts itself to two special characters that trigger all its processing.
</p><p>
<span class="emphasis"><em>xfpt</em></span> treats any input line that starts with a dot as a <span class="emphasis"><em>directive</em></span> line.
Directives control the way the input is processed. A small number of directives
are implemented in the program itself. A macro facility makes it possible to
combine these in various ways to define directives for higher-level concepts
such as chapters and sections. A standard macro library that generates a simple
subset of DocBook XML is provided. The only XML element that the program itself
generates is <code class="literal"><para></code>; all the others must be included as literal XML, either
directly in the input text, or, more commonly, as part of the text that is
generated by a macro call.
</p><p>
The ampersand character is special within non-literal text that is processed by
<span class="emphasis"><em>xfpt</em></span>. An ampersand introduces a <span class="emphasis"><em>flag sequence</em></span> that modifies the output.
Ampersand was chosen because it is also special in XML. As well as recognizing
flag sequences that begin with an ampersand, <span class="emphasis"><em>xfpt</em></span> converts grave accents and
apostrophes that appear in non-literal text into typographic opening and
closing quotes, as follows:
</p><div class="literallayout">
<code class="literal"> ` </code> becomes ‘<br />
<code class="literal"> ' </code> becomes ’<br />
</div><p>
Within normal input text, ampersand, grave accent, and apostrophe are the only
characters that cause <span class="emphasis"><em>xfpt</em></span> to change the input text, but this applies only to
non-literal text. In literal text, there are no markup characters, and only a
dot at the start of a line is recognized as special. Within the body of a
macro, there is one more special character: the dollar character is used to
introduce an argument substitution.
</p><p>
Notwithstanding the previous paragraph, <span class="emphasis"><em>xfpt</em></span> knows that it is generating XML,
and in all cases when a literal ampersand or angle bracket is required in the
output, the appropriate XML entity reference (<code class="literal">&amp;</code>, <code class="literal">&lt;</code>, or
<code class="literal">&gt;</code>, respectively) is generated.
</p><div class="section" title="1.1 The xfpt command line"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID01">1.1 The <span xmlns="http://www.w3.org/1999/xhtml" class="emphasis"><em>xfpt</em></span> command line</a></h3></div></div></div><p>The format of the <span class="emphasis"><em>xfpt</em></span> command line is:
</p><div class="literallayout">
<code class="literal">xfpt [</code><span class="emphasis"><em>options</em></span><code class="literal">] [</code><span class="emphasis"><em>input source</em></span><code class="literal">]</code><br />
</div><p>
If no input is specified, the standard input is read. There are four options:
</p><div class="variablelist"><dl><dt><span class="term"><span class="option"><strong>-help</strong></span></span></dt><dd><p>
This option causes <span class="emphasis"><em>xfpt</em></span> to output its <span class="quote">“<span class="quote">usage</span>”</span> message, and exit.
</p></dd><dt><span class="term"><span class="option"><strong>-o</strong></span> <span class="emphasis"><em><output destination></em></span></span></dt><dd><p>
This option overrides the default destination. If the standard input is being
read, the default destination is the standard output. Otherwise, the default
destination is the name of the input file with the extension <em class="filename">.xml</em>,
replacing its existing extension if there is one. A single hyphen character can
be given as an output destination to refer to the standard output.
</p></dd><dt><span class="term"><span class="option"><strong>-S</strong></span> <span class="emphasis"><em><directory path></em></span></span></dt><dd><p>
This option overrides the path to <span class="emphasis"><em>xfpt</em></span>’s library directory that is built into
the program. This makes it possible to use or test alternate libraries.
</p></dd><dt><span class="term"><span class="option"><strong>-v</strong></span></span></dt><dd><p>
This option causes <span class="emphasis"><em>xfpt</em></span> to output its version number and exit.
</p></dd></dl></div></div><div class="section" title="1.2 A short xfpt example"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID02">1.2 A short <span xmlns="http://www.w3.org/1999/xhtml" class="emphasis"><em>xfpt</em></span> example</a></h3></div></div></div><p>Here is a very short example of a complete <span class="emphasis"><em>xfpt</em></span> input file that uses some of the
standard macros and flags:
</p><pre class="literallayout">
.include stdflags
.include stdmacs
.docbook
.book
.chapter "The first chapter"
This is the text of the first chapter. Here is an &'italic'&
word, and here is a &*bold*& one.
.section "This is a section heading"
We can use the &*ilist*& macro to generate an itemized list:
.ilist
The first item in the list.
.next
The last item in the list.
.endlist
There are also standard macros for ordered lists, literal
layout blocks, code blocks, URL references, index entries,
tables, footnotes, figures, etc.
</pre></div><div class="section" title="1.3 Literal and non-literal processing"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="SECTliteralprocessing">1.3 Literal and non-literal processing</a></h3></div></div></div><p><span class="emphasis"><em>xfpt</em></span> processes non-directive input lines in one of four ways (known as
<span class="quote">“<span class="quote">modes</span>”</span>):
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
In the default mode, text is processed paragraph by paragraph.
<sup>[<a id="idp58896" href="#ftn.idp58896" class="footnote">1</a>]</sup>
The end of a paragraph is indicated by the end of the input, a blank line, or
by an occurrence of the <span class="bold"><strong>.literal</strong></span> directive. Other directives (for example,
<span class="bold"><strong>.include</strong></span>) do not of themselves terminate a paragraph. Most of the standard
macros (such as <span class="bold"><strong>.chapter</strong></span> and <span class="bold"><strong>.section</strong></span>) force a paragraph end by
starting their contents with a <span class="bold"><strong>.literal</strong></span> directive.
</p><p>
Because <span class="emphasis"><em>xfpt</em></span> reads a whole paragraph before processing it, error messages
contain the phrase <span class="quote">“<span class="quote">detected near line <span class="emphasis"><em>nnn</em></span></span>”</span>, where the line number is
typically that of the last line of the paragraph.
</p></li><li class="listitem"><p>
In the <span class="quote">“<span class="quote">literal layout</span>”</span> mode, text is processed line by line, but is
otherwise handled as in the default mode. The only real difference this makes
to the markup from the user’s point of view is that both parts of a set of
paired flags must be on the same line. In this mode, error messages are more
likely to contain the exact line number where the fault lies. Literal layout
mode is used by the standard <span class="bold"><strong>.display</strong></span> macro to generate <code class="literal"><literallayout></code>
elements.
</p></li><li class="listitem"><p>
In the <span class="quote">“<span class="quote">literal text</span>”</span> mode, text is also processed line by line, but no flags
are recognized. The only modification <span class="emphasis"><em>xfpt</em></span> makes to the text is to turn
ampersand and angle bracket characters into XML entity references. This mode is
used by the standard <span class="bold"><strong>.code</strong></span> macro to generate <code class="literal"><literallayout></code> elements
that include <code class="literal">class=monospaced</code>.
</p></li><li class="listitem"><p>
In the <span class="quote">“<span class="quote">literal XML</span>”</span> mode, text lines are copied to the output without
modification. This is the easiest way to include a chunk of literal XML in the
output. An example might be the <code class="literal"><bookinfo></code> element, which occurs only once
in a document. It is not worth setting up a macro for a one-off item like this.
</p></li></ul></div><p>
The <span class="bold"><strong>.literal</strong></span> directive switches between the modes. It is not normally used
directly, but instead is incorported into appropriate macro definitions. The
<span class="bold"><strong>.inliteral</strong></span> directive can be used to test the current mode.
</p><p>
Directive lines are recognized and acted upon in all four modes. However, an
unrecognized line that starts with a dot in the literal text or literal XML
mode is treated as data. In the other modes, such a line provokes an error.
</p><p>
If you need to have a data line that begins with a dot in literal layout mode,
you can either specify it by character number, or precede it with some
non-acting markup. These two examples are both valid:
</p><pre class="literallayout">
&#x2e;start with a dot
&''&.start with a dot
</pre><p>
The second example assumes the standard flags are defined: it precedes the dot
with an empty italic string. However, this is untidy because the empty string
will be carried over into the XML.
</p><p>
In literal text or literal XML mode, it is not possible to have a data line
that starts with a dot followed by the name of a directive or macro. You have
to use literal layout mode if you require such output. Another solution, which
is used in the source for this document (where many examples show directive
lines), is to indent every displayed line by one space, and thereby avoid the
problem altogether.
</p></div><div class="section" title="1.4 Format of directive lines"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID04">1.4 Format of directive lines</a></h3></div></div></div><p>If an input line starts with a dot followed by a space, it is ignored by <span class="emphasis"><em>xfpt</em></span>.
This provides a facility for including comments in the input. Otherwise, the
dot must be followed by a directive or macro name, and possibly one or more
arguments. Arguments that are strings are delimited by white space unless they
are enclosed in single or double quotes. The delimiting quote character can be
included within a quoted string by doubling it. Here are some examples:
</p><pre class="literallayout">
.literal layout
.set version 0.00
.row "Jack's house" 'Jill''s house'
</pre><p>
An unrecognized directive line normally causes an error; however, in the
literal text and literal XML modes, an unrecognized line that starts with a
dot is treated as a data line.
</p></div><div class="section" title="1.5 Calling macros"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="SECTcallingmacro">1.5 Calling macros</a></h3></div></div></div><p>Macros are defined by the <span class="bold"><strong>.macro</strong></span> directive, which is described in section
<a class="xref" href="#SECTmacro" title="3.11 The .macro directive">3.11</a>. There are two ways of calling a macro. It can be called in the
same way as a directive, or it can be called from within text that is being
processed. The second case is called an <span class="quote">“<span class="quote">inline macro call</span>”</span>.
</p><p>
When a macro is called as a directive, its name is given after a dot at the
start of a line, and the name may be followed by any number of optional
arguments, in the same way as a built-in directive (see the previous section).
For example:
</p><pre class="literallayout">
.chapter "Chapter title" chapter-reference
</pre><p>
The contents of the macro, after argument substitution, are processed in
exactly the same way as normal input lines. A macro that is called as a
directive may contain nested macro calls.
</p><p>
When a macro is called from within a text string, its name is given after an
ampersand, and is followed by an opening parenthesis. Arguments, delimited by
commas, can then follow, up to a closing parenthesis. If an argument contains a
comma or a closing parenthesis, it must be quoted. White space after a
separating comma is ignored. The most common example of this type of macro
call is the standard macro for generating a URL reference:
</p><pre class="literallayout">
Refer to a URL via &url(http://x.example,this text).
</pre><p>
There are differences in the behaviour of macros, depending on which way they
are called. A macro that is called inline may not contain references to other
macros; it must contain only text lines and calls to built-in directives.
Also, newlines that terminate text lines within the macro are not included in
the output.
</p><p>
A macro that can be called inline can always be called as a directive, but the
opposite is not always true. Macros are usually designed to be called either
one way or the other. However, the <span class="bold"><strong>.new</strong></span> and <span class="bold"><strong>.index</strong></span> macros in the
standard library are examples of macros that are designed be called either way.
</p></div><div class="footnotes"><br /><hr width="100" align="left" /><div class="footnote"><p><sup>[<a id="ftn.idp58896" href="#idp58896" class="para">1</a>] </sup>
There is, however, a special case when a paragraph contains one or more
footnotes. In that situation, each part of the outer paragraph is processed
independently.
</p></div></div></div><div class="chapter" title="2. Flag sequences"><div class="titlepage"><div><div><h2 class="title"><a href="#" id="ID06">2. Flag sequences</a></h2></div></div></div><p>Only one flag sequence is built-into the code itself. If an input line ends
with three ampersands (ignoring trailing white space), the ampersands are
removed, and the next input line, with any leading white space removed, is
joined to the original line. This happens before any other processing, and may
involve any number of lines. Thus:
</p><div class="literallayout">
<code class="literal">The quick &&&</code><br />
<code class="literal"> brown &&&</code><br />
<code class="literal"> fox.</code><br />
</div><p>
produces exactly the same output as:
</p><pre class="literallayout">
The quick brown fox.
</pre><div class="section" title="2.1 Flag sequences for XML entities and xfpt variables"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID07">2.1 Flag sequences for XML entities and <span xmlns="http://www.w3.org/1999/xhtml" class="emphasis"><em>xfpt</em></span> variables</a></h3></div></div></div><p>If an ampersand is followed by a # character, a number, and a semicolon, it is
understood as a numerical reference to an XML entity, and is passed through
unmodified. The number can be decimal, or hexadecimal preceded by <code class="literal">x</code>. For
example:
</p><pre class="literallayout">
This is an Ohm sign: &#x2126;.
This is a degree sign: &#176;.
</pre><p>
If an ampersand is followed by a letter, a sequence of letters, digits, and
dots is read. If this is terminated by a semicolon, the characters between the
ampersand and the semicolon are interpreted as an entity name. This can be:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
The name of an inbuilt <span class="emphasis"><em>xfpt</em></span> variable. At present, there is only one of these,
called <code class="literal">xfpt.rev</code>. Its use is described with the <span class="bold"><strong>.revision</strong></span> directive
below.
</p></li><li class="listitem"><p>
The name of a user variable that has been set by the <span class="bold"><strong>.set</strong></span> directive, also
described below.
</p></li><li class="listitem"><p>
The name of an XML entity. This is assumed if the name is not recognized as one
of the previous types. In this case, the input text is passed to the output
without modification. For example:
</p><pre class="literallayout">
This is an Ohm sign: &Ohm;.
</pre></li></ul></div></div><div class="section" title="2.2 Flag sequences for calling macros"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID08">2.2 Flag sequences for calling macros</a></h3></div></div></div><p>If an ampersand is followed by a sequence of alphanumeric characters starting
with a letter, terminated by an opening parenthesis, the characters between the
ampersand and the parenthesis are interpreted as the name of a macro. See
section <a class="xref" href="#SECTcallingmacro" title="1.5 Calling macros">1.5</a> for more details.
</p></div><div class="section" title="2.3 Other flag sequences"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID09">2.3 Other flag sequences</a></h3></div></div></div><p>Any other flag sequences that are needed must be defined by means of the
<span class="bold"><strong>.flag</strong></span> directive. These are of two types, standalone and paired. Both cases
define replacement text. This is always literal; it is not itself scanned for
flag occurrences.
</p><p>
Lines are scanned from left to right when flags are being interpreted. If
there is any ambiguity when a text string is being scanned, the longest flag
sequence wins. Thus, it is possible (as in the standard flag sequences) to
define both <code class="literal">&<</code> and <code class="literal">&<<</code> as flags, provided that you never want to
follow the first of them with a <code class="literal"><</code> character.
</p><p>
You can define flags that start with <code class="literal">&#</code>, but these must be used with care,
lest they be misinterpreted as numerical references to XML entities.
</p><p>
A standalone flag consists of an ampersand followed by any number of
non-alphanumeric characters. When it is encountered, it is replaced by its
replacement text. For example, in the standard flag definitions, <code class="literal">&&</code>
is defined as a standalone flag with with the replacement text <code class="literal">&amp;</code>.
</p><p>
A paired flag is defined as two sequences. The first takes the same form as a
standalone flag. The second also consists of non-alphanumeric characters, but
need not start with an ampersand. It is often defined as the reverse of the
first sequence. For example, in the standard definitions, <code class="literal">&'</code> and
<code class="literal">'&</code> are defined as a flag pair for enclosing text in an <code class="literal"><emphasis></code>
element.
</p><p>
When the first sequence of a paired flag is encountered, its partner is
expected to be found within the same text unit. In the default mode, the units
are a paragraphs, or part-paragraphs if footnotes intervene. In literal layout
mode, the text is processed line by line. Each member of the pair is replaced
by its replacement text.
</p><p>
Multiple occurrences of paired flags must be correctly nested. Note that,
though <span class="emphasis"><em>xfpt</em></span> diagnoses an error for badly nested flag pairs, it does not prevent
you from generating invalid XML. For example, DocBook does not allow
<code class="literal"><emphasis></code> within <code class="literal"><literal></code>, though it does allow <code class="literal"><literal></code> within
<code class="literal"><emphasis></code>.
</p></div><div class="section" title="2.4 Unrecognized flag sequences"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID10">2.4 Unrecognized flag sequences</a></h3></div></div></div><p>If an ampersand is not followed by a character sequence in one of the forms
described in the preceding sections, an error occurs.
</p></div><div class="section" title="2.5 Standard flag sequences"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID11">2.5 Standard flag sequences</a></h3></div></div></div><p>These are the standalone flag sequences that are defined in the <em class="filename">stdflags</em>
file in the <span class="emphasis"><em>xfpt</em></span> library:
</p><div class="literallayout">
<code class="literal">&& </code> becomes <code class="literal"> &amp;</code> (ampersand)<br />
<code class="literal">&-- </code> becomes <code class="literal"> &ndash;</code> (en-dash)<br />
<code class="literal">&~ </code> becomes <code class="literal"> &nbsp;</code> (‘hard’ space)<br />
</div><p>
These are the flag pairs that are defined in the <em class="filename">stdflags</em> file in the <span class="emphasis"><em>xfpt</em></span>
library:
</p><div class="literallayout">
<code class="literal">&"..."& </code> becomes <code class="literal"><quote>...</quote></code><br />
<code class="literal">&'...'& </code> becomes <code class="literal"><emphasis>...</emphasis></code><br />
<code class="literal">&*...*& </code> becomes <code class="literal"><emphasis role="bold">...</emphasis></code><br />
<code class="literal">&`...`& </code> becomes <code class="literal"><literal>...</literal></code><br />
<code class="literal">&_..._& </code> becomes <code class="literal"><filename>...</filename></code><br />
<code class="literal">&(...)& </code> becomes <code class="literal"><command>...</command></code><br />
<code class="literal">&[...]& </code> becomes <code class="literal"><function>...</function></code><br />
<code class="literal">&%...%& </code> becomes <code class="literal"><option>...</option></code><br />
<code class="literal">&$...$& </code> becomes <code class="literal"><varname>...</varname></code><br />
<code class="literal">&<...>& </code> becomes <code class="literal"><...></code><br />
<code class="literal">&<<...>>& </code> becomes <code class="literal"><xref linkend="..."/></code><br />
</div><p>
For example, if you want to include a literal XML element in your output, you
can do it like this: <code class="literal">&<element>&</code>. If you want to include a longer
sequence of literal XML, changing to the literal XML mode may be more
convenient.
</p></div></div><div class="chapter" title="3. Built-in directive processing"><div class="titlepage"><div><div><h2 class="title"><a href="#" id="ID12">3. Built-in directive processing</a></h2></div></div></div><p>The directives that are built into the code of <span class="emphasis"><em>xfpt</em></span> are now described in
alphabetical order. You can see more examples of their use in the descriptions
of the standard macros in chapter <a class="xref" href="#CHAPstdmac" title="4. The standard macros for DocBook">4</a>.
</p><div class="section" title="3.1 The .arg directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID13">3.1 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.arg</strong></span> directive</a></h3></div></div></div><p>This directive may appear only within the body of a macro. It must be followed
by a single number, optionally preceded by a minus sign. If the number is
positive (no minus sign), subsequent lines, up to a <span class="bold"><strong>.endarg</strong></span> directive, are
skipped unless the macro has been called with at least that number of
arguments and the given argument is not an empty string. If the number is
negative (minus sign present), subsequent lines are skipped if the macro has
been called with fewer than that number of arguments, or with an empty string
for the given argument. For example:
</p><pre class="literallayout">
.macro example
.arg 2
Use these lines if there are at least 2 arguments
and the second one is not empty. Normally there would
be a reference to the 2nd argument.
.endarg
.arg -2
Use this line unless there are at least 2 arguments
and the second one is not empty.
.endarg
.endmacro
</pre><p>
Note that if a macro is defined with default values for its arguments, these
are not counted by the <span class="bold"><strong>.arg</strong></span> directive, which looks only at the actual
arguments in a particular macro call.
</p><p>
The <span class="bold"><strong>.arg</strong></span> directive may be nested.
</p></div><div class="section" title="3.2 The .eacharg directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID14">3.2 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.eacharg</strong></span> directive</a></h3></div></div></div><p>This directive may appear only within the body of a macro. It may optionally be
followed by a single number; if omitted the value is taken to be 1. Subsequent
lines, up to a <span class="bold"><strong>.endeach</strong></span> directive, are processed multiple times, once for
each remaining argument. Unlike <span class="bold"><strong>.arg</strong></span>, an argument that is an empty string
is not treated specially. However, like <span class="bold"><strong>.arg</strong></span>, only the actual arguments of
a macro call are considered. Default argument values do not count.
</p><p>
The number given with <span class="bold"><strong>.eacharg</strong></span> defines which argument to start with. If the
macro is called with fewer arguments, the lines up to <span class="bold"><strong>.endeach</strong></span> are skipped,
and are not processed at all. When these lines are being processed, the
remaining macro arguments can be referenced relative to the current argument.
<code class="literal">$+1</code> refers to the current argument, <code class="literal">$+2</code> to the next argument, and so
on.
</p><p>
The <span class="bold"><strong>.endeach</strong></span> directive may also be followed by a number, again defaulting
to 1. When <span class="bold"><strong>.endeach</strong></span> is reached, the current argument number is incremented
by that number. If there are still unused arguments available, the lines
between <span class="bold"><strong>.eacharg</strong></span> and <span class="bold"><strong>.endeach</strong></span> are processed again.
</p><p>
This example is taken from the coding for the standard <span class="bold"><strong>.row</strong></span> macro, which
generates an <code class="literal"><entry></code> element for each of its arguments:
</p><pre class="literallayout">
.eacharg
&<entry>&$+1&</entry>&
.endeach
</pre><p>
This example is taken from the coding for the standard <span class="bold"><strong>.itable</strong></span> macro, which
processes arguments in pairs to define the table’s columns, starting from the
fifth argument:
</p><pre class="literallayout">
.eacharg 5
&<colspec colwidth="$+1" align="$+2"/>&
.endeach 2
</pre><p>
The <span class="bold"><strong>.eacharg</strong></span> directive may in principle be nested, though this does not
seem useful in practice.
</p></div><div class="section" title="3.3 The .echo directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID15">3.3 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.echo</strong></span> directive</a></h3></div></div></div><p>This directive takes a single string argument. It writes it to the standard
error stream. Within a macro, argument substitution takes place, but no other
processing is done on the string. This directive can be useful for debugging
macros or writing comments to the user.
</p></div><div class="section" title="3.4 The .endarg directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID16">3.4 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.endarg</strong></span> directive</a></h3></div></div></div><p>See the description of <span class="bold"><strong>.arg</strong></span> above.
</p></div><div class="section" title="3.5 The .endeach directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID17">3.5 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.endeach</strong></span> directive</a></h3></div></div></div><p>See the description of <span class="bold"><strong>.eacharg</strong></span> above.
</p></div><div class="section" title="3.6 The .endinliteral directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID18">3.6 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.endinliteral</strong></span> directive</a></h3></div></div></div><p>See the description of <span class="bold"><strong>.inliteral</strong></span> below.
</p></div><div class="section" title="3.7 The .flag directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID19">3.7 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.flag</strong></span> directive</a></h3></div></div></div><p>This directive is used to define flag sequences. The directive must be followed
either by a standalone flag sequence and one string in quotes, or by a flag
pair and two strings in quotes. White space separates these items. For example:
</p><pre class="literallayout">
.flag && "&amp;"
.flag &" "& "<quote>" "</quote>"
</pre><p>
There are more examples in the definitions of the standard flags. If you
redefine an existing flag, the new definition overrides the old. There is no
way to revert to the previous definition.
</p></div><div class="section" title="3.8 The .include directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID20">3.8 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.include</strong></span> directive</a></h3></div></div></div><p>This directive must be followed by a single string argument that is the path to
a file. The contents of the file are read and incorporated into the input at
this point. If the string does not contain any slashes, the path to the <span class="emphasis"><em>xfpt</em></span>
library is prepended. Otherwise, the path is used unaltered. If
<span class="bold"><strong>.include</strong></span> is used inside a macro, it is evaluated each time the macro is
called, and thus can be used to include a different file on each occasion.
</p></div><div class="section" title="3.9 The .inliteral directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID21">3.9 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.inliteral</strong></span> directive</a></h3></div></div></div><p>This directive may appear only within the body of a macro. It must be followed
by one of the words <span class="quote">“<span class="quote">layout</span>”</span>, <span class="quote">“<span class="quote">text</span>”</span>, <span class="quote">“<span class="quote">off</span>”</span>, or <span class="quote">“<span class="quote">xml</span>”</span>. If the current
literal mode does not correspond to the word, subsequent lines, up to a
<span class="bold"><strong>.endinliteral</strong></span> directive, are skipped. The <span class="bold"><strong>.inliteral</strong></span> directive may be
nested.
</p></div><div class="section" title="3.10 The .literal directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID22">3.10 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.literal</strong></span> directive</a></h3></div></div></div><p>This must be followed by one of the words <span class="quote">“<span class="quote">layout</span>”</span>, <span class="quote">“<span class="quote">text</span>”</span>, <span class="quote">“<span class="quote">off</span>”</span>, or
<span class="quote">“<span class="quote">xml</span>”</span>. It forces an end to a previous paragraph, if there is one, and then
switches between processing modes. The default mode is the <span class="quote">“<span class="quote">off</span>”</span> mode, in
which text is processed paragraph by paragraph, and flags are recognized.
Section <a class="xref" href="#SECTliteralprocessing" title="1.3 Literal and non-literal processing">1.3</a> describes how input lines are processed in
the four modes.
</p></div><div class="section" title="3.11 The .macro directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="SECTmacro">3.11 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.macro</strong></span> directive</a></h3></div></div></div><p>This directive is used to define macros. It must be followed by a macro name,
and then, optionally, by any number of arguments. The macro name can be any
sequence of non-whitespace characters. The arguments in the definition provide
default values. The following lines, up to <span class="bold"><strong>.endmacro</strong></span>, form the body of the
macro. They are not processed in any way when the macro is defined; they are
processed only when the macro is called (see section <a class="xref" href="#SECTcallingmacro" title="1.5 Calling macros">1.5</a>).
</p><p>
Within the body of a macro, argument substitutions can be specified by means of
a dollar character and an argument number, for example, <code class="literal">$3</code> for the third
argument. See also <span class="bold"><strong>.eacharg</strong></span> above for the use of <code class="literal">$+</code> to refer to
relative arguments when looping through them. A reference to an argument that
is not supplied, and is not given a default, results in an empty substitution.
</p><p>
There is also a facility for a conditional substitution. A reference to an
argument of the form:
</p><div class="literallayout">
<code class="literal">$=</code><span class="emphasis"><em><digits><delimiter><text><delimiter></em></span><br />
</div><p>
inserts the text if the argument is defined and is not an empty string, and
nothing otherwise. The text is itself scanned for flags and argument
substitutions. The delimiter must be a single character that does not appear in
the text. For example:
</p><pre class="literallayout">
&<chapter$=2+ id="$2"+>&
</pre><p>
If this appears in a macro that is called with only one argument, the result
is:
</p><pre class="literallayout">
<chapter>
</pre><p>
but if the second argument is, say <code class="literal">abcd</code>, the result is:
</p><pre class="literallayout">
<chapter id="abcd">
</pre><p>
This conditional feature can be used with both absolute and relative argument
references.
</p><p>
If a dollar character is required as data within the body of a macro, it must
be doubled. For example:
</p><pre class="literallayout">
.macro price
The price is $$1.
.endmacro
</pre><p>
If you redefine an existing macro, the new definition overrides the old. There
is no way to revert to the previous definition. If you define a macro whose
name is the same as the name of a built-in directive you will not be able to
call it, because <span class="emphasis"><em>xfpt</em></span> looks for built-in directives before it looks for macros.
</p><p>
It is possible to define a macro within a macro, though clearly care must be
taken with argument references to ensure that substitutions happen at the right
level.
</p></div><div class="section" title="3.12 The .nest directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID24">3.12 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.nest</strong></span> directive</a></h3></div></div></div><p>This directive must be followed by one of the words <span class="quote">“<span class="quote">begin</span>”</span> or <span class="quote">“<span class="quote">end</span>”</span>. It is
used to delimit a nested sequence of independent text items that occurs inside
another, such as the contents of a footnote inside a paragraph. This directive
is usually used inside a macro. For example, a <span class="bold"><strong>footnote</strong></span> macro could be
defined like this:
</p><pre class="literallayout">
.macro footnote
&<footnote>&
.nest begin
.endmacro
</pre><p>
At the start of a nested sequence, the current mode and paragraph state are
remembered and <span class="emphasis"><em>xfpt</em></span> then reverts to the default mode and <span class="quote">“<span class="quote">not in a paragraph</span>”</span>.
At the end of a nested sequence, if a paragraph has been started, it is
terminated, and then <span class="emphasis"><em>xfpt</em></span> reverts to the previous state.
</p></div><div class="section" title="3.13 The .nonl directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID25">3.13 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.nonl</strong></span> directive</a></h3></div></div></div><p>This directive must be followed by a single string argument. It is processed
as an input line without a newline at the end. This facility is useful
in macros when constructing a single data line from several text fragments. See
for example the <span class="bold"><strong>.new</strong></span> macro in the standard macros.
</p></div><div class="section" title="3.14 The .pop directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID26">3.14 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.pop</strong></span> directive</a></h3></div></div></div><p><span class="emphasis"><em>xfpt</em></span> keeps a stack of text strings that are manipulated by the <span class="bold"><strong>.push</strong></span> and
<span class="bold"><strong>.pop</strong></span> directives. When the end of the input is reached, any strings that
remain on the stack are popped off, processed for flags, and written to the
output. In some cases (see the <span class="bold"><strong>.push</strong></span> directive below) a warning message is
given.
</p><p>
Each string on the stack may, optionally, be associated with an upper case
letter. If <span class="bold"><strong>.pop</strong></span> is followed by an upper case letter, it searches down the
stack for a string with the same letter. If it cannot find one, it does
nothing. Otherwise, it pops off, processes, and writes out all the strings down
to and including the one that matches.
</p><p>
If <span class="bold"><strong>.pop</strong></span> is given without a following letter, it pops one string off the
stack and writes it out. If there is nothing on the stack, an error occurs.
</p></div><div class="section" title="3.15 The .push directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID27">3.15 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.push</strong></span> directive</a></h3></div></div></div><p>This directive pushes a string onto the stack. If the rest of the command line
starts with an upper case letter followed by white space or the end of the
line, that letter is associated with the string that is pushed, which consists
either of a quoted string, or the rest of the line. After a quoted string, the
word ‘check’ may appear. In this case, if the string has not been popped off
the stack by the end of processing, a warning message is output. This facility
is used by the standard macros to give warnings for unclosed items such as
<span class="bold"><strong>.ilist</strong></span>.
</p><p>
For example, the <span class="bold"><strong>.chapter</strong></span> macro contains this line:
</p><pre class="literallayout">
.push C &</chapter>&
</pre><p>
Earlier in the macro there is the line:
</p><pre class="literallayout">
.pop C
</pre><p>
This arrangement ensures that any previous chapter is terminated before
starting a new one, and also when the end of the input is reached. The
<span class="bold"><strong>.ilist</strong></span> macro contains this line:
</p><pre class="literallayout">
.push L "&</itemizedlist>&" check
</pre><p>
Item lists are terminatated by <span class="bold"><strong>.endlist</strong></span>, which contains:
</p><pre class="literallayout">
.pop L
</pre><p>
However, if <span class="bold"><strong>.endlist</strong></span> is accidentally omitted (or <span class="bold"><strong>.ilist</strong></span> is accidentally
included), the appearance of ‘check’ means that a warning is issued to alert
the user to a possible problem.
</p></div><div class="section" title="3.16 The .revision directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="SECTrevision">3.16 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.revision</strong></span> directive</a></h3></div></div></div><p>This directive is provided to make it easy to set the <code class="literal">revisionflag</code>
attribute on XML elements in a given portion of the document. The DocBook
specification states that the <code class="literal">revisionflag</code> attribute is common to all
elements.
</p><p>
The <span class="bold"><strong>.revision</strong></span> directive must be followed by one of the words <span class="quote">“<span class="quote">changed</span>”</span>,
<span class="quote">“<span class="quote">added</span>”</span>, <span class="quote">“<span class="quote">deleted</span>”</span>, or <span class="quote">“<span class="quote">off</span>”</span>. For any value other than <span class="quote">“<span class="quote">off</span>”</span>, it causes
the internal variable <span class="emphasis"><em>xfpt.rev</em></span> to be set to <code class="literal">revisionflag=</code> followed by
the given argument. If the argument is <span class="quote">“<span class="quote">off</span>”</span>, the internal variable is
emptied.
</p><p>
The contents of <span class="emphasis"><em>xfpt.rev</em></span> are included in every <code class="literal"><para></code> element that <span class="emphasis"><em>xfpt</em></span>
generates. In addition, a number of the standard macros contain references to
<span class="emphasis"><em>xfpt.rev</em></span> in appropriate places. Thus, setting:
</p><pre class="literallayout">
.revision changed
</pre><p>
should cause all subsequent text to be marked up with <code class="literal">revisionflag</code>
attributes, until
</p><pre class="literallayout">
.revision off
</pre><p>
is encountered. Unfortunately, at the time of writing, not all DocBook
processing software pays attention to the <code class="literal">revisionflag</code> attribute.
Furthermore, some software grumbles that it is <span class="quote">“<span class="quote">unexpected</span>”</span> on some elements,
though it does still seem to process it correctly.
</p><p>
For handling the most common case (setting and unsetting <span class="quote">“<span class="quote">changed</span>”</span>), the
standard macros <span class="bold"><strong>.new</strong></span> and <span class="bold"><strong>.wen</strong></span> are provided (see section
<a class="xref" href="#SECTrevmacs" title="4.13 Revision markings">4.13</a>).
</p></div><div class="section" title="3.17 The .set directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID29">3.17 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.set</strong></span> directive</a></h3></div></div></div><p>This directive must be followed by a name and a text string. It defines a user
variable and gives it a name. A reference to the name in the style of an XML
entity causes the string to be substituted, without further processing. For
example:
</p><pre class="literallayout">
.set version 4.99
</pre><p>
This could be referenced as <code class="literal">&version;</code>. If a variable is given the name of
an XML entity, you will not be able to refer to the XML entity, because local
variables take precedence. There is no way to delete a local variable after it
has been defined.
</p></div></div><div class="chapter" title="4. The standard macros for DocBook"><div class="titlepage"><div><div><h2 class="title"><a href="#" id="CHAPstdmac">4. The standard macros for DocBook</a></h2></div></div></div><p>A set of simple macros for commonly needed DocBook features is provided in
<span class="emphasis"><em>xfpt</em></span>’s library. This may be extended as experience with <span class="emphasis"><em>xfpt</em></span> accumulates. The
standard macros assume that the standard flags are defined, so a document that
is going to use these features should start with:
</p><pre class="literallayout">
.include stdflags
.include stdmacs
</pre><p>
All the standard macros except <span class="bold"><strong>new</strong></span>, <span class="bold"><strong>index</strong></span>, and <span class="bold"><strong>url</strong></span> are intended to
be called as directive lines. Their names are therefore shown with a leading
dot in the discussion below.
</p><div class="section" title="4.1 Overall setup"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID31">4.1 Overall setup</a></h3></div></div></div><p>There are two macros that should be used only once, at the start of the
document. The <span class="bold"><strong>.docbook</strong></span> macro has no arguments. It inserts into the output
file the standard header material for a DocBook XML file, which is:
</p><pre class="literallayout">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
</pre><p>
The <span class="bold"><strong>.book</strong></span> macro has no arguments. It generates <code class="literal"><book></code> and pushes
<code class="literal"></book></code> onto the stack so that it will be output at the end.
</p></div><div class="section" title="4.2 Processing instructions"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="idp3069176">4.2 Processing instructions</a></h3></div></div></div><p>XML processing instructions such as <code class="literal"><?sdop</code> <code class="literal">toc_sections="no"?></code> can, of
course, be written written literally between <code class="literal">.literal</code> <code class="literal">xml</code> and
<code class="literal">.literal</code> <code class="literal">off</code>. If there are a lot of them, this is perhaps the most
convenient approach. A macro called <span class="bold"><strong>.pi</strong></span> is provided as an easy way of
setting up a short processing instruction. Its first argument is the name of
the processor for which the instruction is intended, and its second argument is
the contents of the instruction, for example:
</p><pre class="literallayout">
.pi sdop 'toc_sections="yes,yes,no"'
</pre><p>
This generates <code class="literal"><?sdop</code> <code class="literal">toc_sections="yes,yes,no"?></code>.
</p></div><div class="section" title="4.3 Chapters, sections, and subsections"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID32">4.3 Chapters, sections, and subsections</a></h3></div></div></div><p>Chapters, sections, and subsections are supported by three macros that all
operate in the same way. They are <span class="bold"><strong>.chapter</strong></span>, <span class="bold"><strong>.section</strong></span>, and
<span class="bold"><strong>.subsection</strong></span>. They take either one, two, or three arguments. The first
argument is the title. If a second argument is present, and is not an empty
string, it is set as an ID, and can be used in cross-references. For example:
</p><pre class="literallayout">
.chapter "Introduction"
</pre><p>
sets no ID, but
</p><pre class="literallayout">
.section "A section title" "SECTdemo"
</pre><p>
can be referenced from elsewhere in the document by a phrase such as:
</p><pre class="literallayout">
see section &<<SECTdemo>>&
</pre><p>
When the title of a chapter of section is being used as a running head or foot
(for example), it may be too long to fit comfortably into the available space.
DocBook provides the facility for a title abbreviation to be specified to deal
with this problem. If a third argument is given to one of these macros, it
causes a <code class="literal"><titleabbrev></code> element to be generated. In this case, a second
argument must also be provided, but if you do not need an ID, the second
argument can be an empty string. For example:
</p><pre class="literallayout">
.chapter "This chapter has quite a long title" "" "Long title"
</pre><p>
Where and when the abbreviation is used in place of the full title is
controlled by the stylesheet when the XML is processed.
</p></div><div class="section" title="4.4 Prefaces, appendixes, and colophons"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID33">4.4 Prefaces, appendixes, and colophons</a></h3></div></div></div><p>The macros <span class="bold"><strong>.preface</strong></span>, <span class="bold"><strong>.appendix</strong></span>, and <span class="bold"><strong>.colophon</strong></span> operate in the same
way as <span class="bold"><strong>.chapter</strong></span>, except that the first and the last have the default title
strings <span class="quote">“<span class="quote">Preface</span>”</span> and <span class="quote">“<span class="quote">Colophon</span>”</span>.
</p></div><div class="section" title="4.5 Terminating chapters, etc."><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="idp3081992">4.5 Terminating chapters, etc.</a></h3></div></div></div><p>The macros for chapters, sections, appendixes, etc. use the stack to ensure
that each one is terminated at the correct point, without the need for an
explicit terminator. For example, starting a new section automatically
terminates an open subsection and a previous section.
</p><p>
Occasionally, however, there is a need to force an explicit termination. The
<span class="bold"><strong>.endchapter</strong></span>, <span class="bold"><strong>.endsection</strong></span>, <span class="bold"><strong>.endsubsection</strong></span>, <span class="bold"><strong>.endpreface</strong></span>,
<span class="bold"><strong>.endappendix</strong></span>, and <span class="bold"><strong>.endcolophon</strong></span> macros provide this facility. For
example, if you want to include an XML processing instruction after a preface,
but before the start of the following chapter, you must terminate the preface
with <span class="bold"><strong>.endpreface</strong></span>. Otherwise a processing instruction that precedes the next
<span class="bold"><strong>.chapter</strong></span> will end up inside the <code class="literal"><preface></code> element. You should not
include any actual text items at these points.
</p></div><div class="section" title="4.6 URL references"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID34">4.6 URL references</a></h3></div></div></div><p>The <span class="bold"><strong>url</strong></span> macro generates URL references, and is intended to be called inline
within the text that is being processed. It generates a <code class="literal"><ulink></code> element,
and has either one or two arguments. The first argument is the URL, and the
second is the text that describes it. For example:
</p><pre class="literallayout">
More details are &url(http://x.example, here).
</pre><p>
This generates the following XML:
</p><pre class="literallayout">
More details are <ulink url="http://x.example">here</ulink>.
</pre><p>
If the second argument is absent, the contents of the first argument are used
instead. If <span class="bold"><strong>url</strong></span> is called as a directive, there will be a newline in the
output after <code class="literal"></ulink></code>, which in most cases (such as the example above), you
do not want.
</p></div><div class="section" title="4.7 Itemized lists"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID35">4.7 Itemized lists</a></h3></div></div></div><p>The <span class="bold"><strong>.ilist</strong></span> macro marks the start of an itemized list, the items of which
are normally rendered with bullets or similar markings. The macro can
optionally be called with one argument, for which there is no default. If the
argument is present, it is used to add a <code class="literal">mark=</code> attribute to the
<code class="literal"><itemizedlist></code> element that is generated. The mark names that can be used
depend on the software that processes the resulting XML. For HTML output,
<span class="quote">“<span class="quote">square</span>”</span> and <span class="quote">“<span class="quote">opencircle</span>”</span> work in some browsers.
</p><p>
The text for the first item follows the macro call. The start of the next item
is indicated by the <span class="bold"><strong>.next</strong></span> macro, and the end of the list by <span class="bold"><strong>.endlist</strong></span>.
For example:
</p><pre class="literallayout">
.ilist
This is the first item.
.next
This is the next item.
.endlist
</pre><p>
There may be more than one paragraph in an item.
</p></div><div class="section" title="4.8 Ordered lists"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID36">4.8 Ordered lists</a></h3></div></div></div><p>The <span class="bold"><strong>.olist</strong></span> macro marks the start of an ordered list, the items of which are
numbered. If no argument is given, arabic numerals are used. One of the
following words can be given as the macro’s argument to specify the numeration:
</p><div class="literallayout">
<code class="literal">arabic </code> arabic numerals<br />
<code class="literal">loweralpha </code> lower case letters<br />
<code class="literal">lowerroman </code> lower case roman numerals<br />
<code class="literal">upperalpha </code> upper case letters<br />
<code class="literal">upperroman </code> upper case roman numerals<br />
</div><p>
The text for the first item follows the macro call. The start of the next item
is indicated by the <span class="bold"><strong>.next</strong></span> macro, and the end of the list by <span class="bold"><strong>.endlist</strong></span>.
For example:
</p><pre class="literallayout">
.olist lowerroman
This is the first item.
.next
This is the next item.
.endlist
</pre><p>
There may be more than one paragraph in an item.
</p></div><div class="section" title="4.9 Variable lists"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID37">4.9 Variable lists</a></h3></div></div></div><p>A variable list is one in which each entry is composed of a set of one or more
terms and an associated description. Typically, the terms are printed in a
style that makes them stand out, and the description is indented underneath.
The start of a variable list is indicated by the <span class="bold"><strong>.vlist</strong></span> macro, which has
one optional argument. If present, it defines a title for the list.
</p><p>
Each entry is defined by a <span class="bold"><strong>.vitem</strong></span> macro, whose arguments are the terms.
This is followed by the body of the entry. The list is terminated by the
<span class="bold"><strong>.endlist</strong></span> macro. For example:
</p><pre class="literallayout">
.vlist "Font filename extensions"
.vitem "TTF"
TrueType fonts.
.vitem "PFA" "PFB"
PostScript fonts.
.endlist
</pre><p>
As for the other lists, there may be more than one paragraph in an item.
</p></div><div class="section" title="4.10 Nested lists"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID38">4.10 Nested lists</a></h3></div></div></div><p>Lists may be nested as required. Some DocBook processors automatically choose
different bullets for nested itemized lists, but others do not. The
<span class="bold"><strong>.endlist</strong></span> macro has no useful arguments. Any text that follows it is
treated as a comment. This can provide an annotation facility that may make the
input easier to understand when lists are nested.
</p></div><div class="section" title="4.11 Displayed text"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID39">4.11 Displayed text</a></h3></div></div></div><p>In displayed text each non-directive input line generates one output line. The
<code class="literal"><literallayout></code> DocBook element is used to achieve this. Two kinds of
displayed text are supported by the standard macros. They differ in their
handling of the text itself.
</p><p>
The macro <span class="bold"><strong>.display</strong></span> is followed by lines that are processed in the same way
as normal paragraphs: flags are interpreted, and so there may be font changes
and so on. The lines are processed in literal layout mode. For example:
</p><pre class="literallayout">
.display
&`-o`& set output destination
&`-S`& set library path
.endd
</pre><p>
The output is as follows:
</p><div class="literallayout">
<code class="literal">-o</code> set output destination<br />
<code class="literal">-S</code> set library path<br />
</div><p>
The macro <span class="bold"><strong>.code</strong></span> is followed lines that are not processed in any way, except
to turn ampersands and angle brackets into XML entities. The lines are
processed in literal text mode. In addition, <code class="literal">class="monospaced"</code> is added to
the <code class="literal"><literallayout></code> element, so that the lines are displayed in a
monospaced font. For example:
</p><pre class="literallayout">
.code
z = sqrt(x*x + y*y);
.endd
</pre><p>
As the examples illustrate, both kinds of display are terminated by the
<span class="bold"><strong>.endd</strong></span> macro.
</p></div><div class="section" title="4.12 Block quotes"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID40">4.12 Block quotes</a></h3></div></div></div><p>The macro pair <span class="bold"><strong>.blockquote</strong></span> and <span class="bold"><strong>.endblockquote</strong></span> are used to wrap the
lines between them in a <code class="literal"><blockquote></code> element.
</p></div><div class="section" title="4.13 Revision markings"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="SECTrevmacs">4.13 Revision markings</a></h3></div></div></div><p>Two macros are provided to simplify setting and unsetting the <span class="quote">“<span class="quote">changed</span>”</span>
revision marking (see section <a class="xref" href="#SECTrevision" title="3.16 The .revision directive">3.16</a>). When the revised text is
substantial (for example, a complete paragraph, table, display, or section), it
can be placed between <span class="bold"><strong>.new</strong></span> and <span class="bold"><strong>.wen</strong></span>, as in this example:
</p><pre class="literallayout">
This paragraph is not flagged as changed.
.new
This is a changed paragraph that contains a display:
.display
whatever
.endd
This is the next paragraph.
.wen
Here is the next, unmarked, paragraph.
</pre><p>
When called like this, without an argument, in ordinary text, <span class="bold"><strong>.new</strong></span>
terminates the current paragraph, and <span class="bold"><strong>.wen</strong></span> always does so. Therefore, even
though there are no blank lines before <span class="bold"><strong>.new</strong></span> or <span class="bold"><strong>.wen</strong></span> above, the revised
text will end up in a paragraph of its own. (You can, of course, put in blank
lines if you wish.)
</p><p>
If want to indicate that just a few words inside a paragraph are revised, you
can call the <span class="bold"><strong>new</strong></span> macro with an argument. The macro can be called either as
a directive or inline:
</p><pre class="literallayout">
This is a paragraph that has
.new "a few marked words"
within it. Here are &new(some more) marked words.
</pre><p>
The effect of this is to generate a <code class="literal"><phrase></code> XML element with the
<code class="literal">revisionflag</code> attribute set. The <span class="bold"><strong>.wen</strong></span> macro is not used in this case.
</p><p>
You can use the <span class="bold"><strong>.new</strong></span>/<span class="bold"><strong>.wen</strong></span> macro pair to generate a <code class="literal"><phrase></code> element
inside a section of displayed text. For example:
</p><pre class="literallayout">
.display
This line is not flagged as changed.
.new
This line is flagged as changed.
.wen
This line is not flagged as changed.
.endd
</pre><p>
This usage works with both <span class="bold"><strong>.display</strong></span> and <span class="bold"><strong>.code</strong></span>. Within a <span class="bold"><strong>.display</strong></span>
section you can also call <span class="bold"><strong>.new</strong></span> with an argument, either as a directive or
inline. This does not work for <span class="bold"><strong>.code</strong></span> because its lines are processed in
literal text mode.
</p><p>
If you want to add revision indications to part of a table, you must use an
inline call of <span class="bold"><strong>new</strong></span> within an argument of the <span class="bold"><strong>.row</strong></span> macro (see below).
This is the only usage that works in this case.
</p></div><div class="section" title="4.14 Informal tables"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID42">4.14 Informal tables</a></h3></div></div></div><p>The <span class="bold"><strong>.itable</strong></span> macro starts an informal (untitled) table with some basic
parameterization. If you are working on a large document that has many tables
with the same parameters, the best approach is to define your own table macros,
possibly calling the standard one with specific arguments.
</p><p>
The <span class="bold"><strong>.itable</strong></span> macro has four basic arguments:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
The frame requirement for the table, which may be one of the words <span class="quote">“<span class="quote">all</span>”</span>,
<span class="quote">“<span class="quote">bottom</span>”</span>, <span class="quote">“<span class="quote">none</span>”</span> (the default), <span class="quote">“<span class="quote">sides</span>”</span>, <span class="quote">“<span class="quote">top</span>”</span>, or <span class="quote">“<span class="quote">topbot</span>”</span>.
</p></li><li class="listitem"><p>
The <span class="quote">“<span class="quote">colsep</span>”</span> value for the table. The default is <span class="quote">“<span class="quote">0</span>”</span>, meaning no vertical
separator lines between columns. The value <span class="quote">“<span class="quote">1</span>”</span> requests vertical separator
lines.
</p></li><li class="listitem"><p>
The <span class="quote">“<span class="quote">rowsep</span>”</span> value for the table. The default is <span class="quote">“<span class="quote">0</span>”</span>, meaning no horizontal
lines between rows. The value <span class="quote">“<span class="quote">1</span>”</span> requests horizontal separator lines.
</p></li><li class="listitem"><p>
The number of columns.
</p></li></ol></div><p>
These arguments must be followed by two arguments for each column. The first
specifies the column width, and the second its aligmnent. A column width can be
specified as an absolute dimension such as 36pt or 2in, or as a proportional
measure, which has the form of a number followed by an asterisk. The two forms
can be mixed – see the DocBook specification for details.
</p><p>
Straightforward column alignments can be specified as <span class="quote">“<span class="quote">center</span>”</span>, <span class="quote">“<span class="quote">left</span>”</span>, or
<span class="quote">“<span class="quote">right</span>”</span>. DocBook also has some other possibilities, but sadly they do not
seem to include <span class="quote">“<span class="quote">centre</span>”</span>.
</p><p>
Each row of the table is specified using a <span class="bold"><strong>.row</strong></span> macro; the entries in
the row are the macros’s arguments. The table is terminated by <span class="bold"><strong>.endtable</strong></span>,
which has no arguments. For example:
</p><pre class="literallayout">
.itable all 1 1 2 1in left 2in center
.row "cell 11" "cell 12"
.row "cell 21" "cell 22"
.endtable
</pre><p>
This specifies a framed table, with both column and row separator lines. There
are two columns: the first is one inch wide and left aligned, and the second is
two inches wide and centred. There are two rows. The resulting table looks like
this:
</p><div class="informaltable"><table border="1"><colgroup><col width="1in" align="left" /><col width="2in" align="center" /></colgroup><tbody><tr><td align="left">cell 11</td><td align="center">cell 12</td></tr><tr><td align="left">cell 21</td><td align="center">cell 22</td></tr></tbody></table></div><p>
The <span class="bold"><strong>.row</strong></span> macro does not set the <code class="literal">revisionflag</code> attribute in the
<code class="literal"><entry></code> elements that it generates because this appears to be ignored by
all current XML processors. However, you can use an inline call of the <span class="bold"><strong>new</strong></span>
macro within an entry to generate a <code class="literal"><phrase></code> element with <code class="literal">revisionflag</code>
set.
</p></div><div class="section" title="4.15 Formal tables"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID43">4.15 Formal tables</a></h3></div></div></div><p>The <span class="bold"><strong>.table</strong></span> macro starts a formal table, that is, a table that has a title,
and which can be cross referenced. The first argument of this macro is the
table’s title; the second is an identifier for cross-referencing. If you are
not going to reference the table, an empty string must be supplied. From the
third argument onwards, the arguments are identical to the <span class="bold"><strong>.itable</strong></span> macro.
For example:
</p><pre class="literallayout">
.table "A title for the table" "" all 1 1 2 1in left 2in center
.row "cell 11" "cell 12"
.row "cell 21" "cell 22"
.endtable
</pre></div><div class="section" title="4.16 Figures and images"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID44">4.16 Figures and images</a></h3></div></div></div><p>A figure is enclosed between <span class="bold"><strong>.figure</strong></span> and <span class="bold"><strong>.endfigure</strong></span> macros. The first
argument of <span class="bold"><strong>.figure</strong></span> provides a title for the figure. The second is
optional; if present, it is a tag for references to the figure.
</p><p>
A figure normally contains an image. The <span class="bold"><strong>.image</strong></span> macro can be used in simple
cases. It generates a <code class="literal"><mediaobject></code> element containing an
<code class="literal"><imageobject></code>. The first argument is the name of the file containing the
image. The remaining arguments are optional; an empty string must be
supplied as a placeholder when one that is not required is followed by one that
is set.
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
The second argument specifies a scaling factor for the image, as a percentage.
Thus, a value of 50 reduces the image to half size.
</p></li><li class="listitem"><p>
The third argument specifies an alignment for the image. It must be one of
<code class="literal">left</code> (default), <code class="literal">right</code> or <code class="literal">center</code> (or even <code class="literal">centre</code> if the
DocBook processor you are using can handle it).
</p></li><li class="listitem"><p>
The fourth and fifth arguments specify the depth and width, respectively. How
these values are handled depends on the processing software.
</p></li></ul></div><p>
Here is an example of the input for a figure, with all the image options
defaulted:
</p><pre class="literallayout">
.figure "My figure's title" "FIGfirst"
.image figure01.eps
.endfigure
</pre><p>
Here is another example, where the figure is reduced to 80% and centred:
</p><pre class="literallayout">
.figure "A reduced figure"
.image figure02.eps 80 center
.endfigure
</pre></div><div class="section" title="4.17 Footnotes"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID45">4.17 Footnotes</a></h3></div></div></div><p>Footnotes can be specified between <span class="bold"><strong>.footnote</strong></span> and <span class="bold"><strong>.endnote</strong></span> macros.
Within a footnote there can be any kind of text item, including displays and
tables. When a footnote occurs in the middle of a paragraph, paired flags
must not straddle the footnote. This example is wrong:
</p><pre class="literallayout">
The &'quick
.footnote
That's really fast.
.endf
brown'& fox.
</pre><p>
The correct markup for this example is:
</p><pre class="literallayout">
The &'quick'&
.footnote
That's really fast.
.endf
&'brown'& fox.
</pre></div><div class="section" title="4.18 Indexes"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID46">4.18 Indexes</a></h3></div></div></div><p>The <span class="bold"><strong>.index</strong></span> macro generates <code class="literal"><indexterm></code> elements (index entries) in the
output. It takes one or two arguments. The first is the text for the primary
index term, and the second, if present, specifies a secondary index term. This
macro can be called either from a directive line, or inline. However, it is
mostly called as a directive, at the start of a relevant paragraph. For
example:
</p><pre class="literallayout">
.index goose "wild chase"
The chasing of wild geese...
</pre><p>
You can generate <span class="quote">“<span class="quote">see</span>”</span> and <span class="quote">“<span class="quote">see also</span>”</span> index entries by using <span class="bold"><strong>.index-see</strong></span>
and <span class="bold"><strong>.index-seealso</strong></span> instead of <span class="bold"><strong>.index</strong></span>. The first argument of these
macros is the text for the <span class="quote">“<span class="quote">see</span>”</span>. For example:
</p><pre class="literallayout">
.index-see "chase" "wild goose"
</pre><p>
This generates:
</p><pre class="literallayout">
<indexterm>
<primary>wild goose</primary>
<see>chase</see>
</indexterm>
</pre><p>
If you want to generate an index entry for a range of pages, you can use the
<span class="bold"><strong>.index-from</strong></span> and <span class="bold"><strong>.index-to</strong></span> macros. The first argument of each of them is
an ID that ties them together. The second and third arguments of
<span class="bold"><strong>.index-from</strong></span> are the primary and secondary index items. For example:
</p><pre class="literallayout">
.index-from "ID5" "indexes" "handling ranges"
... <lines of text> ...
.index-to "ID5"
</pre><p>
The <span class="bold"><strong>.makeindex</strong></span> macro should be called at the end of the document, at the
point where you want an index to be generated. It can have up to two
arguments. The first is the title for the index, for which the default is
<span class="quote">“<span class="quote">Index</span>”</span>. The second, if present, causes a <code class="literal">role=</code> attribute to be added to
the <code class="literal"><index></code> element that is generated. For this to be useful, you need to
generate <code class="literal"><indexterm></code> elements that have similar <code class="literal">role=</code> attributes. The
standard <span class="bold"><strong>index</strong></span> macro cannot do this. If you want to generate multiple
indexes using this mechanism, it is best to define your own macros for each
index type. For example:
</p><pre class="literallayout">
.macro cindex
&<indexterm role="concept">&
&<primary>&$1&</primary>&
.arg 2
&<secondary>&$2&</secondary>&
.endarg
&</indexterm>&
.endmacro
</pre><p>
This defines a <span class="bold"><strong>.cindex</strong></span> macro for the <span class="quote">“<span class="quote">concept</span>”</span> index. At the end of the
document you might have:
</p><pre class="literallayout">
.makeindex "Concept index" "concept"
.makeindex
</pre><p>
As long as the processing software can handle multiple indexes, this causes two
indexes to be generated. The first is entitled <span class="quote">“<span class="quote">Concept index</span>”</span>, and contains
only those index entries that were generated by the <span class="bold"><strong>.cindex</strong></span> macro. The
second contains all index entries.
</p></div></div></div></body></html>
|
