summaryrefslogtreecommitdiff
path: root/macros/texinfo/texinfo/doc/texi2any_api.texi
blob: 1292f02c2e4c1006e435993fb7417fbb4093200a (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
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
3618
3619
3620
3621
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698
3699
3700
3701
3702
3703
3704
3705
3706
3707
3708
3709
3710
3711
3712
3713
3714
3715
3716
3717
3718
3719
3720
3721
3722
3723
3724
3725
3726
3727
3728
3729
3730
3731
3732
3733
3734
3735
3736
3737
3738
3739
3740
3741
3742
3743
3744
3745
3746
3747
3748
3749
3750
3751
3752
3753
3754
3755
3756
3757
3758
3759
3760
3761
3762
3763
3764
3765
3766
3767
3768
3769
3770
3771
3772
3773
3774
3775
3776
3777
3778
3779
3780
3781
3782
3783
3784
3785
3786
3787
3788
3789
3790
3791
3792
3793
3794
3795
3796
3797
3798
3799
3800
3801
3802
3803
3804
3805
3806
3807
3808
3809
3810
3811
3812
3813
3814
3815
3816
3817
3818
3819
3820
3821
3822
3823
3824
3825
3826
3827
3828
3829
3830
3831
3832
3833
3834
3835
3836
3837
3838
3839
3840
3841
3842
3843
3844
3845
3846
3847
3848
3849
3850
3851
3852
3853
3854
3855
3856
3857
3858
3859
3860
\input texinfo.tex    @c -*-texinfo-*-

@include version-texi2any_api.texi

@settitle GNU Texinfo @command{texi2any} Output Customization

@copying
This manual is for GNU Texinfo @command{texi2any} program output
adaptation using customization files (version @value{VERSION},
@value{UPDATED}).

Copyright @copyright{} 2013, 2022 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts.  A copy of the license is included in the section entitled
``GNU Free Documentation License'' in the Texinfo manual.
@end quotation
@end copying

@dircategory Texinfo documentation system
@direntry
* texi2any customization: (texi2any_api).
                                Customizing texi2any output
@end direntry

@titlepage
@title GNU Texinfo @command{texi2any} Output Customization
@subtitle for GNU Texinfo version @value{VERSION}, @value{UPDATED}

@page

@insertcopying
@end titlepage

@summarycontents
@contents


@node Top
@top @c @command{texi2any} Output Customization

@node Overview
@chapter Overview

@cartouche
@quotation Warning
All of this information, with the exception of command-line options
and search directories associated with command line options
(@pxref{Loading Init Files}), may become
obsolete in a future Texinfo release.  Right now, the ``API''
described in this chapter is immature, and incomplete (translations
strings customization API, in particular, is lacking),
so we must keep open the possibility of incompatible, possibly major,
changes.  Of course we try to avoid incompatible changes, but it is
not a promise.
@end quotation
@end cartouche

This manual describes how to customize the @command{texi2any} HTML output.
Although some of the features here can technically be used with other output
formats, it's not especially useful to do so, so we'll write the documentation
as if HTML were the target format.  Most of the customizations are only
available for HTML.

The conversion of Texinfo to HTML is done in two steps.  After reading
command-line options and init files, input Texinfo code is parsed
into a Texinfo Perl tree and information is gathered on the document
structure.  This first step can only be customized to a certain extent, by
using the command-line options and setting customization variables.  The
Texinfo Perl tree describes a Texinfo document in a structured way which makes
it easy to go through the tree and format @@-commands and other containers.

The second step is the @dfn{conversion} step done in a converter.  The HTML
converter takes a Texinfo Perl tree as input and transforms it to HTML@.  The
code that is used to go through the tree cannot be customized, but the
conversion of tree elements can be fully customized.

@c Do we want to describe the tree in the manual?  It is already described
@c in (texi2any_internals)Texinfo::Parser TEXINFO TREE
@c  The tree structure will be described in future versions of the
@c manual.


@node Loading Init Files
@chapter Loading Initialization Files and Search Paths

@cindex Loading init files
@cindex Initialization files, loading
@cindex Search paths, for initialization files

@c @pindex Config @r{init files loaded}
@cindex @file{Config} init files loaded

@quotation Warning
The @file{Config} file related paths and even the use
of @file{Config} files is not definitive.
@end quotation

You can write so-called @dfn{initialization files}, or @dfn{init
files} for short, to modify almost every aspect of output formatting.
The program loads init files named @file{Config} each time it is run.
Those files are looked for in the following directories:

@table @file
@item @var{datadir}/texi2any/
(where @var{datadir} is the system data directory specified at
compile-time, e.g., @file{/usr/local/share})

@item @var{sysconfdir}/texi2any/
(likewise specified at compile time, e.g., @file{/usr/local/etc})

@item ~/.texi2any/
(where @code{~} is the current user's home directory)

@item ./.texi2any/
(under the current directory)

@item ./
(the current directory)
@end table

All @file{Config} files found are loaded, in the above order.  Thus,
@file{./Config} can override entries in, say,
@file{/usr/local/share/makeinfo/Config}.

@c @opindex --init-file
@cindex @option{--init-file}
However, the most common way to load an initialization file is with
the @option{--init-file} option, explicitly specifying the file to be
loaded.  By default the following directories are searched, in the
following order.  Only the first file found is used:

@enumerate
@item The current directory @file{./};

@item @file{./.texi2any/} under the current directory;

@item @file{~/.texi2any/}
where @code{~} is the current user's home directory;

@item @file{@var{sysconfdir}/texi2any/}
where @var{sysconfdir} is the system configuration directory
specified at compile-time, e.g., @file{/usr/local/etc};

@item @file{@var{datadir}/texi2any/}
Where @var{datadir} is the system data directory likewise specified at
compile time, e.g., @file{/usr/local/share};

@item @file{./.texinfo/init/} under the current directory;

@item @file{~/.texinfo/init/} under the current home directory;

@item @file{@var{sysconfdir}/texinfo/init/} with @var{sysconfdir} as above;

@item @file{@var{datadir}/texinfo/init/} with @var{datadir} as above.

@item @file{@var{datadir}/texinfo/ext/} with @var{datadir} as above.
@end enumerate

The @file{@var{datadir}/texinfo/ext/} directory contains the
init files directly loaded from @command{texi2any} code.  When loaded from
@command{texi2any} code directly, init files are only searched for
in that directory, being considered as part of the program and not as user
customization.  Since the directory is also in the list of directories searched
for init files loaded by the @option{--init-file} option, those init
files can also be loaded as regular user specified init files.

Additional directories may be prepended to the list with the
@option{--conf-dir} option (@pxref{Invoking @command{texi2any},,, texinfo, Texinfo}).


@node Init File Basics
@chapter Init File Basics

@cindex Init file basics
@cindex Perl, language for init files

Init files are written in Perl, and by convention have extension
@file{.init} or @file{.pm}.  Several init files are included in the Texinfo
distribution, and can serve as a good model for writing your own.  Another
example is the @code{Texinfo::Convert::HTML} module which implements
almost all the Texinfo HTML function described in this manual for the conversion
to HTML@footnote{The @code{Texinfo::Convert::HTML} module also implements the
HTML converter which go through the tree and call user defined functions.}.
In @code{Texinfo::Convert::HTML} the API may not be followed strictly for
performance reasons, in that case there should always be a @samp{API info:}
comment which shows what the API conformant code should be.
The Licenses conditions of the diverse files used as example should be taken
into account when reusing code.

@node Init File Namespace
@section Init File Namespace

@cindex Init file namespace
@cindex Namespace, for init files
@cindex Perl namespaces, for init files

Initialization file are loaded from the main program in the
@code{Texinfo::Config} namespace.  This means that the namespace of the main
program and the namespace of initialization files are distinct, which minimizes
the chance of a name clash.

It is possible to start init files with:
@example
package Texinfo::Config;
@end example
It is not required, but it may help some debugging tools determine in which
namespace the code is run.

In the @code{Texinfo::Config} namespace, the functions names beginning with
@samp{texinfo_}, @samp{GNUT_} and @samp{_GNUT_} are reserved.  User defined
functions in init files should never begin with those prefixes.

The HTML converter is not available directly in the init files namespace,
instead it is passed to functions defined in init files and registered as
functions to be called from the converter. @xref{User Defined Functions}.


@node Managing Customization Variables
@section Managing Customization Variables

@cindex Customization variables, setting and getting

The basic operations on customization variables are to set and
retrieve their values.  New variables can also be added.

The customization variables also valid in the main program out of the HTML
converter are handled differently if they are strings or
arrays.  The customization variables only relevant for the conversion phase
are always set like string variables, in particular array or hash references.

@node Setting Main Program String Variables
@subsection Setting Main Program String Variables

To set the value of a string customization variable from an initialization file,
use @code{texinfo_set_from_init_file}:

@defun texinfo_set_from_init_file ($variable_name, $variable_value)
@var{$variable_name} is a string containing the name of the variable
you want to set, and @var{$variable_value} is the value to which you
want to set it.  @var{$variable_value} may be @samp{undef}.
@end defun

For example,

@example
texinfo_set_from_init_file('documentlanguage', 'fr');
@end example

@noindent overrides the @code{@@documentlanguage} from the
document.  It would be overridden by @option{--document-language} on
the command line.
Another example:

@example
texinfo_set_from_init_file('SPLIT', 'chapter');
@end example

@noindent overrides the default splitting of the document.  It would be
overridden by @option{--split} on the command line.

A final example:

@example
texinfo_set_from_init_file('NO_CSS', 1);
@end example

@noindent overrides the default value for @code{NO_CSS}.  It would be
overridden by @code{--set-init-variable NO_CSS=1} on the command line.

Setting the output format cannot be done by setting the customization variable
@code{TEXINFO_OUTPUT_FORMAT}.  This customization variable sets the output
format in the main program, but not from init files as additional
code needs to be run.  Instead, the @code{texinfo_set_format_from_init_file}
function should be used:

@defun texinfo_set_format_from_init_file ($output_format)
@var{$output_format} is the output format; sets the output format,
without overriding formats set from the command line.
@end defun

Any output format can be set, but since only HTML can be customized,
the main use of @code{texinfo_set_format_from_init_file} is to
set the format to @samp{html}, such that HTML is generated
instead of Info in the default case.

For the customization variables associated with @@-commands, see
@ref{Customization Variables for @@-Commands,,, texinfo, Texinfo}.  For the
customization variables associated with command line options, see
@ref{Customization Variables and Options,,, texinfo, Texinfo}.


@node Modifying Main Program Array Variables
@subsection Modifying Main Program Array Variables

@quotation Warning
The main program customization variables associated with arrays
are not documented.
@end quotation

Customization variables for the main program associated with an array of values
are handled differently. Two functions can be used in init files,
@code{texinfo_add_to_option_list} to add values to the array and
@code{texinfo_remove_from_option_list} to remove values from the array
associated with the customization variable:

@defun texinfo_add_to_option_list ($variable_name, $variable_values_array_reference)
@defunx texinfo_remove_from_option_list ($variable_name, $variable_values_array_reference)
@var{$variable_name} is the name of the variable; the values in the
array reference @var{$variable_values_array_reference} are added to the
list associated with the variable with @code{texinfo_add_to_option_list}, and removed with
@code{texinfo_remove_from_option_list}.
@end defun


@node Setting Converter Variables in Main Program
@subsection Setting Converter Variables in Main Program

Array and hash references customization variables values relevant in converters
only (not in main program) can be set through the main program in init files.
These variables cannot be set on the command-line.  They are documented in the
customization documentation, not in the main Texinfo manual.  Such arrays or
hashes references can be passed through @code{texinfo_set_from_init_file}.  For
example:

@example
my @@SECTION_BUTTONS =
  (
   \&singular_banner,
   'Back', 'Forward',   'FastBack', 'FastForward',
   'Up', 'Top', 'Contents', 'Index', 'About'
  );

texinfo_set_from_init_file ('SECTION_BUTTONS', \@@SECTION_BUTTONS);
@end example

@node Getting Main Program Variables Values
@subsection Getting Main Program Variables Values

To get the value of a variable, the function is
@code{texinfo_get_conf}:

@defun texinfo_get_conf ($variable_name)
@var{$variable_name} is the name of the variable; its value (possibly
@code{undef}) is returned.
@end defun

For example:

@example
if (texinfo_get_conf('footnotestyle') eq 'separate') @{ ... @}
@end example


@node Adding Customization Variables
@subsection Adding Customization Variables

@cindex Customization variables, adding

Trying to set a customization variable that is not known as a valid
customization variable in @command{texi2any} is an error.  It is possible, however,
to add new customization variables from init files.  To add a customization
variable, the function is @code{texinfo_add_valid_customization_option}:

@defun texinfo_add_valid_customization_option ($variable_name)
@var{$variable_name} is added as a valid customization variable name.
@end defun

The variable value, if set, should also be available in the converters and therefore
in the init file functions registered and called from the converters.


@node Init File Loading Error Reporting
@section Init File Loading Error Reporting

@cindex Error reporting @subentry loading

If an error or a warning should be emitted when loading an init file, before
the conversion, use @code{texinfo_register_init_loading_error} for an error and
@code{texinfo_register_init_loading_warning} for a warning.

@defun texinfo_register_init_loading_error ($message)
@defunx texinfo_register_init_loading_warning ($message)
Cause an error message or a warning message based on @var{$message}
to be output, taking into account options related to error reporting
such as @option{--force} or @option{--no-warn}.
@end defun

Errors or warning emitted from user defined functions should use the
converter (@pxref{Error Reporting in User Defined Functions}).


@node Simple formatting customization
@chapter Simple formatting customization

Some change in output formatting can be specified with simple code,
not very different from simple textual configuration information.


@node Init File Expansion Contexts
@section Init File Expansion Contexts: Normal, Preformatted, Code, String, Math

@cindex Init file expansion contexts
@cindex Expansion contexts, for init files
@cindex Contexts for expansion in init files

There are five expansion contexts of interest:

@table @emph
@item normal context
@cindex Normal expansion context
Paragraphs, index entries, tables, @enddots{}

@item preformatted context
@cindex Preformatted expansion context
When spaces between words are kept.  For example, within the
@code{@@display} (@pxref{@code{@@display},,, texinfo, Texinfo}) and
@code{@@example} environments (@pxref{@code{@@example},,, texinfo, Texinfo}), and
in menu comments.  The preformatted regions
are usually rendered using @code{<pre>} elements in HTML.

@item code context
When quotes and minus are kept.  In particular @code{---}, @code{``}
and other similar constructs are not converted to dash and quote special
characters.  For exampe, in @code{@@code} or @code{@@option} commands
(@pxref{Useful Highlighting,,, texinfo, Texinfo}).

@item math context
@cindex Math expansion context
Math (@pxref{math,, @code{@@math}, texinfo, Texinfo}).  Code or preformatted
specifications are often used for math too. In those cases, there
is no way to separately specify the formatting in math context.

@item string context
@cindex String expansion context
When rendering strings without formatting elements, for example in titles.  The
string context allows for limited formatting, typically without any element
when producing HTML or XML, so the value can be used in an attribute.  XML
entities can be used in strings.

@end table

It is worth mentioning that in some cases, in particular for file names,
plain text can also be used in conversion.  There is no associated
context in the converter, so the conversion to plain text is usually
performed by converting a Texinfo elements tree outside of the main
conversion flow.


@node Simple Customization for Commands Without Arguments
@section Simple Customization for Commands Without Arguments

@cindex HTML customization for commands without arguments
@cindex Commands without arguments, customizing HTML for
@cindex Insertion commands, customizing HTML for

These commands include those whose names are a single nonletter
character, such as @code{@@@@}, and those with a normal alphabetic
name but whose braces should be empty, such as @code{@@TeX@{@}} and
@code{@@AA@{@}}.

To change the formatting of a command, the functions is
@code{texinfo_register_no_arg_command_formatting}:

@defun texinfo_register_no_arg_command_formatting ($command_name, @
                  $context, $text, $html_element, $translated_string)
@var{$command_name} is the @@-command name, without the leading @@.
@var{$context} is @samp{normal}, @samp{preformatted} or @samp{string}.
There is no separate math context, @samp{preformatted} should be used
for math context. @xref{Init File Expansion Contexts}.  If @var{$context}
is @code{undef}, the @samp{normal} context is assumed.

The remaining arguments determine the formatting.  If @var{$text} is set,
the corresponding text is output when the @@-command is formatted.  @var{text}
can contain HTML elements if needed.  If @var{$html_element} is set, the text
is enclosed between the @var{$html_element} element opening and the element
closing.  If @var{$translated_string} is set, @var{$translated_string} is used
as text and is translated when the document language changes.
@xref{Texinfo::Translations METHODS,,,texi2any_internals}.
@end defun

It is not required to set values for all the contexts.  If preformatted context
output is not set, normal context output is used.  If string context output is not set,
preformatted context output is used.

For example, if you want @code{&shy;} to be output
for @code{@@-} in normal, preformatted (and math) and string context, call

@example
texinfo_register_no_arg_command_formatting('-', undef, '&shy;');
@end example

If you want @code{<small>...</small>} to be output for @code{@@enddots}
in normal context and @code{...} to be output in other contexts, call
@example
texinfo_register_no_arg_command_formatting('enddots',
                                           'normal', '...', 'small');
texinfo_register_no_arg_command_formatting('enddots',
                                           'preformatted', '...');
@end example

If you want @code{error--&gt;} to be used for @code{@@error} in every context,
with a translation when the document language changes, call

@example
texinfo_register_no_arg_command_formatting('error', undef, undef, undef,
                                           'error--&gt;');
@end example

@quotation Warning
There is no possibility to provide custom translations for selected
strings, such that the translated string case cannot actually be used
in practice.
@end quotation


@node Simple Customization for Simple Commands with Braces
@section Simple Customization for Simple Commands with Braces

@cindex HTML customization for simple commands
@cindex Simple commands, customizing HTML for
@cindex Style commands, customizing HTML for

The formatting of the output produced by ``indicator'' and font
commands (e.g., @code{@@code}, @code{@@t}),
and other simple commands with
arguments (e.g., @code{@@asis}, @code{@@clicksequence},
@code{@@sup}, @code{@@verb}) can be changed with @code{texinfo_register_style_command_formatting}:

@defun texinfo_register_style_command_formatting ($command_name, @
                                     $html_element, $in_quotes, $context)
@var{$command_name} is the @@-command name, without the leading @@.
@var{$context} is @samp{normal}, @samp{preformatted} or @samp{string}.
There is no separate math context, @samp{preformatted} should be used
for math context. @xref{Init File Expansion Contexts}.  If @var{$context}
is @code{undef}, the @samp{normal} context is assumed.

If @var{$html_element} is set, the argument is enclosed between the
@var{$html_element} element opening and the element closing.
@var{$html_element} is always ignored in @samp{string} context.  If @var{$in_quotes}
is true, the result is enclosed in quotes
associated with customization variables @code{OPEN_QUOTE_SYMBOL} and
@code{CLOSE_QUOTE_SYMBOL}.

If @var{$html_element} is undefined and @var{$in_quotes} is not set, the formatted
argument is output as is.
@end defun

For example, to set @code{@@sansserif@{argument@}} to be formatted as
@code{<code>@var{argument}</code>} in normal and preformatted context,
and as a quoted string in string context, use:

@example
texinfo_register_style_command_formatting('sansserif', 'code', 0, 'normal');
texinfo_register_style_command_formatting('sansserif', 'code', 0,
                                          'preformatted');
texinfo_register_style_command_formatting('sansserif', undef, 1, 'string');
@end example

To output the formatted argument of @code{@@t} as is:
@example
foreach my $context ('normal', 'example', string') @{
  texinfo_register_style_command_formatting ('t', undef,
                                             undef, $context);
@}
@end example


@node Simple Customization of Accent Commands
@section Simple Customization of Accent Commands

@cindex HTML customization for accent commands
@cindex Accent commands, customizing HTML for
@cindex Accent command named entities

The formatting of accent commands (@code{@@'}, @code{@@ringaccent},
@code{@@dotless}) can be customized with @code{USE_NUMERIC_ENTITY}.
It is also possible to change how accented commands are converted
to named entities.  The accent named entities are obtained by combining
a letter to be accented, such as @samp{e} and a postfix based on the
accent command name, for example @samp{acute} for the acute accent
@code{@@'}.  For example, @samp{@@'e} is converted to the @samp{&eacute;}
named entity in the default case.

The association of accent @@-command and named entity postfix and
the list of letters that can be prepended can be changed with
@code{texinfo_register_accent_command_formatting}:

@defun texinfo_register_accent_command_formatting ($accent_command_name, $entity_postfix, $letters)
@var{$accent_command_name} is a Texinfo accent formatting @@-command name,
@var{$entity_postfix} is a string corresponding to the accent command that
is postpended to the letter accent argument.  @var{$letters} is a string
listing the letters that can be combined with the @var{$entity_postfix}.
If @var{$entity_postfix} or @var{$letters} is an empty string, numeric entities
are used instead of named entities.
@end defun

For example, with the following code, @code{@@dotless@{i@}} should be converted
to @code{&inodot;}, and @code{@@dotless@{j@}} to @code{&jnodot;}.  Other letters
than @samp{i} and @samp{j} in argument of @code{@@dotless} should not be combined
into a named entity with that example.
@example
texinfo_register_accent_command_formatting('dotless', 'nodot', 'ij');
@end example


@node Simple Customization of Containers
@section Simple Customization of Containers

Texinfo tree elements that are not text container nor directly associated with
an @@-command can have information set on their formatting.  The first piece of
information is whether their contents should be considered in code context (@pxref{Init
File Expansion Contexts}).  The other piece of information is the type of
preformatted environment they are, analogous with the @@-command names of
@code{@@example} or @code{@@display}@footnote{Note that setting the type of preformatted environment does not
make sure that there are preformatted containers used for the formatting of their
contents instead of paragraph containers, since this is determined in the very
first step of parsing the Texinfo code, which cannot be customized.}.

The function used is @code{texinfo_register_type_format_info}:

@defun texinfo_register_type_format_info ($type, $code_type, $pre_class_type)
@var{$type} is the type of the container.  If @var{$code_type} is set, the container
contents are assumed to be in code context. @xref{Init File Expansion
Contexts}. If @var{$pre_class_type} is set, the HTML @code{<pre>} elements
class attribute are based on @var{$pre_class_type}, if there are such HTML
elements output for preformatted content of @var{$type} containers.
@end defun

For example, to set content appearing in-between node links in @code{@@menu},
which is in the @code{menu_comment} container type
to be formatted in a code context, with preformatted type @samp{menu-between}, use:

@example
texinfo_register_type_format_info('menu_comment', 1, 'menu-between');
@end example

@xref{Texinfo::Parser Types of container elements,,,texi2any_internals}, for a
description of container types.


@node Simple Customization of CSS
@section Simple Customization of CSS Rules and Imports

@cindex Customizing CSS
@cindex CSS customization

CSS in HTML output can already be modified with command line options
(@pxref{HTML CSS,,, texinfo, Texinfo}) and customization options such as
@code{NO_CSS} and @code{INLINE_CSS_STYLE}.

Information on static CSS data used in conversion and some control over the CSS
output is possible.  The information is about CSS rules lines and CSS import
lines obtained from parsing @option{--css-include=@var{file}} files, as
described in @ref{HTML CSS,,, texinfo, Texinfo}, and CSS style rules associated with HTML
elements and class attributes used in the conversion to HTML.  The CSS style
rules selectors are, classically, @code{@var{element}.@var{class}} strings with
@var{element} an HTML element and @var{class} an attribute class associated to
that element.

The function used are @code{css_get_info} to get information and
@code{css_add_info} to modify:

@defun @var{$converter}->css_get_info ($specification, $css_info)
@defunx @var{$converter}->css_add_info ($specification, $css_info, $css_style)

Those functions can only be used on a converter @var{$converter}, from
functions registered and called with a converter.  @var{$specification} is
@code{'rules'} to get information on or set information for CSS rules lines and
@code{'imports'} to get information on or set information for CSS import lines.
Any other value for @var{$specification} corresponds to CSS style rules
associated with HTML elements and class attributes selectors.

With @code{css_get_info}, if @var{$specification} is set to @code{'rules'} or
@code{'imports'}, the corresponding arrays are returned.  Otherwise,
if @var{$css_info} is @code{undef}, a hash reference with all the CSS rules selector as keys
and the corresponding rules as values is returned.  If @var{$css_info} is defined,
it is considered to be a CSS rule selector and the corresponding CSS style is returned,
or @code{undef} if not found.

With @code{css_add_info}, @var{$css_info} is an additional entry added to
CSS rules lines if @var{$specification} is set to @code{'rules'} or an additional
entry added to CSS import lines if @var{$specification} is set to @code{'imports'}.
Otherwise, @var{$css_info} is a CSS rule selector and the associated
style rule is set to @var{$css_style}.
@end defun

Some examples of use:

@example
my @@all_included_rules = $converter->css_get_info('rules');
my $all_default_selector_styles = $converter->css_get_info('styles');
my $titlefont_header_style = $converter->css_get_info('styles',
                                                      'h1.titlefont');

$converter->css_add_info('styles', 'h1.titlefont', 'text-align:center');
$converter->css_add_info('imports', "\@@import \"special.css\";\n");
@end example

Note that the CSS selectors and associated style rules that can be accessed and
modified will not necessarily end up in the HTML output. They are output
only if the HTML element and class corresponding to a selector is seen in the
document. @xref{Customizing CSS}.

How to run code during the conversion process is described later
(@pxref{Init File Calling at Different Stages}). The simplest way to
use the @code{css_add_info} function would be to use a function
registered for the @samp{structure} stage:

@example
sub my_function_set_some_css @{
  my $converter = shift;

  $converter->css_add_info('styles', 'h1.titlefont',
                           'text-align:center');
  # ... more calls to  $converter->css_add_info();
@}

texinfo_register_handler('structure', \&my_function_set_some_css);
@end example

@xref{Customizing CSS} for even more control on CSS lines output.


@node Simple headers customizations
@chapter Simple headers customizations

Some customization of navigation panels appearing in header and footers in
output can be specified with simple code.  To explain how navigation
panels are customized, we first describe how the document is organized
and which directions are available as the directions is the basis for
navigation panel customization.


@node Output Element Units
@section Output Element Units

@cindex Output elements
@cindex Elements, main unit of output documents
@cindex Document units
@cindex Texinfo tree element units

We will call the main unit of output documents a document @dfn{unit},
or a Texinfo tree element @dfn{unit}.  An
element unit's association with output files is determined by the split
options (@pxref{Splitting Output,,, texinfo, Texinfo}).  This section describes
precisely how these output units work, with details for customization.

@cindex Output elements, defined

The output elements are:

@table @emph
@item Normal document units
@cindex Normal document units
These are normal sections and nodes.  Usually a node is associated
with a following sectioning command, while a sectioning command is
associated with a previous node; they both together make up the
element unit.  Either the node or the sectioning command is considered to
be the main element component, depending on the values of the
customization variables @code{USE_NODES}
(@pxref{HTML Customization Variables,,, texinfo, Texinfo}).

For example, when generating Info, the nodes are the units; when
generating HTML, either case may happen (@pxref{Two Paths,,, texinfo,
Texinfo}).

@item Top element
@cindex Top element

The top element is the highest element unit in the document structure.  If the
document has an @code{@@top} section (@pxref{@code{@@top} Command,,, texinfo,
Texinfo}), it is the element associated with that section; otherwise, it is the
element associated with the document's @code{@@node Top} (@pxref{The Top
Node,,, texinfo, Texinfo}).  If there is no @code{@@node Top}, the first
element in the document is the top element.

@item Miscellaneous elements
@cindex Table of contents, output element unit
@cindex Short table of contents, output element unit
@cindex Overview, output element unit
@cindex Footnotes, output element unit
@cindex About page, output element unit
The remaining element units are associated with different files if the
document is split, and also if @code{MONOLITHIC} is not set.  There
are four such miscellaneous elements, also called special elements:
@enumerate
@item Table of contents
@item Short table of contents, also called Overview
@item Footnotes page
@item About page
@end enumerate

More details:

@itemize
@item The @emph{Table of contents} should only be formatted if
@code{@@contents} is present in the document.

@item Similarly the @emph{Short table of contents} should only appear if
@code{@@shortcontents} or @code{@@summarycontents} is present.

@item The customization variables @code{contents} and
@code{shortcontents} may be set to trigger the output of the
respective elements.

@vindex CONTENTS_OUTPUT_LOCATION@r{, Elements}
@item If @code{CONTENTS_OUTPUT_LOCATION} is set to @samp{separate_element}, the
@emph{Table of contents} and @emph{Short table of contents} elements are
separate (@pxref{Contents and Short Table of Contents Customization}).
Otherwise the @emph{Table of contents} and @emph{Short table of contents}
elements are directly included within the document, at locations depending on
the specific @code{CONTENTS_OUTPUT_LOCATION} value.

@item When generating HTML, the @emph{Footnotes page} should only
be present if the footnotes appear on a separate page (@pxref{Footnote
Styles,,, texinfo, Texinfo}).  However, a footnote element is present if the document is
not split.

@item The @emph{About page} shouldn't be present for documents
consisting of only one sectioning element, or for monolithic documents
without navigation information, or if @code{DO_ABOUT} is not set.

@end itemize
@end table

It is common not to have anything but normal element units, especially in
case of monolithic output.

@vindex USE_NODES
The main component of elements is sections if @code{USE_NODES} is 0;
conversely, the main component is nodes if @code{USE_NODES} is set.

When sections are the main components of element units, ``isolated'' nodes
not directly associated with a sectioning command are associated with
the following sectioning command, while sectioning commands without
nodes constitute element units.  Conversely, when nodes are the main
components of elements, isolated sections not associated with nodes
are associated with the previous node, and isolated nodes are
element units.


@node Directions
@section Directions

@cindex Output element unit directions
@cindex Links information
@cindex Element directions
@cindex Directions

A variety of data items, called @dfn{element directions}, are associated
with element units.  They may be used in the formatting functions, and/or
associated with a button (@pxref{Simple Navigation Panel Customization}).

Each element direction has a name and a reference to the element unit they
point to, when such an element exists.  The element is either a
global element unit (for example, the first element) or relative to the
current element unit (for example, the next element unit).  Such relative
elements are determined with respect to the document structure defined
by the section structuring commands (@code{@@chapter},
@code{@@unnumbered}@dots{}) or by the nodes if the node pointers are
specified on @code{@@node} lines or in menus (@pxref{Two Paths,,, texinfo, Texinfo}).

Here is the list of element units directions:

@table @emph
@item @samp{@ }
An empty button.

@item Top
Top element.

@item About
About (help) page.

@item Contents
Table of contents.

@item Overview
Overview: short table of contents.

@item Footnotes
Corresponds to the @code{Footnotes} element (@pxref{Output Element
Units}).

@item Index
The first element unit with @code{@@printindex}.

@item This
The current element unit.

@item Forward
Next element unit in reading order.

@item First
First element unit in reading order.

@item Last
Last element unit in reading order.

@item Back
Previous element unit in reading order.

@item FastForward
Next chapter element unit.

@item FastBack
Beginning of this chapter, or previous chapter if the element is a chapter.

@item Next
Next section element unit at the same level.

@item Prev
Previous section element unit at the same level.

@item Up
Up section.

@item SectionNext
Next element unit in section reading order.

@item SectionPrev
Previous element unit in section reading order.

@item SectionUp
Up in section reading order.

@item NodeNext
Next node element unit.

@item NodeForward
Next node element unit in node reading order.

@item NodeBack
Previous node element unit in node reading order.

@item NodePrev
Previous node element unit.

@item NodeUp
Up node element unit.

@end table

@anchor{Element Direction Information Type}
@cindex Direction information type
@cindex Type, of direction information
The element directions also have types of information associated,
which are in general set dynamically depending on the current element
unit, for instance on the element unit whose navigation panel is being
formatted:

@table @code
@item href
A string that can be used as an href attribute linking to the element unit
corresponding to the direction.

@item string
A string representing the direction that can be used in
context where only entities are available (attributes).
@xref{Init File Expansion Contexts}.

@item text
A string representing the direction to be used in contexts
with HTML elements (preformatted and normal contexts).
@xref{Init File Expansion Contexts}.

@item tree
A Texinfo tree element representing the direction.

@item target
A string representing target of the direction, typically used as id
attribute in the element unit corresponding to the direction, and in href
attribute.

@item node
Same as @code{text}, but selecting the node associated with the element unit
direction in priority.

@item section
Same as @code{text}, but selecting the sectioning command
associated with the element unit direction in priority.

@end table

@code{text}, @code{tree} and @code{string} also have a variant with
@samp{_nonumber} prepended, such as @code{text_nonumber} without sectioning
command number in the representation.


@node Simple Navigation Panel Customization
@section Simple Navigation Panel Customization

@cindex Simple Customization, of navigation panel
@cindex Navigation panel, simple customization of

The @dfn{navigation panel} is the line of links (and labels) that
typically appears at the top of each node, so that users can easily
get to the next node, the table of contents, and so on.  It can be
customized extensively.

The customization variables
@code{VERTICAL_HEAD_NAVIGATION}, @code{ICONS}, @code{HEADERS},
@code{HEADER_IN_TABLE}, @code{USE_ACCESSKEY}, @code{USE_REL_REV} and
@code{WORDS_IN_PAGE}
may be used to change the navigation panel formatting.
@xref{HTML Customization Variables,,, texinfo, Texinfo}.

@cindex Navigation panel button specification
@cindex Button specification, navigation panel

Several arrays and hashes enable even more precise control over the navigation
panel buttons and their display.  They can be set as customization variables
with @code{texinfo_set_from_init_file}. @xref{Setting Main Program String
Variables}.

The following customization variables arrays determine the
buttons present in the various navigation panels:

@vtable @code
@item SECTION_BUTTONS
Specifies the navigation panel buttons present at the beginning of
sectioning elements.  If the output is split at nodes or sections,
they are also used at the page footer, and in the case of section
navigation being enabled, at the page header.

@item SECTION_FOOTER_BUTTONS
@itemx NODE_FOOTER_BUTTONS
These arrays specify the navigation panel buttons present in the page
footer when the output is split at sections or nodes, respectively.

@item CHAPTER_BUTTONS
Specifies the buttons appearing at the page footer if split at
chapters, and at the page header if split at chapters and there is no
section navigation.

@item MISC_BUTTONS
Specifies the buttons appearing at the beginning of special elements
and, if the output is split, at the end of such elements.

@item LINKS_BUTTONS
Used for @code{<link>} elements if they are output in the headers.

@item TOP_BUTTONS
Specifies the buttons used in the top element (@pxref{Output Element
Units}).
@end vtable

Each array specifies which buttons are included, and how they are
displayed.  Each array element is associated with a button of the
navigation panel from left to right.  The meaning of the array element
values is the following:

@anchor{Buttons Display}

@table @emph
@item string with an element unit direction
@vindex BUTTONS_TEXT
If icons are not used, the button is a link to the corresponding
element whose text is defined by the value associated with the element
direction in the hash associated with the @code{BUTTONS_TEXT} customization
variable, surrounded by @samp{[} and
@samp{]}. If the element direction is @samp{ }, the @samp{[} and @samp{]}
are omitted.

@vindex ACTIVE_ICONS
@vindex BUTTONS_NAME
@vindex PASSIVE_ICONS
@vindex BUTTONS_GOTO
@cindex Icons, in navigation buttons
If icons are used, the button is an image whose file is determined by
the value associated with the element direction in the
@code{ACTIVE_ICONS} variable hash if the link leads to an element, or in the
@code{PASSIVE_ICONS} variable hash if there is no element to link to.  If
there is a link to the element, the icon links to that element.  The
button name and button description are given as HTML attributes to
have a textual description of the icon.  The corresponding strings are
in the @code{BUTTONS_NAME} variable hash for the button name and
@code{BUTTONS_GOTO} variable hash for a more detailed description.

@item function reference
The function is called with one boolean argument, true if the
navigation panel should be vertical.  Should return the formatted
button text.

@item scalar reference
The scalar value is printed.

@item array reference of length 2
Here, the first array element should be a an element direction.
A link to the element unit associated with the element direction
is generated.  The text of the link depends on the second array element.

@table @emph
@item reference to a text string
In that case, the corresponding text is used.

@item reference to a function
The functions is called with two arguments, the converter object and the
element direction and should return two scalars, the link href and text and a boolean
set if a delimiter is needed after that button.

@item text string
The text string is interpreted as an element direction information type
and the corresponding text is used for the link.
@xref{Element Direction Information Type}.

For example, if the button array element is
@example
[ 'Next', 'node' ]
@end example

@noindent
Then the button will be a link to the next section with text
based on the name of the node associated with the next section element unit.

@end table

@end table

@anchor{Accesskey and @code{rel} Navigation}
@vindex BUTTONS_ACCESSKEY
@cindex @code{accesskey} navigation
If the customization variable @code{USE_ACCESSKEY} is set, the
@code{accesskey} attribute is used in navigation.  The
@code{BUTTONS_ACCESSKEY} customization variable hash is then used for the
@code{accesskey} attributes.

@vindex BUTTONS_REL@r{, for navigation}
@cindex @code{rel} navigation
Similarly, if the @code{USE_REL_REV} customization variable is set,
the @code{rel} attribute is used in navigation.  In that case the
@code{BUTTONS_REL} customization variable hash is used for the @code{rel}
attribute.


@node User Defined Functions
@chapter User Defined Functions

Getting beyond the customization described previously requires
writing some functions and registering those functions such that they
are called for the conversion. This allows dynamic redefinition
of functions used to produce output.


@node User Defined Functions are Registered
@section User Defined Functions are Registered

@cindex User defined functions, registering

User defined functions are always passed as a code reference to a registering
function, together with a string describing what the function formats.
In the following made up example, @code{my_formatting_function} is
passed as a function reference @code{\&my_formatting_function} to the
registering function @code{texinfo_register_command_formatting}, with
the string specifying the formatting done by the function being
@samp{format_thing}:

@example
sub my_formatting_function @{
  my $arg1 = shift;
  my $arg2 = shift;
  # prepare $formatted_text
  ...
  return $formatted_text;
@}

texinfo_register_command_formatting ('format_thing', \&my_formatting_function);
@end example

As such functions are defined by a reference name associated with a string
we will always use the string in function prototypes.  For the function arguments
we will use @code{\@@array} to indicate a reference to an array
(a.k.a.@: list, in Perl terminology), @code{\%hash} for a reference
to a hash and @code{\&function} for a reference on a function.

To illustrate these conventions, here is the prototype for the
function associated with @samp{format_thing}:

@deftypefn {Function Reference} @var{$text} format_thing (@var{$arg1}, @var{\@@arg2})
A function reference associated with @samp{format_thing} has a first argument
@var{$arg1}, a second argument a reference to an array @var{\@@arg2}, and
returns the formatted text @var{$text}.
@end deftypefn


@node Converter Object and Conversion Functions
@section Converter Object and Conversion Functions

The first argument of most, if not all user defined function is a converter
object.  This object gives access to methods to get information on the
conversion context and to methods useful for the conversion, both as an HTML
converter and as a generic @code{Texinfo::Convert::Converter}
(@pxref{Texinfo::Convert::Converter Helper methods,,,texi2any_internals}).  The
converter can also be used for error reporting as it is also a
@code{Texinfo::Report} object (@pxref{Texinfo::Report,,,texi2any_internals}),
and for in-document strings translation as it is also a
@code{Texinfo::Translations} object (@pxref{Texinfo::Translations,,,
texi2any_internals}).  @xref{Error Reporting in User Defined Functions} on
error reporting.


@node Texinfo Tree Conversion Functions
@subsection Texinfo Tree Conversion Functions

One important converter method that can be used in user defined functions
is @code{convert_tree} that convert a Texinfo tree rooted at any element.
There is no reason to use that function often, as the converter
already goes through the tree calling reference functions to convert
the elements, but it can be interesting in some cases.

@deftypefun {@var{$converted_text} =} @var{$converter}->convert_tree (@var{\%element}, @var{$explanation})
@var{\%element} is a Texinfo tree element. @var{$explanation} is
optional, it is a string explaining why the function was called, to help
in case of debugging.  The function returns @var{\%element} converted.
@end deftypefun

@code{convert_tree} is suitable when the conversion is in the flow of the Texinfo
tree conversion.  Sometime, it is better to ignore the formatting context
of the main conversion, for example for the formatting of a caption, or the formatting
of footnotes texts.  Another special case is the case of tree elements being converted
more than once, even if in the flow of the Texinfo tree conversion, for example
if there are multiple @code{@@insertcopying} in a document.  A last special case arise,
with formatting done in advance or out of the main conversion.  This is the case, in practice, for
sectioning commands or node commands which may be formatted as directions in navigation
panels, menus or indices, may appear more than once in the document and be
converted more than once, if language changes, for example.

For such cases, the function is
@code{convert_tree_new_formatting_context} which sets the context appropriately.
@code{convert_tree_new_formatting_context} ultimately calls @code{convert_tree}.

@deftypefun {@var{$converted_text} =} @var{$converter}->convert_tree_new_formatting_context @
      (@var{\%element}, @var{$context}, @var{$multiple_pass}, @var{$global_context})
@var{\%element} is a Texinfo tree element.  @var{$context} is an optional
string describing the new context to be setup to format out of the main
conversion flow.  If not defined, the conversion is done in the main document
flow.  @var{$multiple_pass} is an optional string that marks that the
conversion is done more than once.  It should be unique and suitable for
inclusion in targets and identifiers.  @var{$global_context} is an optional
string that marks that the formatting may be done in advance, and can be
redone.

The function returns @var{\%element} converted, setting the conversion context
according to the arguments.
@end deftypefun

@xref{Setting the Context for Conversion} on how to set a specific context for
a Texinfo tree conversion.


@node Internationalization of Strings Function
@subsection Internationalization of Strings Function

@quotation Warning
There is no possibility to provide custom translations for selected
strings, such that only translated strings already recorded in
the default code can be used in practice.
@end quotation

@vindex texinfo_document @r{Gettext domain}
The subroutine @code{gdt}, from the @code{Texinfo::Translations} module
is used for translated strings:

@deftypefun {@var{$translated_tree} =} @var{$converter}->gdt (@var{$string}, @var{\%variables_hash})
@var{$string} is the string to be translated, @var{\%variables_hash}
is a hash reference holding the variable parts of the translated
string.  The result returned is a perl Texinfo tree.
@end deftypefun

When the string is expanded as Texinfo, and converted to a
Texinfo tree in perl, the arguments are substituted; for
example, @samp{@{arg_name@}} is replaced by the corresponding
actual argument, which should be Texinfo perl trees, Texinfo
perl tree contents arrays or strings.

In the following example, @samp{@{date@}}, @samp{@{program_homepage@}}
and @samp{@{program@}} are the arguments of the string.  Since they
are used in @code{@@uref}, their order in the formatted output depends on
the formatting and is not predictable.
@samp{@{date@}}, @samp{@{program_homepage@}} and @samp{@{program@}} are
substituted after the expansion, which means that they should already be
Texinfo perl trees, Texinfo perl tree contents.  A string is turned
into a Texinfo text element without type, with the string as @code{text}.

@example
  $converter->gdt('Generated @@emph@{@@today@{@}@} using '
   .'@@uref@{@{program_homepage@}, @@emph@{@{program@}@}@}.',
      @{ 'program_homepage' => $converter->get_conf('PACKAGE_URL'),
        'program' => @{ 'text' => $converter->get_conf('PROGRAM') @}@}));
