summaryrefslogtreecommitdiff
path: root/macros/generic/docbytex/docby-e.d
blob: 8a0026057518911aab8587e7cc7ccfeed2dc90fc (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
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
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637

%% DocBy.\TeX{} -- Making a Documentation Of Source Codes By TeX

\def\projectversion{\dbtversion}
\def\headtitle{DocBy.\TeX}

\showboxbreadth=1500 \showboxdepth=2  \hfuzz=4pt

\input docby.tex

\title DocBy.\TeX{} -- Making a Documentation Of Sources By \TeX{}

\author Petr Ol\v s\'ak

\centerline{\ulink[http://www.olsak.net/docbytex.html]%
                         {www.olsak.net/docbytex.html}}

\def\db{\dg\nb}
\def\du#1{\api{\nb#1}}
\let\quotehook=\langleactive
\def\insdef#1 {\ifirst{docby.tex}{def\nb#1 }{^^B\cbrace}{++}}
\def\inssdef#1 {\ifirst{docby.tex}{def\nb#1}{\empty}{+-}}
\bgroup
   \catcode`\[=1 \catcode`]=2 \catcode`\{=12 \catcode`\}=12
   \gdef\obrace[{] \gdef\cbrace[}]
\egroup
\def\indexhook{The control sequences marked by ($\succ$)
   are sequences at user level. Other control sequences are internal in 
   DocBy.\TeX. The bold page number points to the place where the
   sequence is defined and documented, other page numbers point 
   to occurrence of the sequence. The control sequences for users 
   have underlined pagenumber in the list of page numbers. This 
   means the page where the sequence is documented at user level.
   \medskip}
\def\nn#1 {\noactive{\nb#1}} \nn insert \nn undefined

\def\cnvbookmark#1{\lowercase{\lowercase{#1}}}
\def\bookmarkshook{\lo ìe \lo ¹s \lo èc \lo ør \lo ¾z \lo ýy
   \lo áa \lo íi \lo ée \lo úu \lo ùu \lo óo \lo òn }
\def\lo #1#2{\lccode`#1=`#2}

\dotoc \bookmarks

\sec Preface
%%%%%%%%%

DocBy.\TeX{} gives you a possibility to creating a documentation of
source codes by \TeX{}. The source codes can be i C language or
whatever other computer language.

On the contrast of Knuth's ``literal programming'' this tool does not
use any preprocessors for doing filters of information for human and
for computer which is stored in single source file. I suppose that
programmers prefer to write and tune the program in computer language
before they start to write the documentation. It would be fine to
write the documentation after that and without modifying of the source
code of the working program. Modern systems gives possibility to open
more windows with more than one text editors: you can see the source
code in one editor and write the documentation of it in second.
Now, there is no need to merge both information (for computer and
for human being) to single file.

The first part of this document (\cite[uziv]) describes the
\docbytex{} at user level. The next part documents the implicit macros
implemented in \docbytex{}, which are supposed that experienced user
will want to change them in order to realize special wishes.
The next section~\cite[design] includes the documentation of
design-like macros. User can change them to create a better look of
his/her document. The last section~\cite[implementace] describes all
macros of \docbytex{} at implementation level in detail.

This document is created by \docbytex{} itself, it means that it can
serve as an example of \docbytex{} usage.


\sec [uziv] For Users
%%%%%%%%%%%%%%%%%%%%%

\subsec [cleneni] File Types
%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The \docbytex{} is proposed as a tool for making documentation of C
language. That is a reason why the next example is a documentation of
the hypothetical program written in this language. If you needs to
document another computer language, you can change some macros
(see the section~\cite[zmeny]).

Wee suppose that the source code is separated into
``modules''. Each module is intended to one special problem which is solved
by programmer. Each module has its own name ("foo" for example) and it is
written in files "foo.h" and "foo.c". These files are compiled into
"foo.o". All modules are linked at the end of compilation into the
executable program.

If we want to document these source files, we create new file with
".d" extension for each module, for example "foo.d". The documentation
of the module will be written in that file. Next we create the main
file (for example "program.tex") where all "*.d" files are included
by the command "\module"\du{module}. You can use commands
"\title" (name of the program), "\author"
(name of the author) and (for example) "\dotoc" for making
of table of contents, "\doindex" for generating of the
index. Of course, you can write first or general notes to the program 
in the main file too. The contents of the file "program.tex" can be:

\begtt
\input docby.tex
\title   The Program lup -- Documentation of The Source Codes

\author  Progr and Ammer

\dotoc  % the table of contents will be here

\sec The structure of the source files

The source files are in the three modules.
The auxiliary functions are defined in "base.c" and "base.h" files.
The window management are solved in "win.c" and "win.h" files.
The file "main.c" includes the function "main".
\module base
\module win
\module main
\doindex  % the index will be created here
\bye
\endtt

We decided to sort the documentation from ``simple'' functions to the
more complicated problems. Somebody can prefer another way from
"main" function first and the auxiliary functions at the end.
He/she can write:
\begtt
\module main
\module win
\module base
\doindex
\bye
\endtt

Both ways are possible because the documentation is hyperlinked
automatically. When the reader see the usage of some function,
he/she can simply go to the definition of this
function simply by one click. The reverse hyperlinks are included too.


\subsec [priklad] An Example of the Module Documentation
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Let we document the module "foo" in the file "foo.d".
This file is included by "module"~"foo" command. We can document any
part of source "foo.c" by words and combine this by a listing of parts
of source "foo.c" or "foo.h" by command "\ins"~"c <keyword>"\du{ins} or
"\ins"~"h <keyword>". The part of the source code is declared usually by
"//: <keyword>" line. The example follows.

Suppose that the following text is written in the file "foo.d"
\begtt
The struct \dg [struct] mypair is used as a return value of
"my_special_function". There are two "float" values.
\ins c mypair

The \dg [struct mypair] my_special_function() has one parameter "p"
and returns double and triple of this parameter in "mypair" struct.
\ins c my_special_function
\endtt

The file "foo.c" has to include the comments 
"//: "{\tt mypair} and "//: "{\tt my\_special\_function}. 
These comments delimit the part of source code to be listed in
the documentation:

\begtt
#include <stdio.h>

//: mypair

struct mypair {
  float x, y;
};

//: my_special_function

struct my_special_function (float p)
{
  struct mypair return_pair;
  return_pair.x = 2*p; // double of p
  return_pair.y = 3*p; // triple of p
  return return_pair;
} 
\endtt

The result looks like that:

\bigskip

The struct \dg [struct] mypair is used as a return value of
"my_special_function". There are two "float" values.
\def\modulename{foo}
\ins c mypair

The \dg [struct mypair] my_special_function() has one parameter "p"
and returns double and triple of this parameter in "mypair" struct.
\ins c my_special_function


The first listed part of source code is started by 
"//: "{\tt mypair} and ended by firs occurrence of the "//:".
The second listed part is started by "//: "{\tt my\_special\_function}   
and ended at the end of file. These delimiters (and the neighbouring
empty lines) are not printed.

The order of the listed parts are independent of the order in source
file. We can first comment my special function and include its source
code. Afterward we can explain the structure mypair and show the
source code of this structure.

Notice that the numbers of lines are inserted exactly by the lines in
source code. It means that the missing line 
"#include "{\tt<stdio.h>} has number one and first printed line has
the number five.

The "//: <keyword>" delimiter and the closing delimiter "//:" 
can be at arbitrary place of the line, no essential at begin of line.
The lines with the delimiters are not printed.