@end example

In the example, the @code{$converter->get_conf('PACKAGE_URL')} string is turned
into @code{@{ 'text' => $converter->get_conf('PACKAGE_URL')  @}}.

An example of combining conversion with translation:
@example
$converter->convert_tree($converter->gdt(
       '@{explained_string@} (@{explanation@})',
       @{'explained_string' => @{'type' => '_converted',
                               'text' => $result@},
        'explanation' => @{'type' => '_converted',
                          'text' => $explanation_result@}@}),
                         "convert explained $cmdname");
@end example

@xref{Texinfo::Translations,,,texi2any_internals} for more
on @code{Texinfo::Translations}.
@xref{Internationalization of Document Strings,,, texinfo, Texinfo} for an
overview.


@node Error Reporting in User Defined Functions
@subsection Error Reporting in User Defined Functions

@cindex Error reporting @subentry conversion
@cindex @code{Texinfo::Report}

To report an error or a warning in a user defined function, use the methods
of @code{Texinfo::Report} through a converter object
(@pxref{Converter Object and Conversion Functions}).

To report a warning or an error not specific of an element conversion,
use @code{document_warn} or @code{document_error}:

@defun @var{$converter}->document_error ($text, $converter)
@defunx @var{$converter}->document_warn ($text, $converter)
Register a document-wide error or warning.  @var{$text} is the error
or warning message.  The @var{$converter} object should be given
as the second argument.
@end defun

To report a warning or an error in element conversion, use
@code{line_warn} or @code{line_error}
@defun @var{$converter}->line_error ($text, $converter, $location_info)
@defunx @var{$converter}->line_warn ($text, $converter, $location_info)
Register a warning or an error.  @var{$text} is the text of the
error or warning.  The @var{$converter} object should be given
as the second argument.  The optional
@var{$error_location_info} holds the information on the error or
warning location.  The @var{$error_location_info} reference on hash may be
obtained from Texinfo elements @code{source_info} keys.
@end defun

In general, registering an error does not stop the processing, in
particular it does not stop the main conversion of the Texinfo tree.
Write initialization files as if the conversion always continued
after registering the error.

@xref{Texinfo::Report,,,texi2any_internals} for more on
@code{Texinfo::Report}.
@c @xref{Init File Calling at Different Stages} for information on how
@c to stop the processing from user defined functions called at different
@c stages.


@node Texinfo Tree Elements in User Defined Functions
@section Texinfo Tree Elements in User Defined Functions

Many user defined functions used for formatting have Texinfo tree elements
as arguments.  The user defined code should never modify the tree elements.
It is possible to reuse Texinfo tree elements information, but with
a copy.  For example, the following is ok:

@example
my @@contents = @@@{$element->@{'contents'@}@};
push @@contents, @{'text' => ' my added text'@};
my $result = $converter->convert_tree(@{'cmdname' => 'strong',
                                  'contents' => \@@contents @});
@end example

The following is not ok:

@example
push @@@{$element->@{'contents'@}@}, @{'text' => ' my added text'@};
@end example

In addition to the elements obtained after parsing a Texinfo
document, two elements are added,
@code{unit} type elements that correspond to the normal document units
(@pxref{Output Element Units}), and special elements with type
@code{special_element} that correspond to added special elements (@pxref{Output
Element Units}).  These added elements, as well as nodes and sectioning elements
hold information on the document structure in the @code{structure} element hash
(@pxref{Texinfo::Structuring METHODS,,,texi2any_internals}).

Normal tree unit elements have a @code{unit_command} key in the
@code{extra} hash that points to the associated @code{@@node} or
sectioning @@-command depending on which of nodes or sectioning commands
are the main components of elements. @xref{Output Element Units}.

The following keys of the @code{structure} hash can be interesting:

@cindex Document structure

@table @code
@item associated_unit
For sectioning and @code{@@node} @@-command elements.  The associated
tree unit element.

@item section_childs
For sectioning commands elements.  The children of the sectioning element
in the sectioning tree.

@item section_level
The level of the section, taking into account @code{@@raisesections} and
@code{@@lowersections}.  Level 0 corresponds to @code{@@top} or @code{@@part}
and level 1 to @code{@@chapter} level sectioning commands.
@xref{Raise/lower sections,,, texinfo, Texinfo}.

@item unit_filename
For tree unit elements. The associated file name.

@item unit_next
For tree unit elements. The next unit element in document order.

@item unit_prev
For tree unit elements. The previous unit element in document order.
@end table


Detailed information on the tree elements is available in the Texinfo Parser
documentation, in particular a list of types and of information in the elements
@code{extra} hash (@pxref{Texinfo::Parser TEXINFO TREE,,,texi2any_internals}).


@node Encoding and Decoding File Path Strings
@section Encoding and Decoding File Path Strings


@node Encoding File Path Strings
@subsection Encoding File Path Strings

In general, the strings in the customization functions are character strings.  For most purposes,
this is right, and the encoding in output files is taken care of by the converter.
Operations on directories and file names, however, such as the creation of a directory
or the opening of a file require binary strings.

To encode file names consistently with file name encoding used in the conversion to
HTML, there is a function @code{encoded_output_file_name}:

@deftypefun {(@var{$encoded_name}, @var{$encoding}) =} @var{$converter}->encoded_output_file_name (@var{$character_string_name})
Encode @var{$character_string_name} in the same way as other file name are
encoded in the converter, based on @code{DOC_ENCODING_FOR_OUTPUT_FILE_NAME},
and @code{LOCALE_OUTPUT_FILE_NAME_ENCODING} or on input file encoding
(@pxref{Other Customization Variables,,, texinfo, Texinfo}).  Return the
encoded name and the encoding used to encode the name.
@end deftypefun

There is also a similar function for the input file names encoding,
@code{encoded_input_file_name}, which uses
@code{DOC_ENCODING_FOR_INPUT_FILE_NAME} and
@code{LOCALE_INPUT_FILE_NAME_ENCODING} and is less likely to be useful.

When calling external commands, the command line arguments should also
be encoded.  To do similarly with other codes, the customization variable
@code{MESSAGE_ENCODING} should be used.  Already encoded file
names may be used.  For example

@example
use Encode qw(encode);

....

my ($encoded_file_path, $encoding)
  = $converter->encoded_output_file_name($file_name);

my $fh = open($encoded_file_path);

.....

my $call_start = "command --set '$action' ";
my $encoding = $converter->get_conf('MESSAGE_ENCODING');
if (defined($encoding)) @{
  $encoded_call_start = encode($encoding, $call_start);
@} else @{
  $encoded_call_start = $call_start;
@}
my $encoded_call = $encoded_call_start . $encoded_file_path;
my $call = $call_start . $file_name;
if (system($encoded_call)) @{
 $converter->document_error($converter,
     sprintf(__("command did not succeed: %s"),
            $call));
@}
@end example


@node Decoding File Path Strings
@subsection Decoding File Path Strings

The binary strings that could be accessed correspond to the customization
variables strings or arrays @code{INCLUDE_DIRECTORIES}, @code{CSS_FILES},
@code{MACRO_EXPAND} and @code{INTERNAL_LINKS}.  If they need to be decoded into
character strings, for example to appear in error messages, it is possible to
use the @code{COMMAND_LINE_ENCODING} customization variable value as
encoding name to mimic how the decoding of these strings from the command line
is done in the main program and in the converters.  For example:

@example
my $macro_expand_fname = $self->get_conf('MACRO_EXPAND');
my $encoding = $self->get_conf('COMMAND_LINE_ENCODING');
if (defined($encoding)) @{
  $macro_expand_fname = Encode::decode($encoding, $macro_expand_fname);
@}
@end example