Notice the command "\dg" in source of the documentation. The
documented word (separated by space) follows immediately. The optional
parameter in brackets is interpreted as ``type'' of the documented
word.  The documented word is printed in red color on the rectangle
and all occurrences of that word in the documentation is printed in
blue color and treated as hyperlink to the place where is the word
documented (red color). The occurrence of that word have to be written
between the quotes {\tt\char`\"...\char`\"} or it is placed in the
inserted source code. You need not do any marks in source code in
order to highlight the usage of the documented word. This is done
automatically.

If the documented word has the brackets "()" at the end, then it is the
function. These brackets are not printed in the current place, 
but they are printed in the footnotes and in the index.

The quotes {\tt\char`\"...\char`\"} are delimiters of ``parts of
listings inside paragraph''. This text is printed by typewriter font
and the occurrences of documented words are hyperlinked here.
All characters have printed here without re-interpretation, it means
this environment behaves like ``verbatim''.

The footnote includes a list of all documented words on the current page.
Each word is followed by list of pages here. These pages points to all
pages here the documented word occurs.

All documented words are automatically inserted to the alphabetical
index created by "\doindex" command.


\subsec What Version of \TeX{} for \docbytex{}?
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

In order to activate all features mentioned above we need to use
pdf\TeX{} extended by enc\TeX{}. The language of automatically 
generated words (such as Contents, Index) is selected by current
value of "\language" register when "\input docby.tex" is processed.
\docbytex{} writes on the terminal the ``modes'' information: 

\def\begtthook{\catcode`\!=0 \sfcode`.=1000 }
\begtt
This is DocBy.TeX, version !dbtversion, modes: enc+PDF+ENG
\endtt
\def\begtthook{}

\docbytex{} can work in the following modes:
"enc/NOenc", "PDF/DVI", "ENG/CS". 

The "enc"\api{enc} mode is activated if the enc\TeX{} is detected.
Otherwise (if enc\TeX{} is unavailable), \docbytex{} prints warning
and sets the "NOenc"\api{NOenc} mode: the occurrences of documented
words are not detected and hyperlinked. The index is much more poor,
because the pages with occurrences of the words are missing.
Only the places of documentation of the words are referred. 
It means that the enc\TeX{} extension is very important for \docbytex.
This extension is usually available in current \TeX{} distributions
and it is activated by "pdfcsplain" format. So the recommendation is: 
use "pdfcsplain" when you are using \docbytex.

The "PDF"\api{PDF} mode is activated if the pdf\TeX{} is
used. Otherwise \docbytex{} switches to the "DVI"\api{DVI} mode
and prints the warning message on the terminal. The colors and
hyperlinks are not working in "DVI" mode but the list of pages with
all occurrences of documented words is printed in index 
(if enc\TeX{} is activated).

If "\language=0" or "(pdf)csplain" isn't used 
then language mode is set to ENG (English words 
will be generated). Else this mode is set to CS (Czech words
will be generated). If you are using another language, you need
to redefine some macros, see section~\cite[nazvy].



\subsec Searching Words by Enc\TeX{}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The hyperlinked words are located by enc\TeX{} by ``hungry algorithm''.
It means that if there are two documented words "abc" and "abcde" then
the text "abcdefg" is divided to the hyperlinked part "abcde" (the blue
color is used) and to the normal part "fg" (black color). The hyperlinked
part points to the place of the documentation of the word "abcde".
On the other hand the text "abcdx" is divided to hyperlinked part 
"abc" and this part points to the documentation of the word "abc".

Enc\TeX{} is not able to work with regular expositions. It means that
there is no simple possibility to search only words bounded by spaces,
other white characters or by punctuation. Enc\TeX{} 
searches the word as a part of another word. 
This leads to unexpected situations: the
short word is documented but it is a part of longer undocumented words
used in source code. For example, you document the structure "turn"
but you don't need to hyperlink the part of the word "return".
In such case you can define the "return" word as a ``normal''
undocumented word by the command "\noactive{<word>}"\du{noactive}
(for example "\noactive{return}"). This command declares the "<word>"
as a searched word (for enc\TeX) but sets it as inactive.

Imagine that you document a word which is used in code in ``documented
meaning'' only if some text precedes this word and/or some text
followed the word. If the word is used with another prefix/postfix
then this is undocumented meaning of the word. You can use in such
case a declaration "\onlyactive{<before>}{<word>}{<post>}"\du{onlyactive}.  
If you declare the word by "\dg <word>" (or by similar manner, see
section~\cite[ddsl]), then the word is hyperlinked in source code
only if the text "<before>" precedes and the text "<post>" follows.
The text "<before>" and/or "<post>" itself stays inactive.
The parameters "<before>" or "<post>" can be empty (no both
simultaneously) and you can use more "\onlyactive" declarations of
single "<word>".

\docbytex{} activates the enc\TeX{} searching only inside the group
{\tt\char`\"...\char`\"} or in listings of source codes.
It means that "\mubytein=1" (see enc\TeX{} documentation) is set only
in these situations. We recommend to leave "\mubytein=0" outside these
environment. If you set "\mubytein=1" (for example because of UTF-8
encoding) for the whole document then you do it on your own risk. 
The words inside your comments can be hyperlinked in such case.
 

\subsec The Index, Table of Contents, Footnotes and Bookmarks Generation
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The index and table of contents generation is fully done on macro
level of \docbytex{}. You needn't use any external program
(\docbytex{} itself does the alphabetical sorting). Just write
"\doindex"\du{doindex} or "\dotoc"\du{dotoc} on the desired place in
your document. Warning: the table of contents is not correctly
generated after first pass of \TeX. You have to run \TeX{} twice.
The pages may be changed after second pass because of table of
contents is inserted. Thus correct oputput is (may be) 
guaranteed after third pass of \TeX. The words ``may be'' are written
here due to the problem with footnotes mentioned in 
section~\cite[specfootnote].
The footnotes are changed in all three \TeX{} runs and this influences
the vertical typesetting retrospectively.
This is a reason why \docbytex{} performs the check of
consistency of references generated by current and previous 
\TeX{} pass. This check is done during the "\bye"\du{bye} 
macro is processing. Thus, it is usable to write "\bye" command
instead "\end" primitive command at the end of the document.
If the "\bye" macro is used then you can see the message 
``{\tt OK, all references are consistent}'' on the terminal or the warning
``{\tt page references are inconsistent, run me again}''.

You can do test of consistency in more detail by following script:

\begtt
#!/bin/bash
cp document.ref document.r0
pdfcsplain document
diff document.r0 document.ref
\endtt

\docbytex{} tries to fix the footnote processing after second pass in
order to document convergence. If you do big changes in the document
after that then \docbytex{} does change the numbers of lines for
footnotes and the Overfull/Underfull boxes may occur. We recommend
to remove the {\tt.ref} file and to run three passes of 
\docbytex{} again in such case.

\docbytex{} creates the structured bookmarks in PDF output 
if "\bookmarks"\du{bookmarks} command is used. The structured
bookmarks include names of parts, sections, subsections and documented words.
There is no matter where the command "\bookmarks" is written because
the information used in bookmarks is read from {\tt.ref} file. 
The problem about encoding of texts of bookmarks is discussed in
section~\cite[hooky].


\subsec [vkladani] Source Code Inserting
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Instead of simply command "\ins" you can use two more elaborate
commands "\ifirst"\du{ifirst} and "\inext"\du{inext} in order to
insert a part of source code in your documentation.

The "\ifirst{<file>}{<from>}{<to>}{<why>}" command inserts 
a part of the file "<file>" (full file name including extension)
from first line with the pattern "<from>" ending by line with the
pattern "<to>" or (if such line does not exists) to the end of file.
If the pattern "<from>" does not exists then the warning is printed on
the terminal.

The parameters of "\ifirst" command are first expanded and used
thereafter. The active tie character is expanded to the space.

The parameter "<why>" specifies if the line with "<from>" pattern
and/or the line with "<to>" pattern have to be printed or not.
This parameter has only two characters (plus and/or minus) with the
following meaning:

\begtt
why:  --   don't print first nor ending line
why:  +-   print first line but don't print ending line
why:  -+   don't print first line but print ending line
why:  ++   print both lines
\endtt

If the parameter "<from>" is empty (use "{}" notation) then the
printing starts on the begin of file. If the parameter "<to>" is
empty, only one line is printed. If "<to>=\end",\du{end} then
printing stops at the end of file. The ending line does not exists in
such case.

If the parameter "<from>" (or "<to>" respectively) 
has "\empty"\du{empty} value (use "{\empty}" notation) then 
the printing starts (or stops respectively) at the first empty line.
You can specify if this line is printed by "<why>" parameter.

The parameters "<from>" and "<to>" can be started by "^^B" character
(it means that the pattern have to be at the begin of the line) and/or
they can be ended by "^^E" character (it means that the pattern have
to be at the end of line). For example the parameter "^^Btext^^E"
means that "text" have to be on the line without nothing more.

The special \TeX{} characters (special categories) are not allowed 
in "<from>" and "<to>" parameters.  You have to use special control
sequences "\nb"\du{nb}, "\obrace"\du{obrace}, "\cbrace"\du{cbrace},
"\percent"\du{percent} and "\inchquote"\du{inchquote} instead of
"\", "{", "}", "%", {\tt\char`\"} characters. You can define aditional
sequences for another special \TeX{} characters, for example:

\begtt
{\catcode`\#=12 \gdef\hashmark{#}}
\endtt

If parameters "<from>" and "<to>" are the same or the "<from>" pattern
is on the same line as "<to>" pattern then only this line is printed
("<why>" have to be "++" or "+-"). If this condition is true but
"<why>" is "-+" or "--", then the printing of the code is stopped 
at next line with "<to>" pattern or at the end of the file.

The "\ifirst" command remembers the name of the included file and the
number of the last line which was read. Next time you can use the
command "\inext{<from>}{<to>}{<why>}". This command starts the
searching of the "<from>" pattern from the first line which wasn't
read by the previous "\ifirst" or "\inext" command. The parameters
of the "\inext" command have the same meaning as the parameters of the
"\ifirst" command. The parameter "<file>" is missing because the "<file>"
from the last "\ifirst" command is used.

The number of the last line read by "\ifirst" or "\inext" command is
stored in "\lineno"\du{lineno} register (no matter if this line was
printed or no). If the printing of code was stopped at the end of the
file then "\lineno" equals to the number of lines of the file.
You can do test of reaching of the end of file by "\ifeof\infile".

Examples:

\begtt
\ifirst {file.txt}{foo}{foo}{++}        % print the first line
                                        % with the text "foo"
\inext {foo}{foo}{++}                   % print the next line with 
                                        % the occurence of "foo"
\ifirst {file.c}{//: from}{//:}{--}     % the same as \ins command
\ifirst {file.h}{func(}{)}{++}          % print of function prototype
\ifirst {file.c}{func(}{^^B\cbrace}{++} % print of the code func 
\ifirst {file.txt}{}{\end}{++}          % print of the whole file
\ifirst {file.txt}{}{\empty}{+-}        % print of the first block
                                        % separated by empty line
\endtt

If the first line of the code to be printed is empty then it is not printed.
If the last line of the code to be printed is empty, it is not printed too.
This is an implicit behavior. But if you write
"\skippingfalse",\du{skippingfalse} then this behavior is switched off.
It means that the empty lines can occur at the begin or at the end of
listings. You can use "\skippingtrue"\du{skippingtrue} in order to
return to the implicit behavior.

The parameter "<from>" and "<to>" can have the prefix in the form
"\count=<number> ".\du{count} The value of the "<number> - 1" means how
many occurrences of the pattern have to be skipped and ignored during
searching. The "<number>"-th occurrence of the pattern is only
significant. For example "{\count=3 foo}" means that two occurrences
of "foo" have to be skipped and the third occurrence points to the
right place, where the printing of the code starts (or ends).

If the prefix "\count=<number> " is missing then \docbytex{} supposes
that "\count=1".

If the parameters "<from>" or "<to>" are empty and "\count=<number>" is
used then the space after "<number>" needn't be written and the
meaning is slightly different: 
If the "<from>" parameter is empty then "\count" means the number of
line from where the printing is started. If the parameter "<to>" is
empty then "\count" means the number of printed lines. The previous
sentences are true for "<why>=++" and for "\skippingfalse".
If the "<why>" parameter have different value and/or "\skipingtrue" 
then you must add/subtract one or two to/from the line 
number/number of lines. Examples:

\begtt
\skippingfalse
\ifirst {file.txt}{\count=20}{\count=10}{++} % print from line 20 to 29
\ifirst {file.txt}{}{\count=2 \empty}{+-} % print to the second empty line
\ifirst {file.txt}{\count=50}{\end}{++}  % print from 50th line to the end
\ifirst {file.tex}{\count=5 \nb section}{\count=2 \nb section}{+-}
                                  % print fifth section from TeX source
\endtt


\subsec [lineodkazy] References to Line Numbers
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The command "\cite[<label>]" expands to the number of the line in
source code.  How to declare the "<label>"? You can do it by "\ilabel
[<label>]{<text>}".\du{ilabel} command used before the "\ifirst" or
"\inext" command. You can write more "\ilabel" commands if you want to
declare more "<label>"s hidden in the following listing. The order of
"\ilabel" commands is irrelevant.

If the couple "<label>" -- "<text>" is declared by "\ilabel" then the
"\ifirst" or "\inext" command recognizes the occurrence of the "<text>" in
the listing. The line number of the first occurrence of "<text>" is
connected to the "<label>", it means the "\cite" expands to such line
number. 

The "<label>" have to be unambiguous in the whole document. The "\cite"
reference works forward and backward (after second pass of \TeX{} run).

The table of couples "<label>" -- "<text>" created by set of "\ilabel"
commands is local. It means that it cooperate only with the first
"\ifirst" or "\inext" command. These commands use this table and reset
it to the null state. You have to create this table before next
"\ifirst"/"\inext" command again. 

\docbytex{} does not write any warning if a "<text>" doesn't occur in
the listing. Of course, if you use the unconnected "<label>" by
"\cite" command then the warning is printed. 

The following example uses the known file "foo.c" mentioned in the
section~\cite[priklad].

\begtt
The declaration of my very special function is on the line~\cite[myfunct].

\ilabel [myfunct] {function (float}
\ilabel [returnx] {pair.x}
\ifirst {foo.c}{}{}{++}

There is very specific idea on the line~\cite[returnx] where the input
parameter is multiplied by two.
\endtt


\subsec Verbatim Environment by  {\tt\nb begtt}/{\tt\nb endtt}
        and by Quotes
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Verbatim displays of the code can be included to the documentation by
"\begtt"\du{begtt} and "\endtt"\du{endtt} pair of commands. The
material to be displayed is written between these commands. All lines
are inserted without changes, without interpretation of special \TeX{}
characters. The lines are not numbered here and the occurrences of
documented words are not hyperlinked automatically.

The following sections~\cite[hooky] and~\cite[begtt] discuss more
possibilities of this environment.

You can write verbatim text in paragraph between quotes
{\tt\char`\"...\char`\"}. This text is written by typewriter font and
documented words are hyperlinked automatically. We recommend to use
this environment for all parts of documented code which is
mentioned inside the paragraph. This is analogical to math environment
separated by "$...$".


\subsec [ddsl] The Declaration of the Documented Word
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

You can use commands "\dg",\du{dg}
"\dgn",\du{dgn} "\dgh",\du{dgh} "\dl",\du{dl} "\dln"\du{dln} 
or "\dlh"\du{dlh} in order to declare the documented word. The
semantic of these commands is explained below. The syntax of these
commands are slightly special. The purpose is to minimize the work of
the writer, so the braces ("{}") are not used, parameters are separated
by space for instance.  All these commands have the same syntax
thus the example below uses only "\dg" command.

The possibilities of the syntax follows:

\def\begtthook{\langleactive \mubytein=1}
\begtt
\dg <word>            % <word> separed by space
\dg [<text>] <word>    % optional paremeter <text>
\dg [<text>]<word>     % the space between [<text>] add <word> is optional
\dg <word>()          % <word> with "()" separed by space
\dg [<text>]<word>()   % a combination of previous syntax
\dg <word>,           % <word> separed by comma
\dg [<text>] <word>,   % a combination of previous syntax
\dg <word>(),         % <word> with "()" separed by comma
\dg [<text>]<word>(),  % a combination of previous syntax
\dg <word>.           % <word> separed by period
etc...
\endtt
\def\begtthook{}

In general: The optional "[" can follow after "\dg" command. The
"<text>" separated by "]" is read in such case and subsequent optional
space is moved to the end of the "<text>". It means that
"\dg"~"[text] word" is the same as "\dg"~"[text ]word".
Next, the "<word>" is read. The "<word>" parameter cannot
include the space, comma, period, colon and semicolon because these
characters can be separator of the "<word>". These punctuation
characters are not part of the "<word>" but they are printed.
It means that "\dg word:" prints "word": to the output and sets 
the "word" as a documented word. If the scanned "<word>" ends by
brackets "()" then these brackets are removed from "<word>" parameter,
they are not printed in the current place but they are printed in
footnotes and in the index.

Attention: the space have to be written after comma, period, colon or
semicolon separator. If the space does follow immediately then the
scanning process works only if the text between comma-like separator 
and space does not contain active characters ({\tt\char`\"...\char`\"}
for example). If the first character after space is {\tt\char`\`}
(backward quote) then the space and this quote is not printed.

Examples:  "\dg"~"<word> `~<next text without line breaking>"
or: "\dg"~"<word> `"{\tt\char`\"...\char`\"}. 

The commands "\dgh", "\dgn", "\dln", "\dlh" with space as a separator
doesn't print this separator because they usually print nothing
(see below).

Semantic: The "<word>" parameter is documented word. If this "<word>"
occurs on the other place in the document between
{\tt\char`\"...\char`\"} or in code listing then it is hyperlinked
automatically (blue color). The documented word is highlighted by red
color in the place where the "\dg" command is used and the optional 
"<text>" or "()" does not printed. 
This is the destination of all blue hyperlinks. The "<word>" is printed in
footnote of the current page too including the optional "<text>" in
and/or including the optional "()". The list of pages where
the word is used is printed here too. The same is printed in the
index. The index is sorted alphabetically by the "<word>", not by the
optional "<text>". 

The "<word>" declared by "\dg" is declared globally. This place is a
reference point for the whole document.

The "\dgh" works like "\dg" but the word is not printed in the place
of "\dgh" (mnemonic: "\dg" hidden). But this place is still the
destination of hyperlinks and the word occurs in the footnote and in
the index.

The "\dgn" command (mnemonic: "\dg" next) 
saves its parameters but prints nothing.
The first occurrence of the "<word>" in the next listing will 
be treated as the "\dg" is written here.

The "\dl" declares "<word>" locally. If the short name "<word>" is
used in the same name space then it is hyperlinked and pointed to the
place where "\dl" is used. The name space is changed by "\module"
command. It means that "<word>" is used locally in the module.
The word declared by "\dl" lives in two variants: short name ``"<word>"''
and long name (depends on the current name space, typically
``"<word>./<modulename>"''). The long name is accessible in the whole
document. 

The section~\cite[jmenneprostory] explains the name spaces in more detail

Each word can be declared at most once in the document else the error
is printed by \docbytex{} on the terminal. In case of "\dl" the short
name is irrelevant but the long name have to be unambiguous.

The "\dlh" command is "\dl" hidden and the "\dln" means "\dl" next.
They are similar as "\dgh" and "\dgn".

If somebody hate this complicated parameter scanning then he/she can
use internal commands with three parameters in braces:
"\iidg",\du{iidg} 
"\iidgh",\du{iidgh} "\iidgn",\du{iidgn} 
"\iidl",\du{iidl} "\iidlh",\du{iidlh} "\iidln".\du{iidln}
The usage of the parameters is: "\iidg{<text>}{<word>}{<brackets>}".
Of course, you can do more by these commands: you can declare "<word>"
with spaces or another delimiters, you can write something different
than ``"()"'' as "<brackets>" parameter.


\subsec [jmenneprostory] Namespaces
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The namespace is a rule by which the short name of documented 
word is transformed to long name when "\dl" is used. You can set the
namespace by the command "\namespace"\du{namespace}.
If the command "\dl<word>" is used inside the
"\namespace" "{<pre-text>#1<post-text>}...\endnamespace".\du{endnamespace} 
environment then the short name is "<word>" and the long name is 
"<pre-text><word><post-text>".
All occurrences of "<word>" are transformed to the long name inside the
namespace environment. Outside of this environment the occurrence of
short name "<word>" is treated as no "\dl" command is used.
For example each word declared as "\dl<word>" inside
"\namespace"~"{#1//uff}...\endnamespace" environment is transformed to
the long name ``"<word>//uff"'' and the occurrences of "<word>" inside
this environment is hyperlinked and pointed to the place where
"\dl<word>" is used. Outside of this environment only sequences
"<word>//uff" are hyperlinked.

The namespace is undefined out of "\namespace...\endnamespace"
environment thus the "\dl" command cannot be used here.
The "\module" command declares namespace "#1./<modulename>"
thus you can use "\dl" command for local functions and variables
used in current module.

The long names are printed in the footnotes and in the index.
The index is sorted by the long names alphabetically. The table of
contents uses short names.

An example about namespaces follows:

\begtt
\namespace {ju::#1}   %% namespace "ju" is set
The word \dl aha is declared here.
The word "aha" is hyperlinked to the place of its declaration.
The word "ju::aha" is hyperlinked too.
\endnamespace
\namespace {wow::#1} %% namespace "wow" is set
The word \dl aha is declared here again.
The word "aha" points to the declaration inside "wow".
\endnamespace         %% namespace off
The word "aha" is inactive here but the words
"ju::aha" and "wow::aha" points to the right places.
\endtt

The "\namespace...\endnamespace" environments can be nested. The inner
environment have to have another namespace than the outside
environment. These environments work globally independent of the 
"\bgroup" and "\egroup". The "\endnamespace" command used outside of all
namespace environments does nothing. You needn't to close these
environments before "\bye" command. 


\subsec The Application Level of the Documentation
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

You can write the documentation to users of your code. For example the
rules of the usage of functions are documented here (API) without codes
of these functions. Suppose that you want to document the ``inside
behavior'' of these functions by presenting their codes in the same
document. The documented "<word>" (a function name) can point to two
different places in your documentation in such case: API documentation
and CODE documentation.

The place with the function code (detail documentation) is located by
"\dg" command (or similar). The second place where the word is
documented only for users without code can be declared by
"\api{<word>}"\du{api}. This command inserts the invisible mark only,
the destination of links. The table of contents mentions the word
and points to this place. The list of pages with the occurrences of the
word (in the index and in footnotes) contains one underlined
page number. This is the page where "\api" command is used.
Of course, the "\api{<word>}" command is not sufficient to including
the word to the index. You need use the "\dg" command (in another 
place of the document) too.

The word declared by "\api" command are printed in the index with the
"\apitext"\du{apitext} prefix. The implicit value of "\apitext" macro
is the special right arrow. You can see it in the index and in the
table of contents in this document. The "\api{\nb api}" is used here
but the code of "\api" macro is documented in section~\cite[reference].

You can reference the place marked by "\api{<word>}" by
"\cite[+<word>]". This macro expands to the page number where the
"\api{<word>}" is used. For example the "\cite[+\nb api]" expands to
\cite[+\nb api] in this document.

If there exist the API destination declared by "\api" command then
the red word printed in the "\dg" place is hyperlinked and it points
to the API destination. Typically, the occurrence of this word is
hyperlinked here with the "\dg" place as a destination. It means we have
these two destinations cross hyperlinked.


\subsec [kapsec] Title, Parts, Sections, Subsections
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Sections starts by "\sec"~"<Section Name>\par"\du{sec} command.
Each section can include subsections started by the command
"\subsec"~"<Subsection Name>\par"\du{subsec}.
Of course, the "\par" separator can be replaced by empty line
(see the example in section~\cite[cleneni]).
Sections and subsections are numbered automatically.

One or more sections can form a ``part'' which is started by
"\part"~"<Part Name>\par"\du{part} command. Parts are labeled by
letters A, B, C,~\dots\ and they are printed more noticeable in table
of contents than sections. The "\part" command does not reset the
section numbering. It means that sections are numbered from one in
the whole document, no matter if the document is divided into parts.

The "\module <modulename> " command creates a new section
"Module <modulename>", creates namespace and includes the
"<modulename>.d" file. You can change this default behavior,
see sections~\cite[nazvy] and~\cite[module].

The "\title<Name>\par"\du{title} command prints the title of the
document by huge font in rectangle. If the
"\projectversion"\du{projectversion} macro is defined then it expands
to the text printed in the right upper corner of the rectangle
by small font. The word ``version'' precedes. If our project has no
version then you can define (for example):

\begtt
\def\projectversion{\the\day. \the\month. \the\year}
\endtt

The "\author<text>\par"\du{author} command centers the "<text>" 
i the line and prints it bold. The common meaning is name(s) of the 
author(s).

The headline is created at each page of the document with the
current section (from left) and title of the document (from right).
You can redefine the right headline by new definition of the
"\headtitle"\du{headtitle} macro.

The optional parameter "<label>" in square brackets can be used 
with "\sec" and "\subsec" commands. The parameters looks like:
"\sec"~"[<label>] <Section Name>\par". If the "<label>" parameter is
used then you can reference this place by "\cite[<label>]". This macro
prints the number of referenced (sub)section and acts like
hyperlink.

You can disable the transport of "<(Sub)Section Name>" into table of
contents by "\savetocfalse"\du{savetocfalse} used before "\sec" or
"\subsec" command. This section has no number. The macro
"\emptynumber"\du{emptynumber} expands instead of number printing. This 
macro is set to empty by default. The "\savetocfalse" command
influences only first "\sec" or "\subsec" command.


\subsec [krizodkaz] Hyperlinks, References
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


The destination of the hyperlink and/or reference have to be marked by
"<label>".  This can be done by optional parameter of the "\sec" or
"\subsec" command (see the section~\cite[kapsec]) or by the command
"\label[<label>]"\du{label} itself. You can make labels to line
numbers of inserted code too (see the section~\cite[lineodkazy]).  All
labels have to be unambiguous in whole document (independent of their
type).

The command "\pgref[<label>]"\du{pgref} expands to the number of the
page where the "<label>" is. The command
"\numref[<label>]"\du{numref} expands to the result which depends
on the type of the destination:

\begitems
\item * sections number if the destination is the section
\item * the pair "<secnumber>.<subsecnumber>" if the destination is
        the subsection.
\item * the number of the line if the destination is the line in the
        printed code
\item * empty if the destination is marked by "\label" command.
\enditems

Both macros "\pgref" and "\numref" expand to the texts mentioned above
without any more processing. It means that the printed text is not
treated as hyperlink.

You can use the command "\ilink"~"[<label>]{<text>}"\du{ilink}
in order to create the hyperlink in PDF mode.
This macro prints the "<text>" in blue color and it is treated as
hyperlink to the destination specified by "<label>".
For example the command "\cite[<label>]"\du{cite}
does the same as "\ilink[<label>]{\numref[<label>]}".
The real macro "\cite" executes a test if the "\numref[<label>]"
is empty and prints the "\pgref" in such case.

If the "<label>" is not declared then "\pgref{<label>}" and 
"\numref{<label>}" have no destination. The "\pgref" expands to
the text "-1000" and "\numref" is empty in such case. These macros
work on expand processor level thus no warning message is implemented
here. On the other hand the "\cite" command implements warnings.
See the code of "\cite" on the page~\cite[@\nb cite] for more detail.

The "\module"~"<modulename> " command creates the section with the
label ``"m:<modulename>"''. You can reference it by:

\begtt
\def\refmodule[#1]{\ilink[m:#1]{\tt#1}}
\endtt
%
The "\refmodule{<modulename>}" defined in the example above 
prints "<modulename>" and creates it as
hyperlink. For example "\refmodule[base]" prints the word ``base''
in blue typewriter font and creates it as the hyperlink to the begin of 
the section ``Module base'' if this section is crated by
"\module base " command. 

The "\dg", "\dgn" and "\dgh" commands perform the command "\label[@<word>]"
internally and the "\dl", "\dln" and "\dlh" perform the command
"\label[@<longname>]" internally. The "<longname>" is the long name of
the "<word>" in context of the current namespace.
For example, you can reference these places by 
"\link[@<word>]{The <word> documented on the page~\pgref[@<word>]}". 

The "\api{<word>}" command executes "\label[+<word>]" internally. It
means that you can reference this place by
"\ilink[+<word>]{API: <word>}" for instance. 

No more automatic numbering is processed by \docbytex{}. Only
numbers of sections, subsections and line numbers of the printed code.
If you want to create the numbers of figures, publications etc. Then
you have to write your own macros. You can use the
"\labeltext[<label>]{<text>}"\du{labeltext} command in such case.
This macro expands it parameters immediately and 
inserts invisible hyperlink destination into typeset material in
horizontal mode. Then macro "\numref{<label>}" expands to
"<text>" in the next pass of the \TeX{} run.
Example: we define the macro "\bib[label]" which inserts the
destination marked by the "<label>". The hyperlink with the number 
of the book can be created by "\cite[b:<label>]".

\begtt
\newcount\bibnum
\def\bib [#1]{\par\advance\bibnum by1 \indent
    \llap{[\the\bibnum] }\labeltext[b:#1]{[\the\bibnum]}\ignorespaces}
\endtt

\subsec Pictures Inserting
%%%%%%%%%%%%%%%%%%%%%%%%%%

The command "\ifig" "<width> <picname> "\du{ifig} inserts the picture
into your document. The picture have to be prepared in the file
"fig/<picname>.eps" (if \ilink[+DVI]{DVI mode} is used) and in the file
"fig/<picname>.pdf" (if \ilink[+PDF]{PDF mode} is used).
You can use another directory for pictures than "fig/" -- this name is
stored in the "\figdir"\du{figdir} macro and you can redefine it.
The "<width>" parameter is the ratio of the width of inserted picture
to the "\hsize" (unit-less). The inserted picture is placed to left
side with the paragraph indentation.
For example "\ifig 0.5 foo" inserts the picture prom "foo.pdf" 
(in PDF mode). The picture is scaled that its width is one half 
of the width of the printed text.

If you have the picture in "eps" format and you need to convert it to
"pdf" then you can use:

{\def\begtthook{\langleactive}
\begtt 
ps2pdf -dEPSCrop <picname>.eps
\endtt
\par}


\subsec Items
%%%%%%%%%%%%%

The list of items are surrounded by "\begitems"\du{begitems} and
"\enditems"\du{enditems} commands. The text is printed with one indent space
("\parindent") more in this environment. These environments can be
nested. Each item is started by "\item"~"<mark> ".\du{item}
The "<mark>" is printed left from the text. If the "<mark>" is the
star ("*") then it is changed to the bullet. You can write
"\item"~"\the\itemno) "\du{itemno} if you want to print numbered
items. The "\itemno" register counts from one in each
"\begitems"..."\enditems" environment.

The "\item" macro is redefined only inside "\begitems"..."\enditems"
environment. If you wish to use the plain\TeX{} macro "\item" then 
just don't use "\begitems" and "\enditems" commands.
 

\noactive{/*}\noactive{*/}\noactive{//} 
\setlinecomment{\percent} \noactive{\nb\percent} \noactive{\percent\cbrace}


\sec [zmeny] For Advanced Users
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The definitions of basis macros of \docbytex{} are mentioned in 
this section. The user can change these definitions if he need
different behavior of \docbytex{} than default one. For example, user
documents different language than C and he/she redefine the
"\docsuffix" macro or he/she redefine the code of "\module" and
"\ins" commands completely.


\subsec [nazvy] Internal Names
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The "\doindex" command creates new section with the name ``Index''.
The sections with names ``Table Of Contents'' or ``Module''
are inserted when table of contents is generated or "\module" command
is executed. The word ``version'' is prefixed when the number of
version is printed (if "\projectverion" is used). The text
">> PART" is inserted into bookmarks by "\part" command.
These texts are defined in the following macros:
\db titindex, \db tittoc, \db titmodule, \db titversion and \db opartname.

\ifirst {docby.tex}{Intern}{\empty}{--}

Note that different names are used by default when plain or csplain
format is processed. But user can redefine these macros independently
of the used format.


\subsec [hooky] Hooks
%%%%%%%%%%%%%%%%%%%%%

Some more elaborate macros ("\begtt", quotes, "\ifirst",
"\inext", "\doindex", "\dotoc") execute so called ``hook''
before processing of more code. These hooks are macros and they are
empty by default.

\ifirst {docby.tex}{begtthook}{\empty}{+-}

The \db begtthook macro is inserted after begin of the group and after all
catcodes are set by default before text inside the environment 
"\begtt...\endtt" is processed.
The \db quotehook macro is inserted after begin of the group and after
all cactodes are set by default before the text inside
"\begtt...\endtt" is processed.
The \db indexhook macro is inserted by "\doindex" command after new
section name is printed and before two column printing is activated.
You can insert the notice to index here (see the index of this document 
for example). 
The \db tochook macro is inserted by "\dotoc" command after new
section name is inserted and before first line of table of contents is
printed. 
The \db bookmarkshook macro is inserted inside the group at the begin
of bookmarks processing. You can set the different expansion of macros
used in bookmarks here. For example "\def\mylogo{MyProgram(R)}". 
Moreover, if you
say "\let\cnvbookmark=\lowercase" here then all characters is
converted to lower case in bookmarks. This is done by "\lowercase"
primitive thus the different meaning of special characters can be set
by "\lccode". I use it for removing of accents because accents in
bookmarks are interpreted by most PDF viewers wrongly.
The \db outputhook macro is inserted at the begin of the output
routine. We recommend to set chosen macros to "\relax" meaning in
order to they are not expanded in ".ref" file.

Examples:

\bgroup
\catcode`'13 \def'{\nb} \catcode`?=13 \def?{<} 
\def\begtthook{\langleactive\mubytein=1}
\begtt
\def\quotehook{\obeyspaces}   % normal spaces inside  "..." 
\def\quotehook{\langleactive} % ?text> is changed to <text>
\def\begtthook{\mubytein=1}   % auto-hyperlinks between 'begtt...'endtt
\def\begtthook{\setsmallprinting} % 'begtt...'endtt printed by small font
\def\begtthook{\catcode`\!=0} % !commands can be used in 'begtt...'endtt
\def\indexhook{The special index with such and such properties follows.}
\def\outputhook{\let\mylogo=\relax} % \mylogo is not expaded in *.ref
\endtt
\par
\egroup

\subsec [module] The Commands {\tt\nb module} and {\tt\nb ins}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The user documentation of these commands is in section~\cite[cleneni].
The  \db module "<file> " command reads the file with the name "<file>\docsuffix"
where \db docsuffix macro includes the suffix including the period.

\ilabel [linkincomment] {extension}
\insdef docsuffix  

The "\module" command inserts the name of the file (without the suffix)
into the auxiliary macro \db modulename. This macro is used by the
\db ins "<extension> <text> " command.

\inssdef ins

\subsec The Comments Turned to Green Color
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The  "\ifirst" and "\inext" commands recognise C comments in the form
"//..<eol>" and "/* .. */". These comments are printed in green color.
You can disable this behavior by "\noactive<string>" command.
You can set a new type of comments by \db setlinecomment "{<string>}" command.
These commands will be turned to green color from "<sting>" to end of line.
These commands work globally. For example

{\def\begtthook{\mubytein=1}
\begtt
\noactive{/*}\noactive{*/}\noactive{//} 
\setlinecomment{\percent} \noactive{\nb\percent}}
\endtt
\par}
\noindent
activates comments used in \TeX{} sources and PostScript language.

You can set the comments of the type "/*...*/"
by the command \db setlrcomment "{<left>}{<right>}".

If you are interested what these macros do internally then you can read
the following part of this section.


\inext {mubyte}{\empty}{+-}

These macros are empty in no-enc mode. When enc\TeX{} is detected, 
they write information to enc\TeX{} table by "\mubyte...\endmubyte" 
primitive commands. 

The \db linecomment a \db leftcomment commands are inserted by enc\TeX{}
before each occurrence of declared character sequence. These commands sets
the current color to green:

\inext {linecomment}{\empty}{+-}

On the other hand, the \db rightcomment command have to switch off the 
green color after the declared sequence is detected. Thus 
enc\TeX{} cancels the detected sequence and "\rightcomment"
command returns this sequence back. After the returned sequence 
the \db returntoBlack command set the current color to black.  

\inext {returntoBlack}{\empty}{+-}

Each line of listing is started by "\Black" switch. So, the green comments
to the end of line work. But the green comment can be interrupted by
the pair "\Blue...\Black" (see line~\cite[linkincomment] in previous section).
In this case the "\Black" command have the "\Green" meaning so it
returns to the green color. Next line is started with original "\Black"
switch because each line is printed inside its own \TeX{} group.

The comments of type "/* ... */" can affect more lines. So more lines
have to be green and we re-define "\Black" to "\Green" globally.
The lines starts with "\Black" command with "\Green" meaning in such
case. The "\returntoBlack" returns to the original "\Black" switch 
globally.

\docbytex{} initializes the comments by the rules of C language:

\inext {setlinecomment}{\empty}{+-}


\sec [design] For Designers
%%%%%%%%%%%%%%%%%%%%%%%%%%%

The documentation of macros which influence the look of the document
follows. You can redefine it in order to change the design of your
document. I mean that it is better to write simply and good documented
macros for one purpose than the complicated macros with many
parameters. You can simply use them or redefine them.

The main processing of docbytex{} is hidden in more complicated macros
described in section~\cite[implementace]. This differentiation of
levels gives possibility to the designers to concentrate to
design-like problems and not to drown in complicated recursive loops
etc. of internal macros.

There are two different version of design macros: for pdf\TeX{} mode
and for DVI mode (without pdf\TeX{}). This is the reason why you can
see that the listings of following macros are often started by the text 
"\ifx\pdfoutput\undefined".


\subsec Parameters and Auxiliary Macros
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The parameters \db hsize and \db vsize are unchanged in
\docbytex{}. User can set his/her own preferred values.
If they are unchanged by user then the default values from plain
(usable for letter format) or csplain (usable for A4) are used.

\docbytex{} sets new value for "\parindent" because we need more space
here for colourised squares in section names.

\ifirst {docby.tex}{parindent=}{\empty}{+-}

The \db nwidth dimen is used like ``narrowed "\hsize"'' for many
situations: the width of headline, footline and for title text.

\inext {nwidth}{\empty}{+-}

The glue at the bottom of each page is set by "\raggedbottom" macro
(defined in plain\TeX).
Moreover, the "\exhyphenpenalty=10000" is set in order to deny 
the linebreaking after dashes (like pp~11--13).

\inext {raggedbottom}{\empty}{+-}

The fonts 
\db bbf, \db bbbf, \db btt,
\db ttsmall, \db rmsmall, \db itsmall and \db partfont
are loaded here.

\inext {bbf=}{\empty}{+-}

The \db setsmallprinting macro sets the typewriter font and prepares
the \db ttstrut of appropriate size and activates the line printing
without vertical spaces between them by "\offinterlineskip" macro.
The "\parskip" value is set to "-1pt" in order to a small overlaps of
struts guarantee that no dashes-artifacts occur at background of
listings. The \db setnormalprinting is similar.

\inext {setsmallprinting}{\empty}{+-}

The design is projected only with the following colors:
\db Blue, \db Red, \db Brown, \db Green, \db Yellow a \db Black.
If you need other colors you can define more similar macros.

\inext {pdfoutput}{\empty}{+-}

All colors are defined by \db setcmykcolor macro which is empty in DVI
mode but~a proper "\special" is used in PDF\TeX{} mode. It means that
the commands "\Brown" etc. can be used in DVI mode too, but they do
nothing in that mode.
The \db oriBlack macro switches to black color and this macro is never changed.
On the other hand, the "\Black" macro can be redefined in special
environments and we need to return to real black color 
by "\oriBlack" macro at the end of such environment.

The \db rectangle "{<height>}{<depth>}{<width>}{<contents>}"
command creates a rectangle with specified dimensions and contents.
This rectangle is filled by yellow color in PDF mode. 
The same rectangle has only black outline in DVI mode.
Attention: the "<contents>" have to be prefixed by color switch
otherwise it is invisible in PDF version (yellow on yellow). 
The "\rectangle" macro returns back to black color after rectangle 
is created.

\inext {pdfoutput}{\empty}{+-}

The \docbytex{} logo is typeset by \db docbytex macro.

\inext {def\nb docbytex}{\empty}{+-}


\subsec Sections and Subsections
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The \db printsec "{<sec-title>}" and \db printsecbelow macros are
invoked from "\sec" macro. Their main task is to print the title of
the section. You can redefine these implicit macros. 
You can concern with design of section here and you need
not solve other problems (reference to the TOC, numbers, running heads
etc.) which are hidden in "\sec" macro.
 
The following rules are mandatory: The vertical mode have to be
initialized at the begin of the "\printsec" macro. Then you can insert
vertical space and then you can insert the text of title.
The "\makelinks" macro have to be inserted in the horizontal mode here. It
creates the aim of hyperlinks. The "\par" command have to be the last
command of your "\printsec" macro. No more vertical spaces can be
inserted here. The main "\sec" macro inserts another elements below
the text and then it call the second macro "\printsecbelow". The
vertical space below the text is inserted from this macro (probably
protected by "\noberak". The right order of elements in \TeX{}'s
vertical list is: ``box, (whatsit, mark, etc.), penalty, glue''. 
The objects mentioned in the brace here is inserted by "\sec" macro.
You can insert the ``box'' (by "\printsec" macro) and the
``penalty+glue'' (by "\printsecbelow" macro).

There are numerical registers "\secnum" and "\subsecnum" which store the
actual (sub)section number. Moreover you can use the "\ifsavetoc"
test. This is true if the title is printed in table of contents.
If it is false then you can use "\emptynumber" macro instead of
"\the\secnum". 

The "\seclabel" includes the "<label>" of processed section or it is
empty. You can use it for draft printing is you wish to see the labels
(in margins, for example). \docbytex{} doesn't implement this feature
by default.

\ifirst {docby.tex}{def\nb printsec }{\empty}{+-}

The \db printsubsec and \db printsubsecbelow macros does the same
things but subsection is printed. They are invoked by "\subsec" macro.

\inext {def\nb printsubsec }{\empty}{+-}

The \db printpart macro prints the title of part which is enumerated by
uppercase letters. The \db printpartbelow macro inserts the vertical
space below the part title.

\inext {def\nb printpart }{\empty}{+-}

The \db emptynumber is normally used if "\savetocfalse". It prints
nothing by default.

\inext {emptynumber}{\empty}{+-}


\subsec The Title, The Author
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The \db title "<title>\par" macro reads its parameter "<title>" by
auxiliary macro "\secparam" which ignores the possible space at the
end of this parameter. This parameter is stored into "\sectitle"
tokenlist and internal macro \db iititle is invoked. This macro works
in two different modes (DVI and PDF). The "<title>" is stored into
"\headtitle" macro (in both modes) only if the "\headtitle" is empty,
it means that it it not initialized by user. Then "\iititle"
suppresses the headline printing on the current page by the
"\nohedaline" command. 

\inext {def\nb title}{\empty}{+-}

The "\iititle" macro expands to normal "\centerline" in DVI mode.
On the other hand it creates the yellow rectangle of the width
"\nwidth" in PDF mode.

If the \db projectversion macro is undefined then its default value is
empty.

\inext {ifx\nb project}{\empty}{+-}

The \db author "<author>\par" does the same in both modes: prints the
"<author>" text on the center by boldface font.

\inssdef author


\subsec Headers and Footers
%%%%%%%%%%%%%%%%%%%%%%%%%%%

\docbytex{} doesn't change the output routine defined by plain\TeX.
It uses the standard plain\TeX{}'s macros "\headline" and "\footline" 
when the design of headers and footers need to be changed.

The default design doesn't do any difference between left page and
right page because we suppose that the document will be read on
monitor and may be printed without duplex.

The \db footline prints the page number on center with "\rectangle".

\inext {footline}{\empty}{+-}

The text of \db headline is changed during document is processed. It
includes only \db normalhead macro by default but if the "\noheadline"
command is used then "\headline" changes its content until one page is printed.

\ilabel[headlinebox] {headlinebox}
\inext {headline}{\empty}{+-}

The "\normalhead" macro stores page link by "\savepglink"
and creates the header by nested "\vbox/\hbox"es. The name of section
("\firstmark") is printed from the left side and the constant
"\headtitle" is printed on the right side.

The \db noheadline macro sets "\headline" to the temporary macro text 
which stores page link and does the change of "\headline" to its
default value. This setting is global because we are inside the output 
routine.

\inssdef noheadline

The \db headtile macro prints the text in right side of header. It is
empty by default but it is changed by "\title" command to the name of
the document. User can define its value manually.

\inext {headtitle}{\empty}{+-}

The auxiliary macro \db headlinebox prints the empty rectangle in DVI
mode and solid yellow rectangle in PDF mode. It is used on the 
line~\cite[headlinebox] for creating of square filled line in the header.

\inext {ifx\nb pdfoutput}{\empty}{+-}


\subsec Printing of the Hyperlink Destinations and Footnote References
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The hyperlink destination created by "\dg" or "\dl" macros are printed
highlighted in order to reader can easy find it. The printing is
processed by the macro \db printdg "{<text>}{<word>}{<brackets>}"
where the parameters are the same as in "\iidg" macro described 
in~\cite[ddsl] section.

Only one parameter "<word>" is printed by default. The "<word>" is
printed in rectangle in DVI mode or it is printed in red on solid
yellow rectangle in PDF mode.

\inext {ifx\nb pdfoutput}{\empty}{+-}

The red text is printed by auxiliary macro \db printdginside.
This macro prints only in red color if does not exist the "\api"
destination. On the other hand it prints in red by "\ilink" macro if
the "\api" destination does exist.

\inext {def\nb printdginside}{\empty}{+-}

One item below the footnote rule is printed by 
\db printfnote "{<text>}{<word>}{<brackets>}" macro (the parameters from
"\iidg" macro are here). The "<word>" is printed in red, other
information is printed in black.

The "\specfootnote"~"{<text>}" macro is used here. It sends the
"<text>" to the special footnote. The "\pgref[+<word>]" returns the
page number where the "\api" destination of the "<word>" is or it
returns $-1000$ if "\api" destination does not exist. This number is
stored in "\apinum" and if it is non-negative number then it is
printed as first page number underlined. The list of page numbers
where the "<word>" occurs is printed by 
"\listofpages{<word>}" macro. This macro ignores the number of page
where "\api" destination is. The empty list of page numbers is
detected by zero width of "\box0".

\inext {def\nb printfnote}{\empty}{+-}

\subsec The Index and Table of Contents Item
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The \db ptocline "{<number>}{<text>}{<pageno>}" command prints the
item about a section or a part in table of contents. The 
\db ptocsubline "{<number>}{<text>}{<pageno>}" does the same with the
item about subsection. There is no substantial differences between these commands
in \docbytex{}'s default design, only one "\indent" more in "\ptocsubline":

\inext {def\nb ptocline}{\empty}{+-}

The \db mydotfill command prints the dots in table of contents so they
are aligned.

The \db ptocentry "<type>{<word>}{<s-word>}" prints one item about
documented word in table of contents. If it is "\api" occurrence of
the "<word>" then "<type>=+" else "<type>=@". The "<s-word>" parameter
is empty but if the "<word>" is declared by "\dl" then "<s-word>"
includes a short variant of the word and "<word>" includes a long
variant of it. We use long variant for hyperlinking and short variant
for printing.

\inext {def\nb ptocentry}{\empty}{+-}

If someone want to print "<text>" before "<word>" or "<braces>" after
"<word>" then he can use a control sequence 
"\csname-<word>\endcsname". The example follows in the next macro
"\printindexentry".

The \db myldots command creates three dots, they are aligned wit
another dots in table of contents.

The \db printindexentry "{<word>}" macro prints an item of the
"<word>" in the index. It starts in vertical mode inside column,
prints the item and it have to switch to vertical mode back by "\par"
command. 

\inext {def\nb printindexentry}{\empty}{+-}

The \db separeright macro stores the "<text>" before the declared word
into the "\tmpa" and the "<braces>" into the "\tmpb". The control
sequence "\csname-<word>\endcsname" is prepared by the "\refdg" macro.
This sequence expands to "<text>\right<braces>".
The page number with the "\dg" (or "\dl") occurrence of the word 
is obtained by "\pgref[@<slovo>]" and the page number with "\api" 
occurrence is obtained by "\pgref[+<word>]". This page number 
is underlined if it does exist.


\subsec The Source Code Listing
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The "\ifirst" and "\inext" macros print the required part of source
code. They start with "\bgroup" and calls the \db printiabove
macro. Each line is printed by \db printiline "{<number>}{<text>}" 
macro. They finish by calling of \db printibelow macro and "\egroup"
command at the end. The designer can define these three macros. The
default design makes differences between DVI and PDF mode.

\ilabel [isnameprinted]  {raise8}
\ilabel [isnameprinted2] {pt \nb inputfilename}
\inext {ifx\nb pdfoutput}{\empty}{+-}

The line above with file name is printed in DVI mode by "\leaders"
primitive and \db specrule macro. The line below listing is simple.
In the PDF mode, we set "\setsmallprinting" at the start of listing
and insert a small vertical space.

The "\printline" macro sets the horizontal mode and strut is inserted
here (in DVI mode) followed by box with number of the line. The
interline penalty is 11 in the listing. In PDF mode, the solid 
yellow rectangle is printed by "\rlap". We need to print the filename
above the listing after the yellow rectangle of the first line is
printed. That is the reason why there is the test if first line of the
listing is printed by \db isnameprinted control sequence. It is
"\undefined" by default but if the filename is printed then
"\isnameprinted" is set to "\relax" (see lines~\cite[isnameprinted] 
and~\cite[isnameprinted2]). After the "\egroup" (inserted 
at the end of "\ifirst" or "\inext") the default value of "\isnameprinted"
is restored. This value is "\undefined".  


\subsec [begtt] The {\tt\nb begtt ... \nb endtt} Printing
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The "\begtt" establishes a new group and calls the \db printvabove
macro. Next, each printed line is processed by 
\db printvline "{<number>}{<text>}" macro. At the end, 
the \db printvbelow macro is invoked and the group is closed.

The implicit design doesn't print the numbers of lines. We draw only
lines above and below in DVI mode. Moreover, we draw yellow lines in
PDF mode and the yellow lines left and right in each line by "\rlap" macro. 

\inext {ifx\nb pdfoutput}{\empty}{+-} 


\subsec Pictures
%%%%%%%%%%%%%%%%

The pictures are inserted in order to align their left side with the
paragraph indent. The implicit design sets the "\parindent" to
sufficient big value that the result is quite good.
The width of the picture \db figwidth is calculated as
"\hsize" minus "\parindent".

\inext {newdimen\nb figwidth}{\empty}{+-}

DVI mode: The macro \db ifig "<width ratio> <filename> " inserts
the picture from "<filename>.eps" usig the {\tt epsf.tex} macro package.
PDF mode: The macro inserts the picture from "<filename>.pdf" by
pdf\TeX{} primitive commands "\pdfximage", "\pdfrefximage", "\pdflastximage".

\inext {ifx\nb pdfoutput}{\empty}{+-}

The \db figdir includes the directory with the pictures.

\subsec Items
%%%%%%%%%%%%%

The macros for items mentioned in text are simple. The \db begitems
macro starts the items environment and the \db enditems ends it.
The \db itemno register counts the number of the current item and the
\db dbtitem "<mark> " is the global variant of \db item macro.
The "\item" macro is the same as in plain\TeX{} by default but it
changes its behavior inside "\begitems"..."\enditems" environment.

\inext {newcount\nb itemno}{def\nb enditems}{++}


\sec [implementace] For \TeX{} Wizards
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The implementation of \docbytex{} is documented here. All internal
macros of \docbytex{} are listed and commented in this section.
May be, it is not so good idea to redefine these macros unless the
reader want to do his own \docbytex.


\subsec Auxiliary Macros
%%%%%%%%%%%%%%%%%%%%%%%%

The \db dbtwarning macro prints warning on the terminal:

\inext {def\nb dbtwarning}{\empty}{+-}

The macros \db defsec "{<text>}", \db edefsec "{<text>}" and \db undef "{<text>}"
define control sequence "\csname<text>\endcsname".

\inext {def\nb defsec}{\empty}{+-}

You can use the "\undef" macro in following way:

{\def\begtthook{\langleactive\mubytein=1}
\begtt
\undef{<text>}\iftrue <sequence is undefined> \else <sequence is defined> \fi
\endtt
\par}

You have to write "\iftrue" after "\undef{<text>}". There is a
practical reason of this concept: you can use "\undef" test nested
inside another "\if...\fi" conditional.

The \db nb macro expands to normal backslash of catcode 12. You can
use it if you need to search text with this character. The active
tabulator is defined as eight spaces and auxiliary macros
\db obrace, \db cbrace, \db percent, \db inchquote are defined here.

{\catcode`\%=12 \noactive{\nb %} \noactive{[%} }

\inext {catcode}{\empty}{+-}

The \db softinput macro inputs the specified file only if this file
exists. Else the warning is printed.

\inext {def\nb softinput}{\empty}{+-}

The \db setverb macro sets the cactodes of all special characters to
normal~(12).

\inext {def\nb setverb}{\empty}{+-}


\subsec Initialization
%%%%%%%%%%%%%%%%%%%%%%

\docbytex{} prints on the terminal:

\inext {This is DocBy}{\empty}{+-}

The \db dbtversion macro expands to the version of the \docbytex.
It is defined at the begin of the file {\tt docby.tex}. If new version
is released then this definition will be changed.

\inssdef dbtversion

%The csplain mode is detected by "\chyph" control sequence. It
%initializes the Czech hyphenation patterns.
%
%\inext {^^B\nb ifx\nb chyph\nb undefined \nb else}{\empty}{+-}

If "(pdf)csplain" is used then the UTF-8 input is activated by enc\TeX.
Unfortunately this isn't compatible with \docbytex{} which uses 
enc\TeX{} by different way. We need to deactivate the UTF-8 encoding
input. If you need to write something in different language than English
you need to use the 8bit encoding (ISO-8859-2 is usable for Czech 
when "(pdf)csplain" is used).

\inext {utf8off}{\empty}{+-}

The enc\TeX{} mode is detected and initialized:

\inext {encTeX ??}{\empty}{+-}

The \db enctextable "{<word>}{<macrobody>}" command inserts new
item into enc\TeX{} table with the key "<word>". If this key is found
by enc\TeX{} then it is removed from input stream and replaced by
the "\.<word>" macro which expands to "<macrobody>".
For example after "\dg"~"foo" the key "foo" is activated for 
enc\TeX by "\enctextable{foo}{\sword{foo}}" command. If the
"foo" is found in the input stream then it is replaced by
"\sword{foo}".  

The "\enctextable" doesn't store the key to the enc\TeX{} table if it
is included in the list of prohibited words stored in \db owordbuffer.
The words are separated by comma here. They are prohibited because of
"\onlyactive". The "\enctextable" defines only the "\.<word>" sequence
in such situation.

The \db noactive "{<text>}" macro inserts the "<text>" as a key in the
enc\TeX{} table. This key is not removed from input but the 
\db emptysec control sequence is inserted before it. Enc\TeX{} is not
able to remove the key from its table, it is only able to rewrite the
behavior of the transformation process if the key is found. If we need
to deactivate some key by "\noactive" then we rewrite its behavior.

All occurrences of documented words "<word>" is transformed to
\db sword "{<word>}" by enc\TeX{}. The hyperlink is created by this macro:

\inext {def\nb sword}{\empty}{+-}

The \db onlyactive "{<before>}{<word>}{<post>}" command inserts the
"<word>" into the list of prohibited words "\owordbuffer" (only if
this word isn't here already). Enc\TeX{} changes all occurrences of
"<before><word><post>" to "\oword{<before>}{<word>}{<post>}".
Moreover, the "<word>" is deactivated by "\noactive" (may be it was
activated when "\reffile" is read). The 
\db oword "{<before>}{<word>}{<post>}" command prints "<before>" by
normal font, then runs "\.<word>" if it is defined (else prints
"<word>" normally). Finally, it prints "<post>" by normal font.

\inext {def\nb onlyactive}{\empty}{+-}

The DVI/PDF mode is initialized here:

\inext {ifx\nb pdfoutput}{\empty}{+-}


\subsec The {\tt\nb ifirst}, {\tt\nb inext}, {\tt\nb ilabel} Macros
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The \db lineno register is the number of the line, \db ttlineno register 
is the number of the line in the "\begtt...\endtt" environment. We use
\db ifcontinue for loop controlling and \db ifskipping for setting
\db skippingfalse and \db skippingtrue.

\inext {newcount\nb lineno}{\empty}{+-}

The \db ifirst "{<filename>}{<from>}{<to>}{<why>}" command analyses
its parameter "<why>" by "\readiparamwhy" and tries to open the file
"<filename>" for reading by "\openin" primitive. If it is unsuccessful
then a warning is printed. Else the "<filename>" is stored to 
\db inputfilename macro and other parameters are analyzed by
"\scaniparam". The "<from>" resp. "<to>" parameter is stored to "\tmpa"
resp. "\tmpb" macro. The "<num>" parameter from "\count=<num>" is
stored to "\tmpA" and "\tmbB" macros. The command "\insinternal"
is invoked with expanded parameters "<from>" and "<to>". The expansion
is done via "\edef"ed macro "\act".

\insdef ifirst 

The \db inext "{<from>}{<to>}{<why>}" macro does the analogical work
as the "\ifirst". The only difference is that the "<filename>" is not
open by "\openin". We suppose that the file is opened already. We are
not sure that this is true and we check it by test of contents of the 
"\inputfilename" macro.

\insdef inext

When the parameters "<from>" and "<to>" are expanded then we want to
suppress all expansions of macros automatically inserted by
enc\TeX{}. This work is done by \db noswords macro.

\inssdef noswords

The \db readiparamwhy reads "+" or "-" characters from "<why>"
parameter and stores them to \db startline and \db stopline
control sequences.

\inssdef readiparamwhy

The \db scaniparam "<param>^^X<out><outnum>" reads "<param>" in
the form "\count=<num> <text>". It stores the "<text>" to the "<out>"
control sequence and "<num>" to the "<outnum>" control sequence.
The prefix "\count=<num>" is optional thus we need to do a little more
work to scan the parameters. This work is realized by auxiliary macros
\db scaniparamA, \db scaniparamB, \db scaniparamC. If the
prefix "\count=<num>" is missing then "<outnum>" is one.

\inssdef scaniparam

The main work (inserting of source code) is done by the macro \db
insinternal with parameters "{<from>}{<to>}".

\ilabel [prvniloop]       {preskakovani}
\ilabel [konec:prvniloop] {ifcontinue \nb repeat}
\ilabel [druhyloop]       {pretisk}
\ilabel [konec:druhyloop] {readnewline \nb repeat}
\ilabel [insinternal:end] {printibelow}
\insdef insinternal

The "\isinternal" macro has two main loops. First one (from 
line~\cite[prvniloop] to~\cite[konec:prvniloop]) reads the lines from
input source file (by the macro "\readnewline"). Each line is stored to
"\etext" macro. This loop finds the occurrence of the "<from>"
parameter and nothing is printed.

The second loop (lines from~\cite[druhyloop] to~\cite[konec:druhyloop])
reads lines from input source file and searches the occurrence of the
"<to>" parameter. The lines are printed by the "\printilineA" macro.

The preliminary work is done before first loop is started:
the catcode, fonts and "\mubytein" setting.
The \db testline macro is defined here with the "<from>" separator.
We will test the existence of "<from>" parameter by it.
More flexible definition of the "\testline" macro is used here because 
of special form of "<from>" parameter (see user documentation in 
the~\cite[vkladani]~section). The end of loop is controlled by 
the "\ifcontinue" condition. The \db nocontinue command runs
the "\continuefalse" but not always. If "\count>1", it means
"\tempnum>1", then the command only decreases the "\tempnum" by~1.

\inssdef nocontinue

The similar preliminary work is done before second loop. The
"\testline" macro is defined again with the "<to>" separator.
The searching process is similar as in the first loop.

The "\ifx+\startline" is a test if user want to print the first line.
The "\ifx+\stopline" is a test if user want to print the last line.

The "\ilabellist" macro tests the occurrence of labels declared by
the "\ilabel" command.

The macro \db returninsinternal "{<text>}{<possible fi>}{<ignore>}"
is more tricky. It is inserted when the end of the source file is
occurred. The macro leaves its loop by the "<ignore>" parameter which
is separated by the "\printibelow" text. Thus the part of the
"\insinternal" macro is skipped to the line~\cite[insinternal:end].
The inserted conditionals have to by closed properly: the "\fi"s are
inserted here from the second parameter. The first parameter "<text>"
includes the warning text if the warning have to be printed to the log
file. If the "<text>" parameter is empty, no warning is printed.

\insdef returninsinternal

The \db readnewline is simple:

\inssdef readnewline

We are working with the line of source file in two versions: noexpanded
line in the "\text" macro and expanded line in the "\etext" macro.
The "\noswords" macro before expanding of the line guarantees that the
"\etext" does not include control sequences created by enc\TeX
(we need not these sequences when we are testing the occurrence of
"<from>" or "<to>" parameter). The noexpanded "\text" version of the 
line (including the enc\TeX{}s sequences) is used when the line is 
printed.

The more intelligence is implemented in the \db printilineA macro:
the empty lines are printed with delay if the nonempty line follows.
We need it because the last empty line have to be unprinted if
"\skippingtrue". The \db lastline macro has three states: "\empty" (at
the begin), "\relax" (after the line is printed), "<line number>" (if
the previous line is empty).

\insdef printilineA

The \db ilabellist macro stores all declarations from 
\db ilabel "[<label>]{<text>}" commands. The empty value of
"\ilabellist" have to be set as default.

\insdef ilabellist

The "\ilabel" macro first expands its parameters (by the "\act" macro)
and calls the internal \db ilabelee macro. This macro adds the
following text to the "\ilabellist":

\def\begtthook{\langleactive\mubytein=1}
\begtt
\expandafter\testilabel\etext\end{<label>}{<text>}
\endtt

The \db testilabel "<line>\end{<label>}{<text>}" command
defines the temporary "\tmp" macro with the "<text>" separator in
order to test if the "<text>" is included in "<line>". If it is true
then the aim of the reference is registered by the "\labeltext" command.

\inext {testilabel}{\empty}{+-}
 
\def\begtthook{}

\subsec Commands {\tt\nb begtt}, {\tt\nb endtt}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The \db begtt and "\endtt" macros are described in ``\TeX{}book 
inside out'' (the book in Czech language) in pages~27--30.
The \db startverb macro reads the following text separated by
the word "\endtt". This text is divided into lines by
"^^M" character of catcode 12. The loop is started by
the \db runttloop macro and the text is separated into lines.
Each line is processed by the "\printvline" macro.
The \db endttloop is performed at the end of the loop. The final work
is done here (the "\printvbelow" macro and the end of the group) and
the next token is scanned by \db scannexttoken macro. If this token
isn't "\par" then the following text is prefixed by "\noindent".
It means that "\begtt"..."\endtt" is ``inside'' the paragraph.

\ifirst {docby.tex}{def\nb begtt }{\empty}{+-}

The number of line globally incremented in "\begtt"..."\endtt" 
is stored in "\ttlineno" register. You can set this
register to zero at each begin of section (for example).

\subsec [ns] The Namespaces
%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Each name space is connected to its own \db namespacemacro. This is a
macro with one parameter which is declared by "\namespace{<macro body>}".
The "\namespacemacro" is empty by default.

\ifirst {docby.tex}{def\nb namespacemacro}{\empty}{+-}

We need to set a label to each name space. The label is the text
expanded by "\namespacemacro{@!}" and the mark "<nslabel>" is used for
such label in this documentation. There is a little risk that the
"<nslabel>" is ambiguous but I hope that this situation will not occur.

Each name space have to know all local words declared in it in order
to the occurrence of this local word can be referenced to the "\dl"
declaration; the "\dl" declaration can be used after first occurrence
of such word. The enc\TeX{} tables have to be initialised with all 
local words at the start of the name space. The original state of
these tables have to be restored at the end of the name space. We
cannot wait to the "\dl" command but we need to use the "\reffile"
file. It means that the name spaces are inactive in the first \TeX{}'s
run.

The macro "\ns:<nslabel>" includes the list of all locally declared
words in the namespace "<nslabel>" after the "\reffile" file is
read. The list has the following format:

{\def\begtthook{\mubytein=1\langleactive}
\begtt
\locword{<word1>}\locword{<word2>}\locword{<word3>}...
\endtt
\par}

Because the enc\TeX{} table setting is global, we define all namespace
macros globally too. This is the reason why
"\namespace...\endnamespace" is independent of groups in \TeX.

The "\namespacemacro" is defined at the start of the \db namespace
command. The original value of the "\namespacemacro" is stored to
the "\no:<nslabel>" macro in order we are able to restore this value
at the end of the "\namespace...\endnamespace" environment.
Next we define the macro \db locword so that the enc\TeX{} table is
set after invoking of the "\ns:<nslabel>". The "\locword" macro stores
the original meanings of redefined control sequences first.

\inext {def\nb namespace }{^^B\cbrace}{++}

The \db endnamespace command redefines the "\locword" macro so that
the original meaning of redefined sequences are restored.
If the original meaning is ``undefined'' we need to store the "\nword"
to the enc\TeX{} table in order to there is no possibility to clear 
the item from enc\TeX{} table definitely.
The original value of the "\namespacemacro" is restored by the 
"\no:<nslabel>" macro.

\inext {def\nb endnamespace}{^^B\cbrace}{++}

These macros used the \db ewrite sequence which writes the text to the
"\reffile" with delay (in output routine) but the expansion is done
immediately. But the "\nb" control sequence is not expanded.

\inext {def\nb ewrite}{\empty}{+-}

Enc\TeX{} stores the control sequence "\.<word>" instead local
"<word>" at the start of each name space. The "\.<word>" macro expands
to "\lword{<word>}". If the local word occurs the \db lword works as
follows: 

\inext {def\nb lword}{\empty}{+-}

The \db genlongword "<tmp>{<word>}" command creates long version of
the "<word>" from short variant of it and stores this log version to
"<tmp>" macro. The occurrence of the "<word>" is presented by the
parameter of the "\ilink" command and by the long name (unambiguous)
written to the "\reffile". The short variant of the word is printed.

The reading of the "\reffile" is controlled by \db refns "{<nslabel>}"
macro. This control sequence is stored to the file at the begin of the
name space. The second control sequence \db refnsend "{<nslabel>}"
is stored at the end. The items of the type
"\refdg{<text>}{<long-word>}{<brackets>}{<short-word>}"
are stored between these control sequences. We read only the items
with the nonempty "<short-word>" parameter. These items are stored by
"\dl" command.

\inext {def\nb refns}{\empty}{+-}

The "\refns" macro remembers the previous "<nslabel>" which is stored
in \db currns. This value is stored to the "\o:<new nslabel>" and the
"\currns" is redefined as "<new nslabel>". The implicit value of the
"\ns:<nslabel>" is empty. The "\refdg" commands add information to the
"\ns:<nslabel>" buffer (see lines~\cite[ns1]--\cite[ns2] in 
section~\cite[reference]). Finally, the "\refnsend" command returns
the "\currns" macro to the original value before name space was started. 


\subsec The {\tt\nb dg} Command and Friends
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The macros \db dg, \db dl, \db dgn, \db dgh, \db dln, \db dlh
save its name to a "\tmpA" and then they scan parameters by
a \db dgpar. Finally they run the internal version for itself
"\csname ii\tmpA\endcsname".

\inext {def\nb dg}{\count=2 \empty}{+-}

The previous macros prepare the reading of optional parameter. The
main work is done by the \db dparam macro.

\ilabel [managebrackets] {managebrackets}
\ilabel [ii] {csname ii}
\inext {def\nb dparam}{\empty}{+-}


If there is a space after closed bracket "]" then the "#2" parameter
is empty (it is separated by space). The "\dparam" macro runs again in
such case (by \db nextdparam macro which scans the rest of parameters
of the "\dparam"). The space is inserted inside the braces before the
"\dparam" is run again. Now, we can separate the "#2" parameter (it
means the "<word>") to the part before the first comma or period or
colon or semicolon and to the second part with the rest. The first
part is stored to "\tmpa" and the second part (including the separator)
is stored to "\tmpb". This work is done by the macro \db varparam:

\inext {def\nb varparam}{\empty}{+-}

The macro "\varparam<separ>" defines the temporary macro
"\tmp#1<separ>#2 " which is run by "\tmp<word><separ> ". If the 
"#2" is empty then the explicitly written "<separ>" was used as 
separator and the "<word>" does not include the "<separ>". The "\tmpa"
still includes the "<word>" in such case. On the other hand, if the
"<word>" includes "<separ>" then we need to store the rest after the
"<separ>" to "\tmpb" including such "<separ>".  The "#2" parameter includes
"<rest><separ>". The desired work is done by the \db gobblelast macro
with the parameter "<contents of tmpb>\end<separ><rest><separ>". The
"#1" includes the "<rest>" and the new "\tmpb" is filled up by
"<separ><rest><old contents of tmpb>".


At the end of this work, we have the "<word>" in "\tmpa" but it can be
followed by "()". This problem is solved by \db managebrackets macro
which separates these braces if they exist. The braces are stored to 
\db printbrackets in such case.

\inext {def\nb managebrackets}{\empty}{+-}

The \db maybespace macro prints the space after the contents of
"\tmpb" only if the name of the macro used by the user has only two
letters ("\dg", "\dl") and the character "`" follows.

\inext {def\nb maybespace}{\empty}{+-}

The "\dparam" macro changes the original command "\dg*", "\dl*"
respectively to internal variant "\iidg*", "\iidl*"
respectively. This is done on the line~\cite[ii]. Parameters are
expanded before the internal macro is started. Now, we'll concentrate to
the internal macros.

The \db iidg macro inserts the "\sword" to the enc\TeX{} table
(this is redundant because the same work is done when "\reffile" is
read by "\refdg" macro). Next, the "\iidg" macro creates the aim of the
reference in the form "@<word>" and saves
"\refdg{<text>}{<word>}{<brackets>}{}" to the "\reffile".
The highlighted "<word>" is printed by the "\printdg" command and the
footnote is inserted by the "\printfnote" command.

\inext {def\nb iidg }{^^B\cbrace}{++}

The \db iidl 
creates the aim of the reference by "\label [@<long-word>]",
writes the information to the "\reffile" in the format
"\refdg{<text>}{<long-word>}{<brackets>}{<short-word>}" and
prints the "<short-word>" highlighted by "\printdg" command.
It stores nothing to the enc\TeX{} table.
Finally, it inserts the footnote by "\printfnote{<text>}{<long-word>}{<braces>}".

\inext {def\nb iidl }{^^B\cbrace}{++}

The \db iidgh a \db iidlh macros do the same work as the non-"h"
variants. The only difference is that they do not print the word.
The "\printdg" is redefined locally in order to do nothing.

\inext {def\nb iidgh}{\empty}{+-}

The \db iidgn command redefines the "\.<word>" macro which is inserted to
the text by enc\TeX. The result of the expansion will be
"\fword{<text>}{<word>}{<braces>}" instead of the common result
"\sword{<word>}".

\inext {def\nb iidgn}{\empty}{+-}

The tasks of the \db fword macro are: do "\iidgh", print the "<word>"
in red and return the "\.<word>" macro to the normal state.

\inext {def\nb fword}{\empty}{+-}

The \db iidln macro stores the current meaning of the "\.<word>" to
the new control sequence "\;<word>" and redefines the "\.<word>". The
result of the expansion is "\flword{<text>}{<word>}{<braces>}".

\inext {def\nb iidln}{\empty}{+-}


The tasks of the \db flword macro are: do "\iidlh", print "<word>" in
red, return the original meaning of the "\.<word>" (from the 
"\;<word>" storage). If the "\;<word>" is undefined we need to
inactivate the "\.<word>" macro by "\nword{<word>}" because there is
no possibility to remove the item from enc\TeX{} table.

\inext {def\nb flword}{\empty}{+-}


\subsec [specfootnote] The Special Footnotes
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The footnotes are placed beside each other. There are only words
which are declared on this page by "\dg". Because this concept is
visual incompatible with the ``normal'' footnotes, we deny them:

\inext {let\nb footnote=}{\empty}{+-}

Our special footnotes use the ``insert'' "\footins" declared in
plain\TeX{}. The problem is to estimate the vertical space of one
footnote when these footnotes are beside each other. The dirty trick
from the \TeX{}book (to insert the inserts by percent of the width) is
not used here because the pagebreaks didn't converge in the sequence
of \TeX{} runs. The second run gets the pagenumber lists in the
footnotes but they are not definite because of new pagebreaks. The new
pagebreaks influence new lists of pagenumbers in footnotes and the new
lists influences the new pagebreaks because the widths of
the footnotes are different from previous \TeX{} run. The oscillation
is very common in such case. 

I decided to work only with the average space of the footnotes common
for each of them. This coefficient is the number of the lines of the
footnotes divided by the number of the footnotes. Each footnote
inserts to the vertical list the space of the line hight (10pt)
multiplied by this coefficient. I need to set the "\count\footins"
only. 

In order to guarantee the convergence of this problem, we need to fix
the coefficient (mentioned above) after second \TeX{} run. If this
coefficient is changed in each \TeX{} run then the unconvergence is
very possible. The value of this coefficient after first \TeX{} run is
unusable because the lists of pagenumbers in footnotes are empty at
this state. The implicit coefficient is set to "\count\footins=200"
for first and second \TeX{} run (we suppose five footnotes on the one
line). 

The average coefficient (instead of the width of each footnote) can
produce a little overfull or underfull pages. We need to have the
resource for this situation in "\skip\footins" and we need to
use the vertical glue above and below the footnote rule.

\inext {skip\nb footins}{\empty}{+-}

The \db totalfoocount accumulates the number of the footnotes and the 
\db totalfoodim accumulates the total height of all lines with footnotes.

\inext {newcount\nb totalfoocount}{\empty}{+-}

The \db specfootnote "{<text>}" macro inserts  to the "\footins" one
"\hbox{<text>}" and advances "\totalfoocount" by one.

\inext {def\nb specfootnote}{\empty}{+-} 

I decided to keep the output routine of plain\TeX{} unchanged. It
means that the part of this routine which solves the
footnote printing was needed to change. The "\footnoterule" macro of
plain\TeX{} was redefined. The "\unvbox\footins" separator removes the
same text from the original output routine.

\inext {def\nb footnoterule}{\empty}{+-}

This macro decomposes the vertical list of inserts "\footins" and 
composes them again beside each other in horizontal box~4. The
raggedright parameters are set and the box 4 is unboxed in horizontal
mode ended by "\endgraf". This means that the footnotes are divided to
lines. The "\totalfoodim" is advanced here too.

The "\bye" macro (see the line~\cite[write]) writes the 
"\totalfoocount" and "\totalfoodim" to the "\reffile". The actual
average coefficient is added here too. This information is written
only if the "\indexbuffer" is not empty, it means that (at least) 
the second \TeX{} run is in progress.

This information is read by the 
\db refcoef "{<coef>}{<number>}{<height>}" macro
at the start of the next \TeX{} run. It sets the
average coefficient "\count\footins". The change from implicit value
200 to the new value is done only once. Next \TeX{} runs keep this
value unchanged. The auxiliary macro \db gobblerest removes the digits
after decimal point including the text~"pt".

\inext {def\nb refcoef}{\empty}{+-}

We need to suppress the expansion of some macros in output routine
which are presented in "\write" parameter. These macros are set to
"\relax" meaning in output routine. In order to the headline printing
is done correctly we need to expand "\makehedaline" before the setting
of these macros to relax and we need to store the result of
"\makeheadline" in a box.

\inext {\nb output=}{\empty}{+-}


\subsec [secsec] Section, Subsection, Part
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The \db secnum, \db subsecnum, \db sectitle and \db ifsavetoc
are declared here. "\savetoc" is true by default.

\ifirst {docby.tex}{newcount\nb secnum}{\empty}{+-}

There is an optional parameter "[<label>]" followed by optional (ignored) space 
when \db sec and \db subsec macros are used. The last token of "<title>" can be 
space too and we need to ignore it. This is reason what the macros are somewhat 
complicated. The name of the macro is stored to \db tmpA and the parameter 
scanning process is started by "\secparam".

\inext {def\nb sec}{\empty}{+-}

The \db secparam reads the optional "[<label>]". If it exists then it 
is stored to \db seclabel macro else "\seclabel" is empty. 
The \db secparamA macro ignores optional space after the "]".
The \db secparamB "<title>\par" macro reads "<title>". The unwanted 
space at the end of the "<title>" is removed by \db nolastspace macro which 
cooperates with the \db setparamC macro. This macro stores the "<title>" 
(without the last space) into "\sectitle" and executes "\iisec" or "\iisubsec".

\inext {def\nb secparam}{\empty}{+-}

The \db iisec macro sets the "\secnum" and "\subsecnum" values and defines
\db makelinks where the hyperlinks are prepared (used by "\printsec").
The "\printsec" macro prints the title of the section.
The information of the type 
"\reftocline"~"{<secnum>}{<title>}{<pagenumber>}"
is stored to "\reffile".
The command "\mark{<secnum> <title>}" is executed and the vertical space
is appended by "\printsecbelow".

\inext {def\nb iisec}{^^B\cbrace}{++}

The \db iisubsec macro is similar as "\iisec".

\inext {def\nb iisubsec}{^^B\cbrace}{++}

The "\part" macro uses the conversion of the \db partnum register to letters.
It is implemented as \db thepart macro.

\inext {newcount\nb partnum}{\empty}{+-}

The \db part macro is implemented by \db iipart and it is similar to "\iisec".

\inext {def\nb part}{\empty}{+-}

\subsec [reference] Links and References
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The hyperlinks are solved by \db savelink "[<label>]" and 
\db iilink "[<label>]{<text>}" macros. The "\savelink" stores the 
invisible destination into document raised to the height of
\db linkskip above baselineskip. The "\ilink" (i.e.\ internal link)
is documented in the \cite[krizodkaz] section. The "\savepglink"
saves the numerical destination (page number) which will be used by 
"\pglink" if a page is referred. 

\ifirst {docby.tex}{Odkazy, ref}{\empty}{--}

These macros have special implementation for DVI and PDF modes.
The blue color for links are declared in the "\ilink" macro.
You can change this feature by changing of this macro.

The internal labels for PDF links cannot include backslashes. 
That is the reason why the "\nb" (normal backslash) macro is redefined here.
We expect the unexpanded parameter of "\savelink" and "\ilink" macros. 

The \db savepglink macro (see above) is used by "\headline", this places 
the destination at every page. The \db pglink "<number>" macro reads the 
"<number>" (it is numerical register or number itself) and creates the link
to the page "<number>". The "<number>" is printed in blue color and it is 
clickable. The numerical register is scanned by "\afterassignment" followed by
\db dopglink.

The line "\reflabel"~"{<label>}{<text>}{<page>}"
is stored to "\jobname.ref" file by "\labeltext" macro.
This information is read by \db reflabel macro and stored in
"^^X<label>" and "^^Y<label>" control sequences. These sequences are used by
\db numref a \db pgref.
Note that if the "<text>" is empty (this is a case of documented words for example)
then the control sequence "^^X<label>" is not defined. This saves the 
\TeX{} memory for names of control sequences.

\inext {reflabel}{\empty}{+-}

The \db labeltext "[<label>]{<text>}" stores the desired information
as pronounced above. First, it creates PDF link by "\savelink" macro
and second, it stores data to ".ref" file. The 
\db writelabel "[<label>]{<text>}" us used for this purpose which expands to 
the asynchronous "\write" primitive (in order to save right value of the page number).
We need to expand the "<text>" parameter because "\the\secnum" (or similar data) 
is here. This is a reason why the parameters are switched (the
"<label>" parameter cannot be expanded) and the auxiliary macro
\db writelabelinternal "{<text>}{<label>}" is used. The first part, 
i.e.\ "\writelabel{<text>}" is expanded by "\edef".

\inext {labeltext}{\empty}{+-}

The \db label is defined simply as ``empty'' "\labeltext".

\inext {label}{\empty}{+-}

The \db cite "[<label>]" macro prints the hyperlink. The warning on the 
terminal is printed when "<label>" is misspelled. The macro is 
documented in \cite[krizodkaz] section.

\inext {cite}{\empty}{+-}

The links are solved in \db api "{<word>}" too.
This macro uses "\label[+<word>]" and saves the "<word>" prefixed by
"\refapiword" to "\reffile".

\inext {def\nb api}{\empty}{+-}

The \db apitext is printed alongside the "<word>" in the table of contents and 
the index.

When the \db bye is executed, the information for "\refcoef" (line~\cite[write])
is stored in "\reffile" and the test of "\reffile" data consistence is processed.

\ilabel [texttoc] {text\nb tocbuffer}
\ilabel [vypust] {indexbuffer}
\ilabel [write] {write\nb reffile}
\inext {def\nb bye}{^^B\cbrace}{++}

The test of "\reffile" data consistence is done by following steps.
First the "\reffile" is closed, then the control sequences used in "\reffile" 
are redefined by "\setrefchecking" macro, then the "\reffile" is read again.
Now the macros from "\reffile" do the test itself. If inconsistency occurs then
the "\continuefalse" is executed. We can ask to the result of the test by
"\ifcontinue" conditional. The elaborate check of all automatically generated 
hyperlinks is done after the "\reffile" is read. This check is realised by
"\indexbuffer". Why? See the \db setrefchecking.

\ilabel[jerelax] {=\nb relax}
\inext {def\nb setrefchecking}{\empty}{+-}

The "\refcoef" macro is redefined here: it does nothing.
Next, the new version of the "\reflabel" checks if the reference is in the same 
page as in the last run and if it has the same text.
The new macro "\refuseword" works as its original, only the "-<word>"
control sequences are used instead "w:<word>". These control sequence are
used foe another purpose than during normal processing. First, these sequences
take the "\relax" meaning at line~\cite[jerelax].
Second, the "\," is redefined in order to do the test of equivalence of the
"w:<word>" and "-<word>" sequences. The test is executed by 
"\indexbuffer\relax" at line~\cite[vypust]. If an inconsistency occurs then
the message is printed and macro processing is skipped to \db ignoretorelax.
next, the "\refdg"macro is redefined: it writes data only to "\tocbuffer". 
The other macros from "\reffile" write data to "\tocbuffer" too.
The old contents of "\tocbuffer" is stored to the "\text" and the new one is 
created during "\reffile" reading. We check if the table of contents is changed 
at line~\cite[texttoc].


\subsec Generating of Table of Contents, Index and PDF Outlines
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The table of contents (TOC) and index can be printed at various places in the document
(at the begin, end, in the middle\dots). We need to print them correctly
independent of their position. The "\reffile" can be read only at begin of 
the document. After that, it is cleared and reopen to write new information. 
So, we need to store all desired information for TOC or index printing 
during reading of the "\reffile". We are using the "\tocbuffer" and "\indexbuffer"
macros for this. First, these ``buffers'' must be set as empty.
The \db addtext "<text>\to<buffer>" is used for adding new "<text>" to the 
"<buffer>".

\inext {def\nb tocbuffer}{\empty}{+-}

The following commands are used in the \db reffile.

{\def\begtthook{\langleactive\catcode`\!=0\mubytein=1}
\begtt
\reftocline{<number>}{<title>}{<page>}  % about section, subsection for TOC
\refdg{<before>}{<word>}{<after>}{<k-word>}  % about usage of \dg, \dl
\refapiword{<word>}                   % about usage of \api{<word>}
\refuseword{<word>}{<page>}          % about the existence of <word>
\reflabel{<label>}{<text>}{<page>}     % see section !cite[reference], links, references
\refcoef{<coefficient>}{<number>}{<height>}  % see section !cite[specfootnote], spec. notes
\refns{<nslabel>}                     % see section !cite[ns], name spaces
\refnsend{<nslabel>}                  % see section !cite[ns], name spaces
\endtt
\par}

The \db reftocline "{<number>}{<title>}{<pagenumber>}" macro is used for TOC.

\inext {def\nb reftocline}{\empty}{+-}

The information about all sections and subsections are stored in \db tocbuffer gradually.
This buffer includes control sequences \db dotocline "{<number>}{<title>}{<page>}".
The only difference between section and subsection is stored in the "<number>" parameter:
subsection has the "<number>" with a period. This difference is recognised by
the \db istocsec macro.

\inext {def\nb dotocline}{\empty}{+-}

The "\tocbuffer" includes TOC information about sections and subsections. 
Moreover, it includes the data about documented words stored by 
\db refdg a \db refapiword.

\ilabel [right] {right}
\ilabel [ns1] {\nb dl}
\ilabel [ns2] {locword}
\inext {def\nb refdg}{\empty}{+-}

The "\refdg" macro has "{<before>}{<word>}{<after>}{<k-word>}" parameters where
"<before>" is a text before word, "<word>" is a long variant of the word and "<after>"
can include optional braces "()". If the long word differ from short word (when "\dl" is used)
then "<k-word>" includes the short variant of the word else "<k-word>" is empty.
The "\refdg" macro stores its information to "\tocbuffer" and "\indexbuffer" in parallel.
If "<k-word>" is empty then "\sword" is stored to enc\TeX{} table.
If "<k-word>" is nonempty then namespaces are taken into account.
The TOC is created by the \db dotoc macro.

\inext {def\nb dotoc}{\empty}{+-}

The {\bf Index} is created by \db indexbuffer which includes the list of 
all declared words in the document. Each word is sored in the form of
control sequence (this takes minimum \TeX{} memory) and they are separated 
by comma (before sorting) or "\," (after sorting):

{\def\begtthook{\langleactive \sfcode`\:=1000 }
\begtt
before sorting:  \-<word1> , \-<word2> , \-<word3> , \-<word4> , ...
after sorting:   \, \-<wordA> \, \-<wordB> \, \-<wordC> \, \-<wordD> ...
\endtt
\par}

\noindent The "\-<word>" means one control sequence here.
Each control sequence is a macro with the body "<before>\right<after>",
see the \cite[right] line. The index is printed by the \db doindex macro.

\ilabel [calculatedimone] {calculatedimone}
\inext {def\nb doindex }{^^B\cbrace}{++}

The "\calculatedimone" command and the test of "\dimen1" value prepares the 
two columns typesetting, see the section~\cite[dvasloupce].
The "\doindex" begins the "\sec" with the "\titindex" title.
The index printing is started when "\indexbuffer" is nonempty.
The "\indexbuffer" is sorted by "\sortindex" (see section~\cite[abeceda]).
Then the two columns printing is opened by "\begmulti 2" and the "\," 
separator takes the meaning "\doindexentry". 
This macro prints each index entry when "\indexbuffer" expands.

\inext {def\nb doindexentry}{\empty}{+-}

The "\doindexentry" macro removes the "\-" characters from the control
sequence "\-<word>" by the \db ignoretwo, so the "\tmp" includes "<word>" only.
If the "<word>" begins by backslash, it is replaced by "\nb" using 
\db remakebackslash macro. The reason: we needn't the backslash in the
PDF internal labels, see \cite[reference] for more information.
The index entry is finally printed by the "\printindexentry" macro.

When the {\bf PDF outlines} are created, we need to know the number 
of children of each node in the outlines tree. This number is calculated
when "\reffile" is read by \db addbookmark "<node>" macro
(see "\reftocline" and "\refdg" macros). The parameter "<node>"
can be the number of section or the "<section>.<subsection>" pair.
The "<node>" for which we are calculating children is saved in 
\db currb macro. The \db currsecb includes the parent of the "\currb", 
if it exists. The "\bk:<node>" is advanced by one using the 
"\addbookmark" macro.

\inext {def\nb addbookmark}{\empty}{+-}

The \db bookmarks macro opens the group, redefines the "\dotocline"
and "\ptocentry" (i.e.\ macros from "\tocbuffer"), inserts the first
PDF outline with the name of the document and executes the "\tocbuffer".

\inext {def\nb bookmarks}{^^B\cbrace}{++}

The \db setoutline "[<label>]{<text>}{<prefix>}" creates the PDF outline
"<prefix><text>" and the link with "<label>" is activated.
The "\tempnum" register includes the number of children of this PDF outline.

\inext {def\nb setoutline}{\empty}{+-}

The special ``conversion'' macro \db cnvbookmark is used here.
It is nonactive by default. User can set (for example)
"\let\cnvbookmark=\lowercase" for \v c $\to$ c, \v z $\to$ z etc.\
conversions. The "\lccode" setting can be done by "\bookmarkshook".

The text is converted by \db nobraces macro for removing "{}". The macro
\db nobrA is used here too. When we have (for example)
"{\tt text} in \TeX{}" then the "text in TeX" is the result of 
such conversion.


\subsec [abeceda] Sorting by Alphabetical Order
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

This work is done by "\sortindex" macro. First version implemented 
the bubble sort algorithm but it was slow for large indexes. For example 
sorting of the index of this document has taken circa 2 seconds of computer time.
My son Mirek rewrote the sorting by mergesort algorithm in the second version 
of docByTeX. The previous 52 thousand sorting queries (for an index of the size 
comparable with the index used here) was reduced to 1600 queries, so 
30 times better.

First, we declare the \db ifAleB which 
answers true if $A<B$ (see also "\isAleB" macro below). 
The auxiliary macros \db nullbuf, \db return and \db fif 
are used here. The "\return" macro is used for escaping from various loops
to the "\relax" mark.
The "\fi" are balanced by the "\fif" macro in nested "\if...\fi" 
constructions. This save the number of "\expandafter" commands.

\inext {newif\nb ifAleB}{\empty}{+-}

The \db sortindex macro puts to the input queue the content of the 
whole "\indexbuffer" followed by "\end,\end", the new "\indexbuffer" 
is set as empty and the "\mergesort" macro is executed.

\inext {def\nb sortindex}{^^B\cbrace}{++}

The \db mergesort takes two groups of items repeatedly, each group is sorted 
already. The groups are separated by commas in the input queue. These two groups 
are merged to one sorted group. This process is repeated until "\end" occurs.
One merging of two groups looks like that: suppose for example two
groups "eimn,bdkz," which is merged to one group "bdeikmnz,".
Letters in that example are the whole sorted entries.

At the begin of the process, all groups have only one item. After first pass 
over input queue, the result is the groups with two items. They are saved
back in the "\indexbuffer". Next pass puts the "\indexbuffer" to the input 
queue and creates groups with four items. Next, there are 8~items per group etc.
This process is repeated until only  one sorted group is created 
(line~\cite[konecsortu]) and only "\end" is in the second group.
The "\gobblerest" macro removes the second "\end" from input queue.

\noactive{dvojice}
\ilabel [merge:porovnani] {isAleB}
\ilabel [merge:trojka] {mergesort p1+}
\ilabel [merge:p1] {ifx,}
\ilabel [merge:p2] {fif\nb mergesort\cbrace}
\ilabel [konecsortu] {empty\nb indexbuffer}
\ilabel [napercarky] {napercarky}
\inext {def\nb mergesort }{^^B\cbrace}{++}

{\def\quotehook{\catcode`\<12}
The core of the "\mergesort" is on the 
lines~\cite[merge:porovnani]--\cite[merge:trojka].
The "\mergesort" macro saves first item of the first group to the "#1" parameter,
next items of the first group to the "#2" parameter and the first item of the
second group to the "#3" parameter. If "#1<#3" then we save "#1" to the output 
"\indexbuffer", the "#1" is removed from input queue and "\mergesort" 
is executed again. The cases with empty parameters are solved in the lines
\cite[merge:p1]--\cite[merge:p2]: we need to save the rest of the nonempty group
to the output "\indexbuffer" and go to the next pair of groups.
If the terminal string "\end,\end" is scanned then the next run
of "\mergesort" is executed after "\indexbuffer" is put to the input queue and set 
it to empty value.  
\par}

The sorting of the two items are realized by \db isAleB "<itemA><itemB>"
macro. The items are in the form "\-<wordA>" and "\-<wordB>".
The macro converts these parameters to the strings by "\string" primitive
and expands to "\testAleB"~"<wordA>\relax<wordB>\relax".
The "\lowercase" primitive is executed here because we needn't distinguish
between uppercase/lowercase letters. 

\ilabel [teckanula] {0\nb relax}
%\ilabel [teckajedna] {2.1}
\inext {def\nb isAleB }{^^B\cbrace}{++}

The \db testAleB "<wordA>\relax<wordB>\relax" macro tests if
"<wordA>" precedes "<wordB>". It he first letters are the same, the macro 
is called recursively. The recursion will be truly finished because
different tails are appended to the compared words at line~\cite[teckanula].

\inext {def\nb testAleB}{^^B\cbrace}{++}

The macro \db napercarky inserts "\," separators between items in the sorted
"\indexbuffer".

\inext {def\nb napercarky}{\empty}{+-}


\subsec Merging of the List of the Page Numbers
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Each occurrence of the "<word>" is stored to the "\reffile" as
\db refuseword "{<word>}{<page>}". This macro is processed at 
the begin of the document when "\reffile" is read.

\inext {def\nb refuseword}{^^B\cbrace}{++}

So, the list of the pages where the "<word>" occurs is stored in 
the "\w:<word>" macro. Pages are separated by commas.
The list looks like:

\begtt
2,5,5,10,11,12,12,13,13,13,27
\endtt

We need to convert this list to the format "2, 5, 10--13, 27",
i.e.\ we need to remove double occurrences and to replace 
consecutive lists of pages by intervals in the form "<from>--<to>".
This work is done by \db listofpages "{<word>}" macro which 
puts the list of pages to the input queue terminated by ",0,"
and executes the "\transf" macro.

\inext {def\nb listofpages}{^^B\cbrace}{++}

The "\transf" macro removes the page numbers which are equal to 
\db dgnum or \db apinum. We want to avoid the double occurrence of the main page
and underlined page in the list. These pages are printed separately.
The declaration of the registers follows:

\inext {newcount\nb apinum}{\empty}{+-}

The "\tempnum" is current page number processed in the list and 
"\ifdash" returns true if the interval is opened by "<from>--".
The "\iffirst" returns true if the first page of the list is processed.

The \db transf "<list of pages>,0," executes repeatedly the \db cykltransf macro.

\inext {def\nb transf}{def\nb carka}{++}

The "\cykltransf" macro is a little finite state automaton.
It needs no more comments.


\subsec [dvasloupce] Multicolumn typesetting
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The macros for multicolumn printing are borrowed from 
``\TeX{}book inside out'', pages 244--246.

\ilabel [dimen1] {dimen1<2}
\inext {newdimen\nb colsep}{TBN}{++}

One problem is solved in addition. We check the empty space on the 
current page before the section title is printed. This work is done
by \db calculatedimone 
(executed by "\doindex" macro at the line \cite[calculatedimone]).

\inext {def\nb calculatedimone}{\empty}{+-}

\subsec The final settings, catcodes
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The catcodes are set at the end of the {\tt docby.tex} file.
We add the active category for the {\tt\char`\"} character and we set 
the "_" as a normal character because this character is mostly used in the
identifiers and the catcode 8 of this character causes many problems.

\inext {catcode`\nb_}{\empty}{+-}

The "\everymath" and "\everydisplay" returns the category of "_" to 
the plain\TeX{} meaning (as math index prefix).

The active {\tt\char`\"} character separates the ``inline verbatim'' environment.

\inext {catcode`\nb}{\empty}{+-}

The \db langleactive sets the active catcode for the {\tt<} char. 
So, you can write {\tt<text>} in ``inline verbatim'' and the 
"<text>" is printed.

\inext {def\nb langleactive}{\empty}{+-}

\doindex

\bye