More information on perl and encodings in
@uref{https://perldoc.perl.org/perlunifaq, perlunifaq}.


@node Setting the Context for Conversion
@section Setting the Context for Conversion

Special container types are recognized by the converter and can
be used to convert a Texinfo tree in a specific context.  Those
types cannot appear in a regular Texinfo tree.  They can be the
type directly associated with a text element, or the type of a tree
root element.

The types are:

@table @code
@item _code
In this container, the conversion is done in a code context
@xref{Init File Expansion Contexts}.

@item _converted
In this container, the texts are considered to be already formatted.
This is more likely to be relevant as the type of a text element.

@item _string
In this container, the conversion is done in a string context.
@xref{Init File Expansion Contexts}.

@end table

These contexts are typically used together with converter conversion
functions (@pxref{Converter Object and Conversion Functions}).
For example:

@example
my @@contents = @@@{$element->@{'contents'@}@};
push @@contents, @{'text' => ' <code>HTML</code> text ',
                   'type' => '_converted'@};
my $result = $converter->convert_tree(@{'type' => '_code',
                                  'contents' => \@@contents @});
@end example

There is no context for plain text, but the conversion to plain
text can be achieved by using the @code{Texinfo::Text} converter
(@pxref{Texinfo::Convert::Text,,,texi2any_internals}).  For example,
to convert the Texinfo tree element @var{$element} to plain text:

@example
my $plaintext = Texinfo::Convert::Text::convert_to_text($element,
  Texinfo::Convert::Text::copy_options_for_convert_text($converter, 1));
@end example

@node Conversion Customization Variables
@section Setting and Getting Conversion Customization Variables

The customization variables values set during the conversion process may be
different from the main program customization variables.  The general rule is
that variables set in the main program, in particular from init files, are
passed to the converter.  Some variables, however, only appear in the
converter. Some variables are also set in the converter based on the main
program customization variables.  Finally, some variables should be set or reset
during conversion, in particular when converting the tree representing the
Texinfo document, when expanding the tree element corresponding to @@-commands
associated with customization variables.

The functions described here should be used in user defined functions, but
should not be used out of functions. Conversly, the similar functions used to
set customization variables from init files without a converter should not be
used in functions, but should be used out of functions in init files
(@pxref{Managing Customization Variables}).

To get the value of a variable in a converter @code{$converter},
the function is @code{get_conf}:

@defun @var{$converter}->get_conf ($variable_name)
@var{$variable_name} is the name of the variable; its value in the converter
@var{$converter} (possibly @code{undef}) is returned.
@end defun

For example:

@example
my $footnotestyle = $converter->get_conf('footnotestyle');
@end example

To set a variable in a converter @code{$converter},
the function is @code{set_conf}:

@defun @var{$converter}->set_conf ($variable_name, $variable_value)
@var{$variable_name} is the name of the variable; its value in the converter
@var{$converter} is set to @var{$variable_value}.  The @var{$variable_name}
value will not be overidden if it was set from the command line or from an init
file.
@end defun

For example:

@example
$converter->set_conf('footnotestyle', 'separate');
@end example

Some customization variables, in particular those associated with @@-commands,
can be reset to the value they had before starting the conversion.  For
example, they are reset in order to obtain their value before the conversion.
Thet are also reset to the value they had before starting the conversion when
their value at the end of the preambule or at the end of the document is
needed, but there are no @@-commands at those locations in the Texinfo manual.
If a value set by @code{set_conf} is intended to be found when the
customization variable value is reset, @code{set_conf} should be called early.
For example, when called from a user-defined function called at different
stage, it should be called in the @samp{setup} stage (@pxref{Init File Calling
at Different Stages}).

The values set in converter with @code{set_conf} will not override command-line
set customization variables, nor variables set early in init files.  This is the
expected behaviour, in particular when the values are set from the document.
In the rare cases when overriding the customization would be needed, the
@code{force_conf} functions can be used:

@defun @var{$converter}->force_conf ($variable_name, $variable_value)
@var{$variable_name} is the name of the variable; its value in the converter
@var{$converter} is set to @var{$variable_value}, overriding any previous value.
@end defun


@node Conversion General Information
@section Conversion General Information

Some general information is available from the converter.

To determine if an output format such as @samp{html} or @samp{tex}
is expanded (@pxref{Conditional Commands,,, texinfo, Texinfo}), use
@code{is_format_expanded}:

@deftypefun {@var{$is_format_expanded} =} @var{$converter}->is_format_expanded (@var{$format})
Return true if format @var{$format} is expanded, according to
command-line and init file information.
@end deftypefun

The main method to get information from the converter is @code{get_info}:

@deftypefun {@var{$info} =} @var{$converter}->get_info (@var{$item})
Return information on @var{$item}.
@end deftypefun

The available information is about:
@table @code
@item copying_comment
Text appearing in @code{@@copying} with all the Texinfo commands
put into comments (@pxref{@code{@@copying},,, texinfo, Texinfo}).

@item current_filename
The file name of the current document unit being converted.

@item destination_directory
Destination directory for the output files.  It is common to use that string in directory
or file paths with functions requiring binary strings.  In that case the
character string needs to be encoded.  @xref{Encoding File Path Strings}.

@item document_name
Base name of the document.  It is common to use that string in in directory or
file paths with functions requiring binary strings.  In that case the character
string needs to be encoded.  @xref{Encoding File Path Strings}.

@item documentdescription_string
@code{@@documentdescription} argument converted in a string context
(@pxref{@code{@@documentdescription},,, texinfo, Texinfo}).  @xref{Init File
Expansion Contexts}.

@item floats
Information on floats. Gathered from the Texinfo parsing result.
@xref{Texinfo::Parser $float_types = floats_information($parser),,
Texinfo::Parser::floats_information,texi2any_internals}.

@item global_commands
Global commands information.  Gathered from the Texinfo parsing result.
@xref{Texinfo::Parser $commands = global_commands_information($parser),,
Texinfo::Parser::global_commands_information,texi2any_internals}.

@item index_entries
Information on indices taking into account merged indices.
@xref{Texinfo::Structuring $merged_entries = merge_indices($index_names),,Texinfo::Structuring::merge_indices, texi2any_internals}.

@item index_entries_by_letter
Index entries sorted by letter. @xref{Texinfo::Structuring ($index_entries_sorted@comma{} $index_entries_sort_strings) = sort_indices($registrar@comma{} $configuration_information@comma{} $merged_index_entries@comma{} $sort_by_letter),,Texinfo::Structuring::sort_indices,texi2any_internals}.

@item jslicenses
An hash reference with  categories of javascript used in the document
as keys. The corresponding values are also hashes with file names
as keys and with array references as values.  The array references contain
information on each of the file licences, with content
@enumerate
@item licence name
@item license url
@item file name or source of file
@end enumerate

@item line_break_element
HTML line break element, based on @samp{<br>}, also taking into account
@code{USE_XML_SYNTAX} customization variable value.

@item non_breaking_space
Non breaking space, can be @samp{&nbsp;}, but also a non breaking
space character or the corresponding numeric entity based on
@code{ENABLE_ENCODING} and @code{USE_NUMERIC_ENTITY} customization variables
values.

@item paragraph_symbol
Paragraph symbol, can be @samp{&para;}, but also the corresponding numeric entity
or encoded character based on @code{ENABLE_ENCODING} and
@code{USE_NUMERIC_ENTITY} customization variables values.

@item title_string
@item title_tree
@item simpletitle_tree
@item simpletitle_command_name
Some information is deduced from the title commands:
@dfn{simpletitle} reflects @code{@@settitle} vs.@:
@code{@@shorttitlepage}, and @dfn{title} is constructed by trying
all the title-related commands, including @code{@@top} and
@code{@@titlefont}, in the top element.

@code{title_tree} is a Texinfo tree corresponding to the title,
@code{title_string} is the result of the conversion in a string context
(@pxref{Init File Expansion Contexts}).  @code{simpletitle_tree} is
a Texinfo tree corresponding to the simpletitle, and @code{simpletitle_command_name}
is the @@-command name used for the simpletitle, without the leading @@.

@item structuring
Information on the document structure.  Gathered before the conversion.
Two hash keys correspond to interesting information, @code{sectioning_root}
which points to the top level sectioning command tree element, and
@code{sections_list} which holds the list of the sectioning commands in the
document.

@item title_titlepage
The formatted title, possibly based on @code{@@titlepage}, or on
@code{simpletitle_tree} and similar information, depending on @code{SHOW_TITLE}
and @code{USE_TITLEPAGE_FOR_TITLE} customization variables in the default case.

@end table

@xref{Simple Customization of CSS} for an explanation on getting
information on CSS.


@node Customizing Output-Related Names
@chapter Customizing Output-Related Names

It is possible to control both output file names and target
identifiers in detail.

User defined functions customizing
file names and targets are registered with
@code{texinfo_register_file_id_setting_function}:

@defun texinfo_register_file_id_setting_function ($customized, \@ampchar{}handler)
@var{$customized} is a string describing what the function
should set.  @var{\&handler} should be a reference on the user
defined function.  The different functions that can be registered
have different arguments and return values.
@end defun

The different possibilities for the customized information
are explained in the next sections.

For example:
@example
sub my_node_file_name($$$) @{
  my ($converter, $element, $filename) = @@_;
  # ....
  return $node_file_name
@}

texinfo_register_file_id_setting_function('node_file_name',
                                          \&my_node_file_name);
@end example

@menu
* File: Customizing Output File Names.
* Target: Customizing Output Target Names.
@end menu


@node Customizing Output File Names
@section Customizing Output File Names

@cindex Customizing output file names
@cindex Output file names, customizing

@vindex PREFIX
@vindex SUBDIR
@vindex EXTENSION
It is possible to specify the output file names with more control than
merely the command line option @option{--output} (@pxref{Invoking
@command{texi2any},,, texinfo, Texinfo}). The @code{PREFIX} customization
variable overrides the base name of the file given by @code{@@setfilename} or
the file name and should not contain any directory components.  To alter
intermediate directories, use the @code{SUBDIR} customization variable.
Finally, the extension may also be overriden by the customization variable
@code{EXTENSION}.  This variable should be @code{undef} if no extension is to
be added.

@vindex TOP_FILE
Furthermore, the customization variables @code{TOP_FILE} override
the output file name for the top element.

Two function references registered with @code{texinfo_register_file_id_setting_function}
enable further customization.  The first,
@code{node_file_name} is used to customize the nodes files names.

@deftypefn {Function Reference} @var{$node_file} node_file_name (@var{$converter}, @
                                      @var{\%node_element}, @var{$file_name})
@var{$converter} is a converter object.  @var{\%node_element} is the Texinfo tree
element corresponding to the @code{@@node}.  @var{$file_name} is the node file
name that has been already set.  The function should return the node file name
(@var{$node_file}).
@end deftypefn

The other function reference, @code{tree_unit_file_name}, is used to
customize the file names associated with each element unit, and the name of
the file associated with the special elements (@pxref{Output Element
Units}).

@deftypefn {Function Reference} {(@var{$file}, @var{$path})} tree_unit_file_name (@var{$converter}, @
                  @var{\%unit_element}, @var{$file_name}, @var{$file_path})
@var{$converter} is a converter object.  @var{\%unit_element} is the Texinfo
element corresponding to the unit element.  @var{$file_name} is the file
name that has been already set.  @var{$file_path} is the file path that has
been already set.  @var{$file_path} is @samp{undef} if the file is relative to
the output directory, which is the case if the output is split.  The
function should return the file name for the unit element, @var{$file}, and the
file path for the unit element, @var{$path}, which should be @samp{undef} if
the file path is to be constructed by putting @var{$file} in the destination
directory.
@end deftypefn

In the user defined functions, the information that a unit element
is associated with @code{@@top} or @code{@@node Top} or more generally
considered to be the Top element may be determined with
@example
$converter->element_is_tree_unit_top(\%unit_element);
@end example

The information on tree elements may be interesting for those functions
(@pxref{Texinfo Tree Elements in User Defined Functions}).  The @code{extra}
key @code{associated_section} of a node element and @code{associated_node}
of a sectioning command element may also be useful.


@node Customizing Output Target Names
@section Customizing Output Target Names

@cindex Customizing output target names
@cindex Target names, customizing
@cindex Id names, customizing

Similar to file names, so-called target and id names may be set.  The
@dfn{id} is placed where the item is located, while the @dfn{target}
is used to construct references to that item.  The id and target
are the same.  Functions used to set both targets and file names are also
described here.

@c xx, but not always, for example in the default case, the
@c xx target for a section is the node id.

The following function reference is for target items (nodes, anchors,
floats):

@deftypefn {Function Reference} @var{$target} label_target_name @
           (@var{$converter}, @var{\%label_info}, @var{$default_target})
@var{$converter} is a converter object.  @var{\%label_info} is a hash
reference containing a @code{normalized} key with value the
normalized node name, a @code{node_content} key with value a reference on an
array containing the Texinfo tree contents of the command label.
@var{$default_target} is the target that has been already set.  The function
should return the target (@var{$target}).
@end deftypefn

The element corresponding to the label can be found with @code{label_command}
(@pxref{Target Commands Links@comma{} Texts and Associated Commands}):
@example
my $element;
$element = $converter->label_command($label_info->@{'normalized'@})
  if (defined($label_info->@{'normalized'@}));
@end example

For sectioning commands, in addition to the sectioning command target,
targets for the sectioning command in table of contents and in short table
of contents are needed. The following function reference is for sectioning command related
target and file name:

@deftypefn {Function Reference} {(@var{$target}, @var{$target_contents}, @var{$target_shortcontents}, @var{$file})} @
 sectioning_command_target_name (@var{$converter}, @var{\%section_element}, @var{$default_target}, @
    @var{$default_target_contents}, @var{$default_target_shortcontents}, @var{$file_name})
@var{$converter} is a converter object. @var{\%section_element} is the Texinfo
element corresponding to the sectioning command.

@var{$default_target}, @var{$default_target_contents} and
@var{$default_target_shortcontents} are the targets that have been already set
for the sectioning element and the sectioning element in table of contents and in
short table of contents.  @var{$file_name} is the file name that has been already set.

The function should return the @var{$target}, @var{$target_contents} and
@var{$target_shortcontents} sectioning element target and sectioning element in
table of contents and in short table of contents targets, and the file name for
the sectioning element (@var{$file}).
@end deftypefn


For special element units (@pxref{Output Element Units}), the function
reference is:

@deftypefn {Function Reference} {(@var{$target}, @var{$file})} special_element_target_file_name @
           (@var{$converter}, @var{\%element}, @var{$default_target}, @var{$file_name})
@var{$converter} is a converter object. @var{\%element} is the Texinfo
element corresponding to the special element unit. @var{$default_target} is the
target that has been already set, and @var{$file_name} is the
file name that has been already set. The function should return the @var{$target}
and @var{$file}.
@end deftypefn


@node Init File Calling at Different Stages
@chapter Init File Calling at Different Stages

@cindex Init file calling functions at different stages
@cindex Calling functions at different stages
@cindex Functions, calling at different stages

Arbitrary user-defined functions may be called during conversion.
This could be used, for example, to initialize variables and collect
some @@-commands text, and doing clean-up after the Texinfo tree
conversion.

There are four places for user defined functions:
@table @code
@item setup
Called right after completing main program customization information
with converter specific customization information, but before anything else is
done, including collecting the output files names and registering the
customization variables pre-conversion values.
@c the information on input file names directories is probably available
@c somewhere, but we do not want those to be used, in general, rather
@c we mostly want document_name to be used
@c  The input file names'directories are available.

@item structure
Called after setting and determining information on CSS, output files and directories,
document structure and associated directions, file names, labels and links for nodes,
sectioning commands, special elements, footnotes and index entries.

@item init
Called after some gathering of global information on the document,
such as titles, copying comment and document description, which
require some conversion of Texinfo, right before the main output processing.
At that point most of the information available from the converter is set
(@pxref{Conversion General Information}).

@item finish
Called after output generation is finished.
@end table

The function used to register a user defined functions is
@code{texinfo_register_handler}:

@defun texinfo_register_handler ($stage, \@ampchar{}handler, $priority)
@var{$stage} is one of the stages described just above. @var{\&handler}
is a reference on the user defined function. @var{$priority}
is an optional priority class.

To determine the order of
user defined functions calls, the priority classes are sorted, and
within a priority class the order is the order of calling
@code{texinfo_register_handler}.
@end defun

The call of the user defined functions is:

@deftypefn {Function Reference} @var{$status} stage_handler @
           (@var{$converter}, @var{\%tree}, @var{$stage})
@var{$converter} is a converter object. @var{\%tree} is the Texinfo
tree root element. @var{$stage} is the current stage.

If @var{$status} is not 0 it means that an error occured.
If @var{$status} is positive, the user defined functions should
have registered an error or warning message, for example with
@code{document_error} (@pxref{Error Reporting in User Defined Functions}).
If @var{$status} is negative, the converter will emit a non specific
error message.  If the @var{$status} is lower than
-@code{HANDLER_FATAL_ERROR_LEVEL} or
higher than @code{HANDLER_FATAL_ERROR_LEVEL}, the processing stops
immediately.  Default value for @code{HANDLER_FATAL_ERROR_LEVEL}
is 100.
@end deftypefn


@node User Defined Functions in Conversion
@chapter User Defined Functions in Conversion

Full customization of output is achieved with replacing default
formatting functions with user defined functions.  There
are two broad classes of functions, the @dfn{conversion} functions used
for elements of the Texinfo tree, and other @dfn{formatting} functions with
diverse purposes, including formatting that are not based on
tree elements (for example beginning and end of file formatting).


@node Tree Element Conversion Functions
@section Tree Element Conversion Functions

Functions used for tree elements associated with @@-commands are
considered separately from functions used for tree elements not
associated with @@-commands, which includes containers with a type
and text.  There are two functions for each element command or
type, one called when the element is first encountered, and the other
called after formatting the contents of the element.  The actual
conversion is usually done after formatting the contents of the element,
but it may sometime be necessary to have some code run when
the element is first encountered.


@node Command Tree Element Opening Functions
@subsection Command Tree Element Opening Functions

User defined functions called when an @@-command element is first encountered are registered
with @code{texinfo_register_command_opening}:

@defun texinfo_register_command_opening ($command_name, \@ampchar{}handler)
@var{$command_name} is an @@-command name, with the leading @@.
@var{\&handler} is the user defined function reference.
@end defun

The call of the user defined functions is:

@deftypefn {Function Reference} @var{$text} command_open @
           (@var{$converter}, @var{$command_name}, @var{\%element})
@var{$converter} is a converter object. @var{$command_name}
is the @@-command name without the @@. @var{\%element} is the Texinfo
element.

The @var{$text} returned is prepended to the formatting of the
@@-command.
@end deftypefn

It is possible to have access to the default opening function reference.
The function used is:
@deftypefun {@var{\&default_command_open} =} @var{$converter}->default_command_open (@var{$command_name})
@var{$command_name} is the @@-command name without the @@. Returns the
default opening function reference for @var{$command_name}, or undef if there is none.
@end deftypefun


@node Command Tree Element Conversion Functions
@subsection Command Tree Element Conversion Functions

User defined functions called for an @@-command element conversion, after
arguments and contents have been formatted, are registered with
@code{texinfo_register_command_formatting}:

@defun texinfo_register_command_formatting ($command_name, \@ampchar{}handler)
@var{$command_name} is an @@-command name, with the leading @@.
@var{\&handler} is the user defined function reference.
@end defun

The call of the user defined functions is:
@deftypefn {Function Reference} @var{$text} command_conversion  @
           (@var{$converter}, @var{$command_name}, @var{\%element}, @var{\@@args}, @var{$content})
@var{$converter} is a converter object. @var{$command_name}
is the @@-command name without the @@. @var{\%element} is the Texinfo
element.

@var{\@@args}, if defined, is a reference on the formatted arguments
of the @@-command. Each of the array items correspond to each of
the @@-command argument. Each array item is a hash references, with keys
corresponding to possible argument formatting contexts:

@table @code
@item normal
Argument formatted in a normal context

@item monospace
Argument formatted in a context where spaces are kept as is, as well as
quotes and minus characters, for instance in @samp{--} and @samp{``}.  Both
in preformatted and code context.  @xref{Init File Expansion Contexts}.

@item monospacestring
Same as monospace, but in addition in string context. @xref{Init File Expansion Contexts}.

@item monospacetext
Same as monospace, but in addition the argument is converted to plain
text.  @xref{Converter Object and Conversion Functions}.

@item raw
Text is kept as is, special HTML characters are not protected.  Appears only
as @code{@@inlineraw} second argument.

@item string
In string context. @xref{Init File Expansion Contexts}.

@item tree
The Texinfo tree element corresponding to the argument.
@xref{Texinfo Tree Elements in User Defined Functions}.

@item url
Similar with monospacetext.  The difference is that UTF-8 encoding is always
used for the conversion of accented and special insertion @@-commands to plain
text.  This is best for percent encoding of url, which should always be
produced from UTF-8 encoded strings.

@end table

The formatted arguments contexts depend on the @@-command, there could be none,
for @code{@@footnote} argument which is not directly converted where the
footnote command is, or multiple, for example for the fourth argument of
@code{@@image} which is both available as @samp{normal} and
@samp{string}.

For example, @code{$args->[0]->@{'normal'@}} is the first argument converted in
normal context.

@var{$content} is the @@-command formatted contents.  It corresponds to the
contents of block @@-commands, and to Texinfo code following @code{@@node},
sectioning commands, @code{@@tab} and @code{@@item} in @code{@@enumerate} and
@code{@@itemize}.  @var{$content} can be @code{undef} or the empty string.

The @var{$text} returned is the result of the @@-command conversion.
@end deftypefn

To call a conversion function from user defined code, the function reference
should first be retrieved using @code{command_conversion}:

@deftypefun {@var{\&command_conversion} =} @var{$converter}->command_conversion (@var{$command_name})
@var{$command_name} is the @@-command name without the @@. Returns the
conversion function reference for @var{$command_name}, or undef if there is none,
which should only be the case for @@-commands ignored in HTML not defined by the user.
@end deftypefun

for example, to call the conversion function for the @code{@@tab} @@-command,
passing arguments that may correspond to another @@-command:
@example
&@{$converter->command_conversion('tab')@}($converter, $cmdname,
                                     $command, $args, $content);
@end example

It is possible to have access to the default conversion function reference.
The function used is:

@deftypefun {@var{\&default_command_conversion} =} @var{$converter}->default_command_conversion (@var{$command_name})
@var{$command_name} is the @@-command name without the @@. Returns the
default conversion function reference for @var{$command_name}, or undef if there is none,
which should only be the case for @@-commands ignored in HTML.
@end deftypefun


@node Type Tree Element Opening Functions
@subsection Type Tree Element Opening Functions

User defined functions called when an element without @@-command
with a container type is first encountered are registered
with @code{texinfo_register_type_opening}:

@defun texinfo_register_type_opening ($type, \@ampchar{}handler)
@var{$type} is the element type.
@var{\&handler} is the user defined function reference.
@end defun

The call of the user defined functions is:

@deftypefn {Function Reference} @var{$text} type_open (@var{$converter}, @
        @var{$type}, @var{\%element})
@var{$converter} is a converter object. @var{$type} is the element type.
@var{\%element} is the Texinfo
element.

The @var{$text} returned is prepended to the formatting of the
type container.
@end deftypefn

It is possible to have access to the default opening function reference.
The function used is:
@deftypefun {@var{\&default_type_open} =} @var{$converter}->default_type_open (@var{$type})
@var{$command_name} is the element type. Returns the
default opening function reference for @var{$type}, or undef if there is none.
@end deftypefun


@node Type Tree Element Conversion Functions
@subsection Type Tree Element Conversion Functions

User defined functions called for the conversion of an element without
@@-command with text or a container type are registered with
@code{texinfo_register_type_formatting}.  For containers, the user defined
function is called after conversion of the content.

@defun texinfo_register_type_formatting ($type, \@ampchar{}handler)
@var{$type} is the element type.
@var{\&handler} is the user defined function reference.
@end defun

The call of the user defined functions is:

@deftypefn {Function Reference} @var{$text} type_conversion (@var{$converter}, @
        @var{$type}, @var{\%element}, @var{$content})
@var{$converter} is a converter object. @var{$type} is the element type.
@var{\%element} is the Texinfo element.  @var{$content} is text for elements
associated with text, or the formatted contents for other elements.
@var{$content} can be @code{undef} or the empty string.

The @var{$text} returned is the result of the @@-command conversion.
@end deftypefn

To call a conversion function from user defined code, the function reference
should first be retrieved using @code{type_conversion}:

@deftypefun {@var{\&type_conversion} =} @var{$converter}->type_conversion (@var{$type})
@var{$type} is the element type.  Returns the
conversion function reference for @var{$type}, or undef if there is none,
which should only be the case for types ignored in HTML not defined by the user.
@end deftypefun

It is possible to have access to the default conversion function reference.
The function used is:

@deftypefun {@var{\&default_type_conversion} =} @var{$converter}->default_type_conversion (@var{$type})
@var{$type} is the element type.  Returns the
default conversion function reference for @var{$type}, or undef if there is none,
which should only be the case for types ignored in HTML.
@end deftypefun


@node Formatting Functions
@section Formatting Functions

Most formatting functions are specific, with specific arguments,
and a specific item formatted.

User defined functions associated with
the formatting of special elements body (@pxref{Output Element Units})
are handled separately.

The formatting functions are often called from function that can be
replaced by a user defined function, therefore these functions may
not be called if the replacement functions do not keep a similar
operation.


@node Specific formating Functions
@subsection Specific formating Functions

User defined formatting functions are registered with
@code{texinfo_register_formatting_function}:

@defun texinfo_register_formatting_function ($formatted, @
                            \@ampchar{}handler)
@var{$formatted} is a string describing the formatting
function. @var{\&handler} is the user defined function reference.
@end defun

To call a formatting function from user defined code, the
function reference should first be retrieved using @code{formatting_function}:

@deftypefun {@var{\&formatting_function} =} @var{$converter}->formatting_function (@var{$formatted})
@var{$formatted} is a string describing the formatting
function. Returns the associated formatting function reference.
@end deftypefun

It is possible to have access to the default formatting function reference.
The function used is:

@deftypefun {@var{\&default_formatting_function} =} @var{$converter}->default_formatting_function (@var{$formatted})
@var{$formatted} is a string describing the formatting
function. Returns the default formatting function reference.
@end deftypefun

The string that should be used to register or call each of the formatting functions
and the call of the formatting functions are documented in the following sections of
the manual, depending on where they are relevant.


@node Special Element Body Formatting Functions
@subsection Special Element Body Formatting Functions

To register body formating user defined functions for special element
(@pxref{Output Element Units}), the special elements varieties are used, as
described in @ref{Special Elements Varieties}.

@float Table, Special Elements Varieties
@multitable {Short table of contents} {Special Element Variety}
@headitem Special Element @tab Special Element Variety
@item Table of contents @tab @code{contents}
@item Short table of contents @tab @code{shortcontents}
@item Footnotes @tab @code{footnotes}
@item About @tab @code{about}
@end multitable
@caption{Association of special elements names with their special element variety}
@end float

Special element body formatting user defined functions are registered with
@code{texinfo_register_formatting_special_element_body}:

@defun texinfo_register_formatting_special_element_body ($special_element_variety, @
                            \@ampchar{}handler)
@var{$special_element_variety} is the element variety
(@pxref{Special Elements Varieties}).  @var{\&handler} is the user defined
function reference.
@end defun

The call of the user defined functions is:
@deftypefn {Function Reference} @var{$text} special_element_body (@var{$converter}, @
                                @var{$special_element_variety}, @var{\%element})
@var{$converter} is a converter object. @var{$special_element_variety} is the
element variety.  @var{\%element} is the Texinfo element.

The @var{$text} returned is the formatted special element body.
@end deftypefn

To call a special element body formatting function from user defined code, the
function reference should first be retrieved using
@code{special_element_body_formatting}:

@deftypefun {@var{\&special_element_body_formatting} =} @var{$converter}->special_element_body_formatting @
                                              (@var{$special_element_variety})
@var{$special_element_variety} is the special element variety.  Returns the
conversion function reference for @var{$variety}, or undef if there is none,
which should not happen for the special elements described in this manual.
@end deftypefun

For example:
@example
my $footnotes_element_body
 = &@{$converter->special_element_body_formatting('footnotes')@}($converter,
                                                     'footnotes', $element);
@end example

It is possible to have access to the default conversion function reference.
The function used is:

@deftypefun {@var{\&default_special_element_body_formatting} =} @
               @var{$converter}->defaults_special_element_body_formatting @
                                               (@var{$special_element_variety})
@var{$special_element_variety} is the special element variety.  Returns the
default conversion function reference for @var{$special_element_variety}, or
@code{undef} if there is none, which should not happen for the special elements
described in this manual.
@end deftypefun

@xref{Customizing Footnotes} for more on the footnotes special element body
formatting.  @xref{Contents and Short Table of Contents Customization}
for more on the @code{contents} and @code{shortcontents} special elements
body formatting.  @xref{About Element Customization} for more
on the @code{about} special element body formatting.


@node Mandatory Conversion Function Calls
@chapter Mandatory Conversion Function Calls

There are several conventions and constraints that user defined code should
abide to, in order to comply with customization option values, and also
to have information correctly registered in the converter.


@node Protection of URLs
@section Protection of URLs

URLs need to be ``percent-encoded'' to protect non-ASCII characters, spaces and
other ASCII characters.  Percent-encoding also allows to have characters be
interpreted as part of a path and not as characters with a special role in
URLs.  For example, @samp{?} has a special role in URLs as it starts a query
string.  To have it considered as part of a file path, instead of a marker of
the beginning of a query, it needs to be percent encoded.

To protect a whole URL, in which characters with a special role in URL
are left as is, use @code{url_protect_url_text}.  To protect file path in URL,
including characters with a special role in URLs,
use @code{url_protect_file_text}.

@deftypefun {@var{$protected_url} =} @var{$converter}->url_protect_url_text(@var{$input_string})
Percent-encode @var{$input_string}, leaving as is all the characters with a
special role in URLs, such as @samp{:}, @samp{/}, @samp{?}, @samp{&}, @samp{#}
or @samp{%} (and a few other).  HTML reserved characters and form feeds
protected are also protected as entities (@pxref{Basic Formatting
Customization,,@code{format_protect_text}}).  This is typically used on
complete URLs pointing to diverse internet resources, such as the @code{@@url}
URL argument.

for example
@example
return $self->html_attribute_class('a', [$cmdname])
     .' href="'.$self->url_protect_url_text($url)."\">$text</a>";
@end example
@end deftypefun

@deftypefun {@var{$protected_path} =} @var{$converter}->url_protect_file_text(@var{$input_string})
Percent-encode @var{$input_string} leaving as is character appearing in file
paths only, such as @samp{/}, @samp{.}, @samp{-} or @samp{_}.  All the other
characters that can be percent-protected are protected, including characters
with a special role in URLs.  For example, @samp{?}, @samp{&} and @samp{%} are
percent-protected.  HTML reserved characters and form feeds protected are also
protected as entities (@pxref{Basic Formatting Customization,,
@code{format_protect_text}}).  This is typically used on file names
corresponding to actual files, used in the path portion of an URL, such as the
image file path in @code{@@image}.

For example
@example
$self->html_attribute_class('img', [$cmdname])
   . ' src="'.$self->url_protect_file_text($image_file)."\");
@end example
@end deftypefun


@node Formatting HTML Element with Classes
@section Formatting HTML Element with Classes

Opening an HTML element with one or more classes should always be done through
@code{html_attribute_class}:

@deftypefun {@var{$element_open} =} @var{$converter}->html_attribute_class @
                              (@var{$html_element}, @var{\@@classes})
Formats the beginning of an HTML element @var{$html_element}.  @var{\@@classes}
is the list of classes for this element.  The element opening returned does not
include the end of element symbol @samp{>} such that it is possible to add
more attributes.

If the HTML element is @code{span}, an empty string is returned if there
is also no attribute.

If @code{NO_CSS} is set, no attribute is set for the element.  Otherwise
a @code{class} attribute is set based on @var{\@@classes }. If
@code{INLINE_CSS_STYLE} is set, a CSS style attribute based on
CSS element class rules is also added.  Otherwise the information that
the element class was seen is registered by the converter.
@end deftypefun

Examples of use:
@example
my $open = $converter->html_attribute_class('span', ['category-def']);
$category_result = $open.'>'.$category_result.'</span>'
  if ($open ne '');

my $result = $converter->html_attribute_class('em', [$cmdname, 'jax_p'])
     . '>' . $content . '</em>';
@end example


@node Closing Lone HTML Element
@section Closing Lone HTML Element

HTML elements with an opening element, but no closing element,
such as @code{<img>} or @code{<link>} should be closed by calling
@code{close_html_lone_element}:

@deftypefun {@var{$html_element} =} @var{$converter}->close_html_lone_element @
                                                     (@var{$unclosed_element})
Close the @var{$unclosed_element}, which can contain attributes, by prepending
@samp{>} or @samp{/>} depending on the @code{USE_XML_SYNTAX} customization
variable value.
@end deftypefun

Examples of use:
@example
$description = $converter->close_html_lone_element(
    "<meta name=\"description\" content=\"$description\"");
@end example


@node Substituting Non Breaking Space
@section Substituting Non Breaking Space

If a @code{&nbsp;} can appear in formatted code,
the corresponding text should be in a call to @code{substitute_html_non_breaking_space},
to take into account @code{ENABLE_ENCODING} and @code{USE_NUMERIC_ENTITY}
customization variables:

@deftypefun {@var{$substituted_text} =} @var{$converter}->substitute_html_non_breaking_space @
                                                    (@var{$formatted_text})
Substitute @code{&nbsp;} according to customization variables values.
@end deftypefun

This is not needed if the @code{non_breaking_space} information is taken from
the general information (@pxref{Conversion General Information}).


@node Conversion in String Context
@section Conversion in String Context

Conversion and formatting functions should check if in string
context to avoid using HTML elements in formatting when in string context.
@xref{Init File Expansion Contexts}.

To determine if in string context, the functions is @code{in_string}:

@deftypefun {@var{$in_string} =} @var{$converter}->in_string ()
Return true if in string context.
@end deftypefun

Example of use:

@example
if ($converter->in_string()) @{
  return "$mail_string ($text)";
@} else @{
  return $converter->html_attribute_class('a', [$cmdname])
                      ." href=\"mailto:$mail_string\">$text</a>";
@}
@end example


@node Conversion in Preformatted Context
@section Conversion in Preformatted Context

Conversion and formatting functions should test if in preformatted
context to convert accordingly. @xref{Init File Expansion Contexts}.

To determine if in preformatted context, the functions is @code{in_preformatted}:

@deftypefun {@var{$in_preformatted} =} @var{$converter}->in_preformatted ()
Return true if in preformatted context.
@end deftypefun

If in preformatted context, it is possible to get preformatted @@-commands and
preformatted types nesting with @code{preformatted_classes_stack}:

@deftypefun {@var{@@preformatted_nesting} =} @var{$converter}->preformatted_classes_stack ()
Returns an array containing the block preformatted @@-commands such as
@code{@@example}, @code{@@display} or @code{@@menu} names without the leading
@@ and the HTML attribute class preformatted container names, in order of appearance.
@end deftypefun

The @code{%Texinfo::Commands::preformatted_code_commands}
hash can be used to determine if a preformatted command is to be formatted
as code (@pxref{Texinfo::Commands %preformatted_code_commands,,,
texi2any_internals}).

@example
my @@pre_classes = $converter->preformatted_classes_stack();
foreach my $pre_class (@@pre_classes) @{
  if ($Texinfo::Commands::preformatted_code_commands@{$pre_class@}) @{
    $result = '<code>' .$result. '</code>';
    last;
  @}
@}
@end example

@xref{Simple Customization of Containers} on customizing containers preformatted class.


@node Text Formatting Context
@section Text Formatting Context

Formatting of text requires to use additional informative functions on specific
contexts only relevant for text.  User defined functions should convert the text
according to the context.

Each context is associated with a function:

@table @emph
@item code

@deftypefun {@var{$in_code} =} @var{$converter}->in_code ()
Return true if in code context.  @xref{Init File Expansion Contexts}.
@end deftypefun

@item math

@deftypefun {@var{$in_math} =} @var{$converter}->in_math ()
Return true if in math context. @xref{Init File Expansion Contexts}.
@end deftypefun

@item raw

@deftypefun {@var{$in_raw} =} @var{$converter}->in_raw ()
Return true if in raw format, in @code{@@inlineraw} or in @code{@@html}.
In such a context, text should be kept as is and special HTML characters should
not be protected.
@end deftypefun

@item verbatim

@deftypefun {@var{$in_verbatim} =} @var{$converter}->in_verbatim ()
Return true if in verbatim context, corresponding to @code{@@verb} and @code{@@verbatim}.
In general, HTML characters should be protected in this context.
@end deftypefun

@item upper-case

@deftypefun {@var{$in_upper_case} =} @var{$converter}->in_upper_case ()
Return true if in upper-case context, corresponding to @code{@@sc}.
@end deftypefun

@item non-breakable space

@deftypefun {@var{$in_non_breakable_space} =} @var{$converter}->in_non_breakable_space ()
Return true if in non-breakable space context, corresponding to @code{@@w}.
@end deftypefun
@end table


@node Basic Formatting Customization
@chapter Basic Formatting Customization

The following formatting functions references handle basic formatting
and are called from diverse formatting and conversion functions. @xref{Specific
formating Functions} for information on how to register and get the functions
references.

All the functions take a converter object as their first argument.

@table @code
@item format_button_icon_img

Called for an active direction, if @code{ICONS} is set, when formatting
the navigation panel (@pxref{Simple Navigation Panel Customization}).

@deftypefn {Function Reference} @var{$text} format_button_icon_img @
                  (@var{$converter}, @var{$button}, @var{$icon}, @var{$name})
@var{$button} is a button name, typically obtained from the @code{BUTTONS_NAME}
customization variable hash using a direction as key (@pxref{Directions}).
@var{$icon} is an image file name to be used as icon.  @var{$name} is the
direction heading, typically formatted in string context.  @xref{Init File
Expansion Contexts}.

Returns a formatted icon image.
@end deftypefn

@item format_comment

@deftypefn {Function Reference} @var{$text} format_comment  @
                                       (@var{$converter}, @var{$input_text})
Return @var{$input_text} in a comment.
@end deftypefn

@xref{Texinfo::Convert::Converter $comment = $converter->xml_comment($text),,
Texinfo::Convert::Converter::xml_comment,texi2any_internals}.

@item format_heading_text

@deftypefn {Function Reference} @var{$text} format_heading_text @
  (@var{$converter}, @var{$command_name}, @var{\@@classes}, @var{$input_text}, @var{$level}, @var{$id}, @var{\%element})
Returns a heading formatted using @var{$input_text} as heading text, @var{$level}
as heading level, @var{\@@classes} for a class attribute.  @var{$command_name}
gives an information on the @@-command the heading is associated to and can be
@code{undef}, for instance for special elements headings.

@var{$id} is an optional identifier, and @var{\%element} is an optional
Texinfo tree element associated with the heading.
@end deftypefn

This function reference can be called for @code{@@node} and sectioning
commands, heading commands, tree units, special elements and title @@-commands.

A formatted headings is, in the default case, like @code{<h2>@var{$input_text}</h2>}
for a @var{$level} 2 heading.

@item format_program_string

@deftypefn {Function Reference} @var{$text} format_program_string (@var{$converter})
This function reference should return the formatted program
string.
@end deftypefn

@item format_protect_text
@deftypefn {Function Reference} @var{$text} format_protect_text  @
                                        (@var{$converter}, @var{$input_text})
Return @var{$input_text} with HTML reserved characters and form feeds
protected.

For performance reasons, this function reference may not be called everywhere
text is protected.  For those cases, the calling function should also be
redefined to call @code{&@{$self->formatting_function('format_protect_text')@}(...)}
instead of another function@footnote{The function called is actually the
function referenced as @code{$self->formatting_function('format_protect_text')}
in the default case, but it is called directly to avoid an indirection}.
@end deftypefn

@xref{Texinfo::Convert::Converter $protected_text = $converter->xml_protect_text($text),,
Texinfo::Convert::Converter::xml_protect_text,texi2any_internals}.
@item format_separate_anchor

This function reference is called if there is not another HTML element to
add an identifier attribute to.

@deftypefn {Function Reference} @var{$text} format_separate_anchor @
                               (@var{$converter}, @var{$id}, @var{$class})
@var{id} is the identifier.
@var{$class} is an optional class to be used in an HTML class attribute.

Return an anchor with identifier @var{$id}.
@end deftypefn
@end table


@node Dynamic Conversion Information
@chapter Dynamic Conversion Information

Dynamic formatting information on the conversion can be obtained from the
converter.

For advanced customization, it is also often necessary to pass information
during conversion between different formatting functions or between
different calls calls of the same function.

The information is often useful for the formatting of paragraph and
preformatted containers and @@-comands such as @code{@@abbr}, @code{@@footnote},
@code{@@node}, sectioning commands, @code{@@quotation} and @code{@@float}.


@node Dynamic Converter Formatting Information
@section Dynamic Converter Formatting Information


To get the current paragraph and preformatted number, use @code{paragraph_number}
or @code{preformatted_number}:

@deftypefun {@var{$number} =} @var{$converter}->paragraph_number ()
@deftypefunx {@var{$number} =} @var{$converter}->preformatted_number ()
Return the current paragraph or preformatted container number in the
current formatting context.
@end deftypefun

To get the topmost block @@-command being converted, use @code{top_block_command}:
@deftypefun {@var{$command_name} =} @var{$converter}->top_block_command ()
Return the most recent block @@-command seen in the current formatting
context.
@end deftypefun

To get the text filling and alignement context, determined by @code{@@flushleft}
or @code{@@center}, use @code{in_align}:

@deftypefun {@var{$align_context} =} @var{$converter}->in_align ()
If the alignment context is the default alignement context, return @code{undef}.
Otherwise, returns the command name of the alignment context.
@end deftypefun

To determine if the conversion is in a context converted multiple times,
use @code{in_multi_expanded}:
@deftypefun {@var{$multi_expanded_context_information} =} @var{$converter}->in_multi_expanded ()
Return a string representing the multiple expanded context, or @code{undef} if
not in a multiple expanded context.
@end deftypefun

To get the location of an image file, use @code{html_image_file_location_name}:

@deftypefun {(@var{$image_file}, @var{$image_basefile}, @var{$image_extension}, @var{$image_path}, @var{$image_path_encoding}) =} @
 @var{$converter}->html_image_file_location_name (@var{$command_name}, @var{\%element}, @var{\@@args})
@var{$command_name}, @var{\%element} and @var{\@@args} should be the arguments
of an @code{@@image} @@-command formatting (@pxref{Command Tree Element
Conversion Functions}).

The return values gives information on the image file if found, or fallback values.
@var{$image_file} is the relative image file name.  It is the file name used in
formatting of the @code{@@image} command in the default case.  @var{$image_basefile}
is the base file name of the image, without extension, corresponding to the
@code{@@image} @@-command first argument.  @var{$image_extension} is the image
file extension (without a leading dot).  @var{$image_path} is the path to the
actual image file, @code{undef} if no file was found.  @var{$image_path} is
returned as a binary string, the other strings returned are character strings.
@var{$image_path_encoding} is the encoding used to encode the image path to a
binary string.
@end deftypefun

@xref{Conversion in Preformatted Context} for information on getting
preformatted commands and container types nesting information.


@node Opening and Closing Sectioning Commands Extent
@section Opening and Closing Sectioning Commands Extent

In the default formatting, when a sectioning command is encountered, a
@code{<div>} element is opened for the extent of the sectioning command
including its children sectioning commands.  This extent need to be closed
at different places, for instance when another sectioning command
is reached, at the end of a file, or at the end of the document.

The user defined formatting function should take care of
registering and closing opened section levels.  In the default code, registering is
done in the sectioning commands conversion function only.

The function for registering opened section extent is
@code{register_opened_section_level}:

@defun @var{$converter}->register_opened_section_level ($level, $closing_text)
@var{$level} is the sectioning command level.  It is typically
obtained with @code{section->@{'structure'@}->@{'section_level'@}}
(@pxref{Texinfo Tree Elements in User Defined Functions}).
@var{$closing_text} is the text that should be output when the
section level @var{$level} is closed.
@end defun

The function for closing registered section extents is
@code{close_registered_sections_level}:

@deftypefun {@var{@@closing_texts} =} @var{$converter}->close_registered_sections_level (@var{$level})
@var{$level} is the sectioning command level.  Opened section are closed
down to section level @var{$level}.  The closing texts are returned in the
@var{@@closing_texts} array in order.
@end deftypefun

Example of use:
@example
my $level = $opening_section->@{'structure'@}->@{'section_level'@};
$result .= join('', $converter->close_registered_sections_level($level));
$converter->register_opened_section_level($level, "</div>\n");
@end example


@node Setting Up Content for the Next Text Container
@section Setting Up Content for the Next Text Container

Text is mainly output in two @dfn{inline} text containers, @code{paragraph} for
text in paragraph and @code{preformatted} for text in preformatted
environments.  The Texinfo code parsing makes sure that it is the case, to
simplify conversion to formats which allow text only in specific environments
such as HTML.

Formatted text may also be prepared based on information from Texinfo
elements tree while out of the inline containers.  For that case, functions
allow to register pending inline formatted content, and get the content to be
prepended in inline text containers.

Pending formatted content text is registered with
@code{register_pending_formatted_inline_content}:

@defun @var{$converter}->register_pending_formatted_inline_content ($category, $content)
@var{$content} is the formatted content to be registered and output
in the next inline container.  @var{$category} is a indicator of the source
of the formatted inline content, mostly used to cancel registered content
if no inline container was seen.
@end defun

Pending formatted content can (and should) be cancelled when it is known that
there is no suitable inline container to be used to output the text.  The
function is @code{cancel_pending_formatted_inline_content}:

@deftypefun {@var{$cancelled_content} =} @var{$converter}->cancel_pending_formatted_inline_content (@var{$category})
Cancel the first @var{$category} pending formatted content text found.
Returns @code{undef} if nothing was cancelled, and the cancelled
content otherwise.
@end deftypefun

Pending formatted content is gathered by calling @code{get_pending_formatted_inline_content}.
In the default case, this is done in inline containers opening
code (@pxref{Type Tree Element Opening Functions}).

@deftypefun {@var{$content} =} @var{$converter}->get_pending_formatted_inline_content ()
Returns the concatenated pending content.
@end deftypefun

The inline containers get the content when they are opened, but are
converted after the formatting of their contents.  Two additional functions
allow to associate pending content to an element,
@code{associate_pending_formatted_inline_content}, and get the associated
content, @code{get_associated_formatted_inline_content}.
@code{associate_pending_formatted_inline_content} is normally called in inline
container opening code, right after
@code{get_pending_formatted_inline_content}, while
@code{get_associated_formatted_inline_content} is called in the inline
container conversion function (@pxref{Type Tree Element Conversion Functions}).

@defun @var{$converter}->associate_pending_formatted_inline_content (\%element, $content)
Associate @var{$content} to the Texinfo tree element @var{\%element}.
@end defun

@deftypefun {@var{$content} =} @var{$converter}->get_associated_formatted_inline_content (@var{\%element})
Get @var{$content} associated to the Texinfo tree element @var{\%element}.
@end deftypefun


@node Associating Information to an Output File
@section Associating Information to an Output File

To be able to retrieve information associated to the current file, in general
for the file begin or end formatting, @code{register_file_information} can  be
used to associate information, and @code{get_file_information} to retrieve that
information.

@defun @var{$converter}->register_file_information ($key, $value)
Associate the current output file name file to the key @var{$key}, itself
associated to the value @var{$value}.
@end defun

@deftypefun {@var{$value} =} @var{$converter}->get_file_information (@var{$key}, @var{$file_name})
Return the value associated to the key @var{$key} and file name @var{$file_name}.
@end deftypefun


@node Shared Conversion State
@section Shared Conversion State

For information shared among formatting functions without involving the
converter, the function @code{shared_conversion_state} can be used both for
initialization of shared information and to share information:

@deftypefun {@var{$reference} =} @var{$converter}->shared_conversion_state (@var{$name}, @var{$initialization})
Return the reference @var{$reference} associated with @var{$name}.
@var{$initialization} is only read the first time @var{$name} is seen and sets
up the reference that will be reused afterwards.  If @var{$initialization} is a
scalar (string or integer, for example), a reference on a scalar is returned,
the associated value being set to @var{$initialization}.  Otherwise,
@var{$initialization} should be a reference on a hash or on an array.
@end deftypefun

The converter is used to hold the information, but does not use nor write.

Examples of use:
@example
my $explained_commands_hash
    = $converter->shared_conversion_state('explained_commands', @{@});
$explained_commands_hash->@{'key'@} = 'value';

my $foot_num_reference
     = $converter->shared_conversion_state('footnote_number', 0);
$@{$foot_num_reference@}++;
@end example


@node Directions@comma{} Links@comma{} Labels and Files
@chapter Directions, Links, Labels and Files

Navigation headers, navigation panels, end or beginning of files, @code{@@xref}
and similar @@-commands output, @code{@@menu}, @code{@@node}, sectioning
commands, @code{@@printindex} and @code{@@listoffloats} formatting requires
directions, links, labels and files information.


@node Target Commands Links@comma{} Texts and Associated Commands
@section Target Commands Links, Texts and Associated Commands

Target @@-commands are @@-comands that are associated with an identifier
and can be linked to.  They corresponds first to @@-commands with unique identifier
used as labels, @code{@@node}, @code{@@anchor} and @code{@@float}.  Sectioning
commands, index entries and footnotes are also associated to targets.

To get the unique Texinfo tree element corresponding to a label, use
@code{label_command}:

@deftypefun {@var{\%element} =} @var{$converter}->label_command (@var{$label})
Return the element in the tree that @var{$label} refers to.
@end deftypefun

To get the identifier, file name and href of tree elements that may be used
as link target, use @code{command_id}, @code{command_filename} and @code{command_href}:

@deftypefun {@var{$identifier} =} @var{$converter}->command_id (@var{\%target_element})
Returns the id specific of the @var{\%target_element} tree element.
@end deftypefun

@deftypefun {@var{$file_name} =} @var{$converter}->command_filename (@var{\%target_element})
Returns the file name of the @var{\%target_element} tree element.
@end deftypefun

@deftypefun {@var{$href} =} @var{$converter}->command_href (@var{\%target_element}, @
       @var{$source_filename}, @var{$source_command}, @var{$specified_target})
Return string for linking to @var{\%target_element} with @code{<a href>}.
@var{$source_filename} is the file the link comes from. If not set, the current
file name is used.  @var{$source_command} is an optional argument, the
@@-command the link comes from.  It is only used for messages.
@var{$specified_target} is an optional identifier that overrides the target
identifier if set.
@end deftypefun

To get the text of tree elements that may be used as link description, use
@code{command_text}:

@deftypefun {@var{$result} =} @var{$converter}->command_text (@var{\%target_element}, @var{$type})
Return the information to be used for a hyperlink to @var{\%target_element}.
The information returned depends on @var{$type}:

@table @emph
@item text
Return text.

@item tree
Return a Texinfo elements tree.

@item tree_nonumber
Return a Texinfo elements tree representing text without a chapter number
being included.

@item string
Return text in string context.  @xref{Init File Expansion Contexts}.
@end table
@end deftypefun

To obtain the top level command element associated with the target element,
either a @code{@@node} or a sectioning element, use
@code{command_root_element_command}:

@deftypefun {@var{\%top_level_element} =} @var{$converter}->command_root_element_command @
                                                    (@var{\%target_element})
Return the top level element @var{\%target_element} is in.
@end deftypefun

To get the node element associated with the target element, use
@code{command_node}:

@deftypefun {@var{\%node_element} =} @var{$converter}->command_node (@var{\%target_element})
Return the node element associated with @var{\%target_element}.
@end deftypefun


@node Other Links@comma{} Headings and Associated Information for Special Elements
@section Other Links, Headings and Associated Information for Special Elements

To get the id of a footnote in the main document, use
@code{footnote_location_target}:

@deftypefun {@var{$target} =} @var{$converter}->footnote_location_target (@var{\%footnote_element})
Return the id for the location of the footnote @var{\%footnote_element}
in the main document (where the footnote number or symbol appears).
@end deftypefun

To get an href to link to a footnote location in the main document, use
@code{footnote_location_href}:

@deftypefun {@var{$href} =} @var{$converter}->footnote_location_href (@var{\%footnote_element}, @
     @var{$source_filename}, @var{$specified_target}, @var{$target_filename})
Return string for linking to @var{\%footnote_element} location
in the main document with @code{<a href>}.  @var{$source_filename} is the file
the link comes from. If not set, the current file name is used.
@var{$specified_target} is an optional identifier that overrides the
target identifier if set.  @var{$target_filename} is an optional file name
that overrides the file name href part if set.
@end deftypefun

@xref{Target Commands Links@comma{} Texts and Associated Commands} to get
link information for the location where footnote text is output.

To get id and link href of sectioning commands in table of contents
and short table of contents, use @code{command_contents_target} and
@code{command_contents_href}:

@deftypefun {@var{$target} =} @var{$converter}->command_contents_target @
    (@var{\%sectioning_element}, @var{$contents_or_shortcontents})
Returns the id for the location of @var{\%sectioning_element} sectioning
element in the table of contents, if @var{$contents_or_shortcontents} is
@samp{contents}, or in the short table of contents, if
@var{$contents_or_shortcontents} is set to @samp{shortcontents} or
@samp{summarycontents}.
@end deftypefun

@deftypefun {@var{$href} =} @var{$converter}->command_contents_href @
   (@var{\%sectioning_element}, @var{$contents_or_shortcontents}, @var{$source_filename})
Return string for linking to the @var{\%sectioning_element} sectioning element
location in the table of contents, if @var{$contents_or_shortcontents} is
@samp{contents} or in the short table of contents, if
@var{$contents_or_shortcontents} is set to @samp{shortcontents} or
@samp{summarycontents}.  @var{$source_filename} is the file the link comes
from. If not set, the current file name is used.
@end deftypefun

To determine if a tree unit element is the top element, use
@code{element_is_tree_unit_top}:

@deftypefun {@var{$is_tree_unit_top} =} @var{$converter}->element_is_tree_unit_top (@var{\%element})
Returns true if the @var{\%element} Texinfo tree element is the tree unit
Top element (@pxref{Output Element Units}) and is either associated with the
@code{@@top} sectioning command or with the @code{Top} @code{@@node}.
@end deftypefun

To get information on the special element variety associated with
an @@-command command name, use @code{command_name_special_element_information}:

@deftypefun {(@var{$special_element_variety}, @var{\%special_element}, @var{$class_base}, @var{$special_element_direction}) =} @
  @var{$converter}->command_name_special_element_information (@var{$command_name})
@var{$command_name} is an @@-command name without the leading @@.
If the @var{$command_name} is not associated with a special element, returns
@code{undef}.  Otherwise, return the @var{$special_element_variety}
(@pxref{Special Elements Varieties}), the @var{\%special_element} texinfo tree
unit, a @var{$class_base} string for HTML class attribute and the
@var{$special_element_direction} direction corresponding to that special
elements (@pxref{Directions}).
@end deftypefun

In the current setup, special elements are associated with @code{@@contents},
@code{@@shortcontents} and @code{@@summarycontents} and with @code{@@footnote}.


@node Elements and Links for Directions
@section Elements and Links for Directions

@xref{Directions} for the list of directions.

To get the Texinfo tree unit special element associated with
a special element direction, such as @samp{About} or @samp{Contents},
use @code{special_direction_element}:

@deftypefun {@var{\%special_element} =} @var{$converter}->special_direction_element (@var{$direction})
Return the special element associated with direction @var{$direction}, or
@code{undef} if the direction is not a special element direction or the special
element is not output.
@end deftypefun

To get the Texinfo tree unit element associated with other global element
directions, such as @samp{Top} or @samp{Index}, use
@code{global_direction_element}:

@deftypefun {@var{\%element} =} @var{$converter}->global_direction_element (@var{$direction})
Return the Texinfo tree unit element corresponding to direction
@var{$direction}, or @code{undef} if the direction is not a global direction.
@end deftypefun

To get link information for relative and global
directions, use @code{from_element_direction}:

@deftypefun {@var{$result} =} @var{$converter}->from_element_direction (@var{$direction}, @var{$type}, @
   @var{$source_element}, @var{$source_filename}, @var{$source_command})
Return a string for linking to @var{$direction}, or the information
to be used for a hyperlink to @var{$direction}, depending on @var{$type}.
The possible values for @var{$type} are described in
@ref{Element Direction Information Type}.

@var{$source_element} is the tree unit element the link comes from. If not set,
the current tree unit element is used.  @var{$source_filename} is the file the
link comes from. If not set, the current file name is used.
@var{$source_command}
is an optional argument, the @@-command the link comes from. It is only used for
messages.
@end deftypefun


@node Element Counters in Files
@section Element Counters in Files

The position of the tree unit element being formatted in its file
or the total number of elements output to a file is interesting, for instance
to format end of files, decide which navigation header or footer is needed and
whether a rule should be output.

To get information on tree elements unit counter in files, use
@code{count_elements_in_filename}:

@deftypefun {@var{$count} =} @var{$converter}->count_elements_in_filename @
                                     (@var{$specification}, @var{$file_name})
Return tree unit element counter for @var{$file_name}, or @code{undef} if
the counter does not exist.  The counter returned depends on @var{$specification}:

@table @emph
@item current
Return the number of unit elements associated with @var{$file_name}
having already been processed.
@item remaining
Return the number of unit elements associated with @var{$file_name}
that remains to be processed.
@item total
Return the total number of element units associated with the file.
@end table
@end deftypefun


@node Customizing Footnotes@comma{} Tables of Contents and About
@chapter Customizing Footnotes, Tables of Contents and About

@node Customizing Footnotes
@section Customizing Footnotes

@code{NUMBER_FOOTNOTES} and @code{NO_NUMBER_FOOTNOTE_SYMBOL} customization
variables can be used to change the footnotes formatting.  Redefinition
of @code{@@footnote} conversion reference and footnote formatting
references is needed for further customization.

@code{@@footnote} @@-commands appearing in the Texinfo elements tree
are converted like any other elements associated with @@-commands
(@pxref{Command Tree Element Conversion Functions}).  It is therefore possible
to redefine their formatting by registering a user defined function.

To pass information on footnotes between the conversion function processing the
@code{@@footnote} command at the location they appear in the document and the
functions formatting their argument elsewhere, two functions are available:
@code{register_footnote} to be called where they appear in the document, and
@code{get_pending_footnotes} to be called where they are formatted.

@defun @var{$converter}->register_footnote (\%element, $footnote_id, @
  $foot_in_doc_id, $number_in_doc, $footnote_location_filename, $multi_expanded_region)
@var{\%element} is the footnote texinfo tree element. @var{$footnote_id} is the
identifier for the location where the footnote arguments are expanded.
@var{$foot_in_doc_id} is the identifier for the location where the footnote
appears in the document.  @var{$number_in_doc} is the symbol used to format the
footnote in the document.  @var{$footnote_location_filename} is the filename of
the tree unit element of the footnote in the document. If the footnote appears
in a region that is expanded multiple times, the information on the expansion
is @var{$multi_expanded_region} (@pxref{Dynamic Converter Formatting
Information}).
@end defun

@code{register_footnote} is normally called in the @code{@@footnote}
@@-command conversion function reference.  The default conversion function
also call @code{command_href} to link to the location where the footnote
text will be expanded (@pxref{Target Commands Links@comma{} Texts and Associated Commands}).

@deftypefun {@var{@@pending_footnotes_information} =} @var{$converter}->get_pending_footnotes ()
Returns in @var{@@pending_footnotes_information} the information gathered
in @code{register_footnote}.  Each of the array element in @var{@@pending_footnotes_information}
is an array reference containing the arguments of @code{register_footnote}
in the same order.
@end deftypefun

The formatting of footnotes content is done by the
@code{format_footnotes_sequence} formatting reference
(@pxref{Specific formating Functions}):

@deftypefn {Function Reference} @var{$footnotes_sequence} format_footnotes_sequence @
                                                  (@var{$converter})
Formats and returns the footnotes that need to be formatted.  This function
normally calls @code{get_pending_footnotes}.  The default function also calls
@code{footnote_location_href} (@pxref{Other Links@comma{} Headings and
Associated Information for Special Elements}) to link to the location
in the document where the footnote appeared.
@end deftypefn

If footnotes are in a separate element unit (@pxref{Output Element Units}), the
default footnote special element body formatting function calls
@code{format_footnotes_sequence} (@pxref{Special Element
Body Formatting Functions}).

If the footnotes are not in a separate element unit, or there is no separate element because
there is only one tree unit element or no tree unit element, the
@code{format_footnotes_segment} formatting reference is called when
pending footnotes need to be formatted.  This function reference
can be replaced by a user defined function.

@deftypefn {Function Reference} @var{$footnotes_segment} format_footnotes_segment @
                                                        (@var{$converter})
Returns the footnotes formatted.  In the default case, the function reference
calls @code{format_footnotes_sequence} and also sets up a header with
@code{format_heading_text} (@pxref{Basic Formatting Customization}), using the
customization variables @code{FOOTNOTE_END_HEADER_LEVEL} and
@code{SPECIAL_ELEMENTS_HEADING} with the @code{footnotes} special element
variety key.
@end deftypefn


@node Contents and Short Table of Contents Customization
@section Contents and Short Table of Contents Customization

@cindex Customization of tables of contents elements
@cindex Contents, customizing elements
@cindex Short table of contents element, customizing
@cindex Overview element, customizing

@c FIXME this is already documented in the Customization variables
@c documentation in the Texinfo manual.  Keep it anyway as it is
@c slightly more informative here?

To begin with, the table of contents and short table of contents can
be made to appear at different locations in the document.

@vindex CONTENTS_OUTPUT_LOCATION
By default, the customization variable
@code{CONTENTS_OUTPUT_LOCATION} is set to @samp{after_top}, specifying
that the tables of contents are output at the end of the @code{@@top}
section, to have the main location for navigation in the whole document
early on.  This is in line with @code{FORMAT_MENU} set to @samp{sectiontoc}
with sectioning command being used in HTML for navigation rather
than menus.

If @code{CONTENTS_OUTPUT_LOCATION} is set to @samp{inline}, the tables of
content are output where the corresponding @@-command, for example
@code{@@contents}, is set.  This behavior is consistent with
@command{texi2dvi}.

If @code{CONTENTS_OUTPUT_LOCATION} is set to @samp{separate_element},
the tables of contents are output in separate elements, either at
the end of the document if the output is unsplit or in separate files if not.
This makes sense when menus are used for navigation with @code{FORMAT_MENU} set
to @samp{menu}.

If @code{CONTENTS_OUTPUT_LOCATION} is set to @samp{after_title}
the tables of contents are merged into the title material, which in turn is not
output by default; @pxref{HTML Title Page Customization}.

Next, the following variables allow for some useful control of the
formatting of table of contents and short table of contents:

@vtable @code
@item BEFORE_TOC_LINES
Inserted before the table of contents text.

@item AFTER_TOC_LINES
Inserted after the table of contents text.

@item BEFORE_SHORT_TOC_LINES
Inserted before the short table of contents text.

@item AFTER_SHORT_TOC_LINES
Inserted after the short table of contents text.

@end vtable

Additional customization variables @code{SHORT_TOC_LINK_TO_TOC}
and @code{NUMBER_SECTIONS} can be used to change the formatting
of table of contents.

Finally, the following function reference provides even more control
over the table of contents and short table of contents formatting
reference:

@deftypefn {Function Reference} @var{$toc_result} format_contents @
   (@var{$converter}, @var{$command_name}, @var{\%element}, @var{$filename})
@var{$command_name} is the @@-command name without leading @@, should be
@samp{contents}, @samp{shortcontents} or @samp{summarycontents}.
@var{\%element} is optional.  It corresponds to the @var{$command_name} Texinfo
tree element, but it is only set if @code{format_contents} is called from a
Texinfo tree element conversion, and not as a special element body formatting.
@var{$filename} is optional and should correspond to the filename where the
formatting happens, for links.

In the default function, structuring information is used
to format the table of contents (@pxref{Conversion General Information}),
and @code{command_contents_href} (@pxref{Other Links@comma{} Headings and
Associated Information for Special Elements}) and @code{command_href}
(@pxref{Target Commands Links@comma{} Texts and Associated Commands})
are used for links.  If @var{$filename} is unset, the current file name
is used, using @code{$converter->get_info('current_filename')}.

Return formatted table of contents or short table of contents.
@end deftypefn

If contents are in a separate element unit (@pxref{Output Element Units}), the
default contents and shortcontents special element body formatting function
calls @code{format_contents} (@pxref{Special Element Body Formatting
Functions}).  Otherwise, @code{format_contents} is called in the conversion
of heading @@-command, in title page formatting, and in @code{@@contents}
conversion function, depending on the @code{CONTENTS_OUTPUT_LOCATION} value.


@node About Element Customization
@section About Element Customization

@cindex Customization of about element
@cindex About element, customizing

The default About element has an explanation of the buttons used in
the document, controlled by @code{SECTION_BUTTONS}.
The formatting of this text may be influenced by
@code{BUTTONS_GOTO}, @code{BUTTONS_NAME}, @code{ACTIVE_ICONS}
(@pxref{Simple Navigation Panel Customization}).

@vindex BUTTONS_EXAMPLE
@code{BUTTONS_EXAMPLE} also influences the formatting. The keys of this hash
are element directions (@pxref{Directions}) and the values
are the text from the About example, typically a section number.

@vindex PROGRAM_NAME_IN_ABOUT
@code{PROGRAM_NAME_IN_ABOUT} can also be used to change the beginning of
the About element formatting.

If the above is not enough and you want to control exactly the
formatting of the about element, the @code{about} special element body reference
function may be overridden (@pxref{Special Element Body Formatting Functions}).


@node Customizing HTML Footers@comma{} Headers and Navigation Panels
@chapter Customizing HTML Footers, Headers and Navigation Panels

@command{texi2any} provides for customization of the HTML page
headers, footers, and navigation panel.  (These are
unrelated to the headings and ``footings'' produced in @TeX{} output;
@pxref{Headings,, Page Headings, texinfo, Texinfo}.)

In the event that your needs are not met by changing the navigation buttons
(@pxref{Simple Navigation Panel Customization}), you can completely control the
formatting of navigation panels by redefining function references.
@xref{Specific formating Functions} for information on how to register
the function references.

In a nutshell, element header and footer formatting function determines
the button directions list to use and calls navigation header formatting.  The
navigation header formatting adds some formatting if needed, but mostly calls
the navigation panel formatting.  The navigation panel can call buttons
formatting.


@node Navigation Panel and Navigation Header Formatting
@section Navigation Panel and Navigation Header Formatting

@c In the unusual case that this isn't enough, it is also possible to
@c redefine the function doing the navigation panel formatting.

@cindex Navigation panel formatting functions
@cindex Formatting functions, for navigation panel

All the formatting functions take a converter object as first argument.

The overall display of navigation panels is controlled via this
function reference, @code{format_navigation_header}:

@deftypefn {Function Reference} @var{$navigation_text} format_navigation_header @
   (@var{$converter}, @var{\@@buttons}, @var{$command_name}, @var{\%element})
@var{\@@buttons} is an array reference holding the specification of
the buttons for the navigation panel
(@pxref{Simple Navigation Panel Customization}). @var{\%element} is the
element in which the navigation header is formatted. @var{$command_name} is
the associated command (sectioning command or @code{@@node}).  It may be @code{undef}
for special elements.

Returns the formatted navigation header and panel. The navigation
panel itself can be formatted with a
call to @code{&@{$self->formatting_function('format_navigation_panel')@}}.

The customization variable @code{VERTICAL_HEAD_NAVIGATION} should be relevant.
@end deftypefn

The navigation panel display is controlled via @code{format_navigation_panel}:

@deftypefn {Function Reference} @var{$navigation_text} format_navigation_panel @
  (@var{$converter}, @var{\@@buttons}, @var{$command_name}, @var{\%element}, @var{$vertical})
@var{\@@buttons} is an array reference holding the specification of the buttons
for that navigation panel.   @var{\%element} is the element in which the
navigation header is formatted. @var{$command_name} is the associated command
(sectioning command or @code{@@node}).  It may be @code{undef} for special
elements.  @var{$vertical} is true if the navigation panel should be vertical.

Returns the formatted navigation panel in @var{$navigation_text}. The buttons
in the navigation panel can be formatted with a call to
@code{&@{$self->formatting_function('format_button')@}}.
@end deftypefn

The function reference @code{format_button} does the formatting of
one button:

@deftypefn {Function Reference} @var{$formatted_button} format_button @
           (@var{$converter}, @var{$button}, @var{$source_command})
@var{$button} holds the specification of the button (@pxref{Buttons Display}).
@var{$source_command} is an optional argument, the @@-command the link comes from.

Returns the formatted result in @var{$formatted_button}.

The buttons images can be formatted with @code{format_button_icon_img}
(@pxref{Basic Formatting Customization}).

Customization information described in @ref{Simple Navigation Panel Customization}
such as @code{BUTTONS_TEXT}, @code{BUTTONS_NAME}, @code{BUTTONS_GOTO},
@code{USE_ACCESSKEY}, @code{BUTTONS_ACCESSKEY},
@code{USE_REL_REV} and @code{BUTTONS_REL} can be relevant for the
formatting of a button.
@end deftypefn


@node Element Header and Footer Formatting
@section Element Header and Footer Formatting

@cindex Customizing HTML page headers
@cindex Headers, customizing for HTML

All the formatting functions take a converter object as first argument.

By default, the function associated with @code{format_element_header}
formats the header and navigation panel of a tree unit element.

@deftypefn {Function Reference} @var{$formatted_header} format_element_header @
    (@var{$converter}, @var{$command_name}, @var{\%element}, @var{\%tree_unit_element})
@var{\%element} is the element in which the navigation header is formatted
(sectioning command, @code{@@node} or special element). @var{$command_name} is
the associated command name.  It may be @code{undef} for special elements.
@var{\%tree_unit_element} is the associated tree unit element (@pxref{Texinfo
Tree Elements in User Defined Functions}).

Returns the formatted navigation header and panel.

In the default code, the function reference select a buttons list
(@pxref{Simple Navigation Panel Customization}).  The navigation header can
then be formatted with a call to
@code{&@{$self->formatting_function('format_navigation_header')@}}.  It is also
possible to format directly the navigation panel, depending on customization
variables values and location in file.
@end deftypefn

Similarly, the function associated with @code{format_element_footer}
formats the footer and navigation panel of a tree unit element.

@deftypefn {Function Reference} @var{$formatted_footer} format_element_footer @
   (@var{$converter}, @var{$tree_unit_type}, @var{\%tree_unit_element}, @
    @var{$content}, @var{$command})
@var{\%tree_unit_element} is the tree unit element element in which the
navigation footer is formatted.  @var{$tree_unit_type} is the associated type.
@var{$content} is the formatted element content.  @var{$command} is an optional
argument, the @@-command associated with the @var{\%tree_unit_element}.

Returns the formatted navigation footer and panel.

In the default code, the function reference select a buttons list
(@pxref{Simple Navigation Panel Customization}).
The navigation header can then be formatted with a call
to @code{&@{$self->formatting_function('format_navigation_header')@}}.

Many customization variables may be interesting for the footer
formatting, such as @code{SPLIT}, @code{HEADERS}, @code{DEFAULT_RULE},
@code{BIG_RULE}, @code{WORDS_IN_PAGE} or @code{PROGRAM_NAME_IN_FOOTER}.
@end deftypefn


@node Heading Commands and Tree Elements Formatting
@chapter Heading Commands and Tree Elements Formatting

The customization variables
@code{CONTENTS_OUTPUT_LOCATION},
@code{CHAPTER_HEADER_LEVEL}, @code{TOC_LINKS} and @code{FORMAT_MENU}
may be used to change the sectioning commands conversion.
@xref{HTML Customization Variables,,, texinfo, Texinfo}.

@code{@@node} and sectioning default conversion function call
@code{format_heading_text} (@pxref{Basic Formatting Customization})
and @code{format_element_header} (@pxref{Element Header and Footer
Formatting}), as well as functions opening and closing sectioning commands
extent (@pxref{Opening and Closing Sectioning Commands Extent}).  The
@code{@@node} and sectioning elements are formatted like any other elements
associated with @@-commands.  The corresponding function references can
therefore be replaced by user defined functions for a precise control of
conversion (@xref{Command Tree Element Conversion Functions}).

Tree unit elements default conversion involves calling the formatting reference
@code{format_element_footer} (@pxref{Element Header and Footer Formatting}).
The conversion for these elements with type @code{unit} can be be replaced by
user defined functions for a precise control of conversion (@pxref{Type Tree
Element Conversion Functions}).

Special elements conversion is achieved by calling
@code{special_element_body_formatting} (@pxref{Special Element Body Formatting
Functions}), @code{format_navigation_header} (@pxref{Navigation Panel and
Navigation Header Formatting}), @code{format_heading_text} (@pxref{Basic
Formatting Customization}) and @code{format_element_footer} (@pxref{Element
Header and Footer Formatting}).  The conversion for these elements with type
@code{special_element_type} can be be replaced by user defined functions for a
precise control of conversion (@pxref{Type Tree Element Conversion Functions}).

Specific customization variable hashes taking
special element varieties as keys are used in special elements formatting:

@vtable @code
@item SPECIAL_ELEMENTS_HEADING
heading text of the special element.

@item SPECIAL_ELEMENTS_CLASS
string for special element HTML class attributes.

@item SPECIAL_ELEMENTS_DIRECTIONS
direction corresponding to the special element. @xref{Directions}.

@end vtable

@node Beginning and Ending Files
@chapter Beginning and Ending Files

The end of file (footers) formatting function reference is called from the converter
after all the element units in the file have been converted.
The beginning of file (headers) formatting function reference is called right after
the footers formatting function reference.

@xref{Specific formating Functions} for information on how to register and get
the functions references.


@node Customizing HTML File Beginning
@section Customizing HTML File Beginning

@c FIXME following information is also in the Customization
@c variables dicumentation in the Texinfo manual

@vindex DOCTYPE
You can set the variable @code{DOCTYPE} to replace the default.
the @code{DOCTYPE} is output at the very beginning of each output
file.

@vindex EXTRA_HEAD
@vindex AFTER_BODY_OPEN
@cindex @code{<head>} block, adding to
You can define the variable @code{EXTRA_HEAD} to add text within the
@code{<head>} HTML element.  Similarly, the value of
@code{AFTER_BODY_OPEN} is added just after @code{<body>} is output.
These variables are empty by default.

@c @vindex BODYTEXT@r{, in customization}
@vindex BODYTEXT
@cindex @code{<body>} tag, attributes of
The @code{<body>} element attributes may be set by defining the
customization variable @code{BODYTEXT}.

@vindex ENCODING_NAME
@cindex Encoding, in HTML output
By default, the encoding name from @code{ENCODING_NAME} is used.  If
this variable is not defined, it is automatically determined.

@vindex DATE_IN_HEADER
@cindex Date, in header
A date is output in the header if @code{DATE_IN_HEADER} is set.

@cindex Document description, in HTML output
The description from @code{@@documentdescription} (or a value set as a
customization variable) is used in the header
(@pxref{@code{@@documentdescription},,, texinfo, Texinfo}).

@c @vindex LINKS_BUTTONS@r{, in customization}
@c @vindex BUTTONS_REL@r{, in customization}
@vindex LINKS_BUTTONS@r{, in file beginning}
@vindex BUTTONS_REL@r{, in file beginning}
@code{<link>} elements are used in the header if @code{USE_LINKS} is
set, in which case @code{LINKS_BUTTONS} determines which links are
used and @code{BUTTONS_REL} determines the link type associated with
the @code{rel} attribute.  @xref{Simple Navigation Panel Customization}.

@c @vindex HTML_ROOT_ELEMENT_ATTRIBUTES@r{, in customization}
@vindex HTML_ROOT_ELEMENT_ATTRIBUTES
You can set @code{HTML_ROOT_ELEMENT_ATTRIBUTES} to add attributes to
the @code{<html>} element.

The customization variables
@code{SECTION_NAME_IN_TITLE},
@code{PACKAGE_AND_VERSION}, @code{PACKAGE_URL} and other similar variables,
@code{HTML_MATH} and @code{INFO_JS_DIR}
may also be used to change the page header formatting.
@xref{HTML Customization Variables,,, texinfo, Texinfo}.

The following function references give full control over the
page header formatting done at the top of each HTML output file.

@deftypefn {Function Reference} @var{$file_begin} format_begin_file @
               (@var{$converter}, @var{$filename}, @var{\%tree_unit_element})
@cindex @code{<body>} tag, outputting
@var{$filename} is the name of the file output.
@var{\%tree_unit_element} is the first tree unit element of the file.
This function should print the page header, in HTML,
including the @code{<body>} element.
@end deftypefn


@node Customizing HTML File End
@section Customizing HTML File End

@cindex Customizing HTML page footers
@cindex Footer, customizing for HTML

@vindex PRE_BODY_CLOSE
You can define the variable @code{PRE_BODY_CLOSE} to add text just
before the HTML @code{</body>} element.  Nothing is added by default.

@vindex PROGRAM_NAME_IN_FOOTER
If @code{PROGRAM_NAME_IN_FOOTER} is set, the date and name of the
program that generated the output are output in the footer.

The customization variables @code{JS_WEBLABELS} and @code{JS_WEBLABELS_FILE}
are also used in the page footer formatting. @xref{HTML Customization
Variables,,, texinfo, Texinfo}.

The @code{format_end_file} function reference give full control over the page
footer formatting done at the bottom of each HTML output file.

@deftypefn {Function Reference} @var{$file_end} format_end_file @
                                         (@var{$converter}, @var{$filename})
@var{$filename} is the name of the file output.
@cindex @code{</body>} tag, outputting
This function should print the page footer, including
the @code{</body>} element.
@end deftypefn


@node Titlepage@comma{} CSS and Redirection Files
@chapter Titlepage, CSS and Redirection Files

@node HTML Title Page Customization
@section HTML Title Page Customization

@cindex Title page, customization

If @code{SHOW_TITLE} is not set, no title is output.  @code{SHOW_TITLE} is @samp{undef}
in the default case.  If @samp{undef}, @code{SHOW_TITLE} is set if @code{NO_TOP_NODE_OUTPUT}
is set.  The ``title page'' is used to format the HTML title if @code{USE_TITLEPAGE_FOR_TITLE}
is set, otherwise the @code{simpletitle} is used.  @code{USE_TITLEPAGE_FOR_TITLE}
is set in the default case.  @xref{HTML Customization Variables,,, texinfo, Texinfo}.

The following functions references provides full control on the title and
``title page'' formatting:

@deftypefn {Function Reference} @var{$title_titlepage} format_title_titlepage (@var{$converter})
Returns the formatted title or ``title page'' text.

In the default case, return nothing if @code{SHOW_TITLE} is not set, return the
output of @code{format_titlepage} if @code{USE_TITLEPAGE_FOR_TITLE} is set, and
otherwise output a simple title based on @code{simpletitle}.
@end deftypefn

@deftypefn {Function Reference} @var{$title_page} format_titlepage (@var{$converter})
Returns the formatted ``title page'' text.

In the default case, the @code{@@titlepage} is used if found in global information,
otherwise @code{simpletitle} is used (@pxref{Conversion General Information}).
@end deftypefn

@node Customizing CSS
@section Customizing the CSS lines

@xref{Simple Customization of CSS} for information on CSS customization.

The CSS @var{element}.@var{class} that appeared in a file, gathered through
@code{html_attribute_class} calls (@pxref{Formatting HTML Element with
Classes}) are available through the @code{html_get_css_elements_classes}
function:

@deftypefun {@var{@@css_element_classes} =} @var{$converter}->html_get_css_elements_classes @
    (@var{$file_name})
Returns an array containing @code{element.class} pairs of elements and classes
appearing in @var{$file_name}.
@end deftypefun

It is possible to change completely how CSS lines are generated
by redefining the following function reference:

@deftypefn {Function Reference} @var{$css_lines} format_css_lines @
    (@var{$converter}, @var{$file_name})
This function returns the CSS lines and @code{<script>} HTML element
for @var{$file_name}.

In the default case, the function reference uses @code{CSS_REFS} corresponding
to command-line @option{--css-ref}, @code{html_get_css_elements_classes} and
@code{css_get_info} (@pxref{Simple Customization of CSS}) to determine the CSS
lines.
@end deftypefn


@node Customizing Node Redirection Pages
@section Customizing Node Redirection Pages

Node redirection pages are output if @code{NODE_FILES} is set (@pxref{Invoking
@command{texi2any},,, texinfo, Texinfo}).

It is possible to change completely how node redirection pages
are generated by redefining the following function reference:

@deftypefn {Function Reference} @var{$node_redirection_file_content} @
   format_node_redirection_page (@var{$converter}, @var{\%element})
@var{\%element} is a node element needing a redirection page.  A redirection
page is needed if the node file name is not the file name expected for
HTML cross manual references (@pxref{HTML Xref,,, texinfo, Texinfo}).

Returns the content of the node redirection file.
@end deftypefn

@c NOTE format_frame_files is not documented, we do not want users to use/set this
@c we want frames to disappear


@node Specific Functions for Specific Elements
@appendix Specific Functions for Specific Elements

Links on Texinfo perl modules functions or descriptions of functions that can
be used for specific elements formatting:

@table @asis

@item @code{@@today}
@xref{Texinfo::Convert::Utils $tree = expand_today($converter),,
Texinfo::Convert::Utils::expand_today, texi2any_internals}.

@item @code{@@verbatiminclude}
@xref{Texinfo::Convert::Utils $tree = expand_verbatiminclude($registrar@comma{} $configuration_information@comma{} $verbatiminclude),,
Texinfo::Convert::Utils::expand_verbatiminclude, texi2any_internals}.

@item @code{@@def*} @@-commands
@xref{Texinfo::Convert::Utils $arguments = definition_arguments_content($element),,
Texinfo::Convert::Utils::definition_arguments_content, texi2any_internals}.
@xref{Texinfo::Convert::Utils $tree = definition_category_tree($converter@comma{} $def_line),,
Texinfo::Convert::Utils::definition_category_tree, texi2any_internals}.

@item @code{@@float}
@xref{Texinfo::Convert::Converter ($caption@comma{} $prepended) = $converter->float_name_caption ($float),,
Texinfo::Convert::Converter::float_name_caption, texi2any_internals}.
Can be called as @code{$converter->float_name_caption}.

@item accent @@-commands
@xref{Texinfo::Convert::Converter $result = xml_accent($text@comma{} $accent_command@comma{} $in_upper_case@comma{} $use_numeric_entities),,
Texinfo::Convert::Converter::xml_accent, texi2any_internals}.
Can be called as @code{$converter->xml_accent}.

@xref{Texinfo::Convert::Converter $result = xml_numeric_entity_accent($accent_command_name@comma{} $text),,
Texinfo::Convert::Converter::xml_numeric_entity_accent, texi2any_internals}.

@xref{Texinfo::Convert::Converter $result = $converter->convert_accents($accent_command@comma{} \&format_accents@comma{} $in_upper_case),,
Texinfo::Convert::Converter::convert_accents, texi2any_internals}.

@item text element
@xref{Texinfo::Convert::Converter $formatted_text = $converter->xml_format_text_with_numeric_entities($text),,
Texinfo::Convert::Converter::xml_format_text_with_numeric_entities,
texi2any_internals}. Can be called as
@code{$converter->xml_format_text_with_numeric_entities}.

@item @code{@@item} in @code{@@table} and similar @@-commands
@xref{Texinfo::Convert::Converter $table_item_tree = $converter->table_item_content_tree($element@comma{} $contents),,
Texinfo::Convert::Converter::table_item_content_tree, texi2any_internals}.
Can be called as @code{$converter->table_item_content_tree}.

@item @code{@@*index} @code{@@subentry}
@xref{Texinfo::Convert::Converter $contents_array $converter->comma_index_subentries_tree($entry),,
Texinfo::Convert::Converter::comma_index_subentries_tree, texi2any_internals}.
Can be called as @code{$converter->comma_index_subentries_tree}.

@item global informative commands (@code{@@contents}, @code{@@footnotestyle} @enddots{})
@xref{Texinfo::Common set_informative_command_value($configuration_information@comma{} $element),,
Texinfo::Common::set_informative_command_value, texi2any_internals}.

@item heading commands, such as @code{@@subheading}
@xref{Texinfo::Common $level = section_level($section),,
Texinfo::Common::section_level, texi2any_internals}.  This function would work
for sectioning commands too, but for sectioning commands,
@code{section->@{'structure'@}->@{'section_level'@}} can also be used.
@xref{Texinfo Tree Elements in User Defined Functions}.

@item sectioning commands
@xref{Texinfo::Structuring $command_name = section_level_adjusted_command_name($element),,
Texinfo::Structuring::section_level_adjusted_command_name, texi2any_internals}.

@item @code{@@itemize}
@code{@@itemize} normally have an @@-command as argument.  If, instead,
the argument is some Texinfo code, @code{html_convert_css_string_for_list_mark}
can be used to convert that argument to text usable in CSS style specifications.

@deftypefun {@var{$text_for_css} =} @var{$converter}->html_convert_css_string_for_list_mark @
             (@var{\%element}, @var{$explanation})
@var{\%element} is the Texinfo element that is converted to CSS text.
In general, it is @code{$itemize->@{'args'@}->[0]}, with @code{$itemize} an @code{@@itemize}
Texinfo tree element.  @var{$explanation} is an optional string describing what is
being done that can be useful for debugging.

Returns @var{\%element} formatted as text suitable for CSS.
@end deftypefun
@end table

The @code{Texinfo::Convert::NodeNameNormalization} converter, used
for normalization of labels, exports functions that can be used on Texinfo
elements trees to obtain strings that are unique and can be used in attributes.
@xref{Texinfo::Convert::NodeNameNormalization,,,texi2any_internals}.

@node Functions Index
@appendix Functions Index

@printindex fn

@node Variables Index
@appendix Variables Index

@printindex vr

@node General Index
@appendix General Index

@printindex cp


@bye