/usr/share/doc/docutils-doc/docs/dev/todo.html is in docutils-doc 0.13.1+dfsg-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 | <?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.13.1: http://docutils.sourceforge.net/" />
<title>Docutils To Do List</title>
<meta name="author" content="David Goodger (with input from many); open to all Docutils developers" />
<meta name="date" content="2016-07-26" />
<meta name="copyright" content="This document has been placed in the public domain." />
<link rel="stylesheet" href="../../css/html4css1.css" type="text/css" />
</head>
<body>
<div class="document" id="docutils-to-do-list">
<h1 class="title"><a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> To Do List</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>David Goodger (with input from many); open to all Docutils
developers</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first last reference external" href="mailto:docutils-develop@lists.sourceforge.net">docutils-develop@lists.sourceforge.net</a></td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2016-07-26</td></tr>
<tr><th class="docinfo-name">Revision:</th>
<td>7951</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>This document has been placed in the public domain.</td></tr>
</tbody>
</table>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#minimum-requirements-for-python-standard-library-candidacy" id="id17">Minimum Requirements for Python Standard Library Candidacy</a></li>
<li><a class="reference internal" href="#general" id="id18">General</a><ul>
<li><a class="reference internal" href="#object-numbering-and-object-references" id="id19">object numbering and object references</a></li>
</ul>
</li>
<li><a class="reference internal" href="#documentation" id="id20">Documentation</a><ul>
<li><a class="reference internal" href="#user-docs" id="id21">User Docs</a></li>
<li><a class="reference internal" href="#developer-docs" id="id22">Developer Docs</a></li>
<li><a class="reference internal" href="#how-tos" id="id23">How-Tos</a></li>
<li><a class="reference internal" href="#peps" id="id24">PEPs</a></li>
</ul>
</li>
<li><a class="reference internal" href="#python-source-reader" id="id25">Python Source Reader</a></li>
<li><a class="reference internal" href="#restructuredtext-parser" id="id26">reStructuredText Parser</a><ul>
<li><a class="reference internal" href="#misc" id="id27">Misc</a></li>
<li><a class="reference internal" href="#math-markup" id="id28">Math Markup</a><ul>
<li><a class="reference internal" href="#alternative-input-formats" id="id29">alternative input formats</a></li>
<li><a class="reference internal" href="#latex-output" id="id30">LaTeX output</a></li>
<li><a class="reference internal" href="#html-output" id="id31">HTML output</a></li>
<li><a class="reference internal" href="#openoffice-output" id="id32">OpenOffice output</a></li>
</ul>
</li>
<li><a class="reference internal" href="#directives" id="id33">Directives</a></li>
<li><a class="reference internal" href="#interpreted-text" id="id34">Interpreted Text</a></li>
<li><a class="reference internal" href="#doctree-pruning" id="id35">Doctree pruning</a></li>
</ul>
</li>
<li><a class="reference internal" href="#unimplemented-transforms" id="id36">Unimplemented Transforms</a></li>
<li><a class="reference internal" href="#html-writer" id="id37">HTML Writer</a></li>
<li><a class="reference internal" href="#pep-html-writer" id="id38">PEP/HTML Writer</a></li>
<li><a class="reference internal" href="#s5-html-writer" id="id39">S5/HTML Writer</a></li>
<li><a class="reference internal" href="#epub-html-writer" id="id40">Epub/HTML Writer</a></li>
<li><a class="reference internal" href="#latex-writer" id="id41">LaTeX writer</a><ul>
<li><a class="reference internal" href="#bug-fixes" id="id42">Bug fixes</a></li>
<li><a class="reference internal" href="#generate-clean-and-configurable-latex-source" id="id43">Generate clean and configurable LaTeX source</a><ul>
<li><a class="reference internal" href="#configurable-placement-of-figure-and-table-floats" id="id44">Configurable placement of figure and table floats</a></li>
<li><a class="reference internal" href="#latex-constructs-and-packages-instead-of-re-implementations" id="id45">LaTeX constructs and packages instead of re-implementations</a></li>
</ul>
</li>
<li><a class="reference internal" href="#default-layout" id="id46">Default layout</a><ul>
<li><a class="reference internal" href="#tables" id="id47">Tables</a></li>
<li><a class="reference internal" href="#image-and-figure-directives" id="id48">Image and figure directives</a></li>
</ul>
</li>
<li><a class="reference internal" href="#missing-features" id="id49">Missing features</a><ul>
<li><a class="reference internal" href="#unicode-to-latex" id="id50">Unicode to LaTeX</a></li>
<li><a class="reference internal" href="#allow-choice-between-utf8-standard-and-utf8x-extended-encodings" id="id51">Allow choice between utf8 (standard) and utf8x (extended) encodings</a></li>
<li><a class="reference internal" href="#xetex-writer" id="id52">XeTeX writer</a></li>
<li><a class="reference internal" href="#problematic-urls" id="id53">problematic URLs</a></li>
<li><a class="reference internal" href="#add-stylesheet-option" id="id54">add-stylesheet option</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#front-end-tools" id="id55">Front-End Tools</a></li>
</ul>
</div>
<p>Priority items are marked with "@" symbols. The more @s, the higher
the priority. Items in question form (containing "?") are ideas which
require more thought and debate; they are potential to-do's.</p>
<p>Many of these items are awaiting champions. If you see something
you'd like to tackle, please do! If there's something you'd like to
see done but are unable to implement it yourself, please consider
donating to Docutils: <a class="reference external" href="http://sourceforge.net/donate/index.php?group_id=38414">Support the Docutils project!</a></p>
<p>Please see also the <a class="reference external" href="../../BUGS.html">Bugs</a> document for a list of bugs in Docutils.</p>
<div class="section" id="minimum-requirements-for-python-standard-library-candidacy">
<h1><a class="toc-backref" href="#id17">Minimum Requirements for Python Standard Library Candidacy</a></h1>
<p>Below are action items that must be added and issues that must be
addressed before Docutils can be considered suitable to be proposed
for inclusion in the Python standard library.</p>
<p>Many of these are now handled by <a class="reference external" href="http://sphinx.pocoo.org/">Sphinx</a></p>
<ul class="simple">
<li>Support for <a class="reference internal" href="#document-splitting">document splitting</a>. May require some major code
rework.</li>
<li>Support for subdocuments (see <a class="reference internal" href="#large-documents">large documents</a>).</li>
<li><a class="reference internal" href="#object-numbering-and-object-references">Object numbering and object references</a>.</li>
<li><a class="reference internal" href="#nested-inline-markup">Nested inline markup</a>.</li>
<li><a class="reference internal" href="#python-source-reader">Python Source Reader</a>.</li>
<li>The HTML writer needs to be rewritten (or a second HTML writer
added) to allow for custom classes, and for arbitrary splitting
(stack-based?).</li>
<li><a class="reference internal" href="#documentation">Documentation</a> of the architecture. Other docs too.</li>
<li>Plugin support.</li>
<li>Suitability for <a class="reference external" href="http://docutils.sf.net/sandbox/README.html#documenting-python">Python module documentation</a>.</li>
</ul>
</div>
<div class="section" id="general">
<h1><a class="toc-backref" href="#id18">General</a></h1>
<ul>
<li><p class="first">Move to single source for Python 2 and Python 3.
(Cf. <a class="reference external" href="https://docs.python.org/3/howto/pyporting.html">Porting Python 2 Code to Python 3</a> and
<a class="reference external" href="http://python-future.org">clean single-source support for Python 2/3</a>.)</p>
<ul class="simple">
<li>Gradually phase out support for Python 2.4 and 2.5 first.</li>
</ul>
</li>
<li><p class="first">Encoding of command line arguments can only be guessed:</p>
<ul>
<li><p class="first">try UTF-8/strict first, then try the locale's encoding with
strict error handling, then ASCII/replace?</p>
<p>UTF-8 is almost 100% safe to try first; false positives are rare,
The locale's encoding with strict error handling may be a
reasonable compromise, but any error would indicate that the
locale's encoding is inappropriate. The only safe fallback is
ASCII/replace.</p>
</li>
<li><p class="first">Do not decode argv before option parsing but individual string
values?</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">+1</span></kbd></td>
<td><p class="first last">Allows for separate command-line vs. filesystem encodings,
respectively to keep file names encoded.</p>
</td></tr>
<tr><td class="option-group">
<kbd><span class="option">+1</span></kbd></td>
<td><p class="first last">Allows to configure command-line encoding in a config file,</p>
</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-1</span></kbd></td>
<td><p class="first last">More complicated.</p>
</td></tr>
</tbody>
</table>
</li>
</ul>
<p>Cf. <<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/2890/focus=2957">http://thread.gmane.org/gmane.text.docutils.user/2890/focus=2957</a>>.</p>
</li>
<li><p class="first">Improve handling on Windows:</p>
<ul class="simple">
<li>Get graphical installer.</li>
<li>Make rst2html.py an .exe file using py2exe.</li>
</ul>
</li>
<li><p id="gui">The user interface is very difficult to use for most Windows users;
you can't really expect them to use the command line. We need some
kind of GUI that can launch rst2html.py, and save the HTML output to
a file, and launch a browser. What's important is that we get
settings to work with the GUI. So we need some way to dynamically
generate a list of settings for the GUI. The current settings_spec
for OptionParser doesn't seem to be usable for this for the
following reasons:</p>
<ul class="simple">
<li>It's biased toward the command line -- there are <em>two</em> options for
one boolean setting.</li>
<li>You cannot have both a one-line description and a longer
description for tooltips/help-texts.</li>
<li>It doesn't provide hints for the input type. You cannot easily
infer the type of a setting from its validator, because any
component can add new validators. In fact, it may be necessary to
have both a hint about the input type (e.g. string) and a
validator (valid ID), or it may be necessary to have a different
set of choices for the CLI (1, INFO, 2, ...) and for the GUI
(INFO, WARNING, ...).</li>
<li>It's coupled to the OptionParser. We want to be able to change
the underlying system without breaking everything.</li>
<li>It's a bunch of primitive structures. We want an extensible (thus
object-oriented) interface.</li>
</ul>
<p>So we probably need to create a class for storing all the settings,
and auto-generate the OptionParser data from that.</p>
<p>I talked to Stephan Deibel about getting Docutils integrated into
Wing IDE. He said it's possible, and he'd be willing to help.
There's a scripting interface to Wing, which we'd use. We can
dynamically generate a list of preferences and not worry too much
about the rendering (from what I understood); Wing's whole GUI is
dynamic anyway. The interface could be made usable for other GUIs.
For example, we could try to get option support for DocFactory. //
FW</p>
</li>
<li><p class="first">Allow different report levels for STDERR and system_messages inside
the document?</p>
</li>
<li><p class="first">Change the docutils-update script (in sandbox/infrastructure), to
support arbitrary branch snapshots.</p>
</li>
<li><p class="first">Move some general-interest sandboxes out of individuals'
directories, into subprojects?</p>
</li>
<li><p class="first">Add option for file (and URL) access restriction to make Docutils
usable in Wikis and similar applications.</p>
<p>2005-03-21: added <tt class="docutils literal">file_insertion_enabled</tt> & <tt class="docutils literal">raw_enabled</tt>
settings. These partially solve the problem, allowing or disabling
<strong>all</strong> file accesses, but not limited access.</p>
</li>
<li><p class="first">Configuration file handling needs discussion:</p>
<ul class="simple">
<li>There should be some error checking on the contents of config
files. How much checking should be done? How loudly should
Docutils complain if it encounters an error/problem?</li>
<li>Docutils doesn't complain when it doesn't find a configuration
file supplied with the <tt class="docutils literal"><span class="pre">--config</span></tt> option. Should it? (If yes,
error or warning?)</li>
</ul>
</li>
<li><p class="first">Internationalization:</p>
<ul>
<li><p class="first">I18n needs refactoring, the language dictionaries are difficult to
maintain. Maybe have a look at gettext or similar tools.</p>
<p>(This would make a nice Google Summer of Code project)</p>
</li>
<li><p class="first">Language modules: in accented languages it may be useful to have
both accented and unaccented entries in the
<tt class="docutils literal">bibliographic_fields</tt> mapping for versatility.</p>
</li>
<li><p class="first">Add a "--strict-language" option & setting: no English fallback
for language-dependent features.</p>
<p>Make this the default for output (as opposed to input)?
Throw an error with a helpfull message, e.g.</p>
<blockquote>
<p>Default "contents" title for language %s missing, please specify
an explicit title.</p>
</blockquote>
<p>or</p>
<blockquote>
<p>"attention" title for language %s missing, please use a generic
admonition with explicit title.</p>
</blockquote>
</li>
<li><p class="first">Add internationalization to <span class="target" id="footer-boilerplate-text">footer boilerplate text</span> (resulting
from "--generator", "--source-link", and "--date" etc.), allowing
translations.</p>
</li>
</ul>
</li>
<li><p class="first">Add validation? See <a class="reference external" href="http://pytrex.sourceforge.net">http://pytrex.sourceforge.net</a>, RELAX NG, pyRXP.</p>
</li>
<li><p class="first">In <tt class="docutils literal">docutils.readers.get_reader_class</tt> (& <tt class="docutils literal">parsers</tt> &
<tt class="docutils literal">writers</tt> too), should we be importing "standalone" or
"docutils.readers.standalone"? (This would avoid importing
top-level modules if the module name is not in docutils/readers.
Potential nastiness.)</p>
</li>
<li><p class="first">Perhaps store a <span class="target" id="name-to-id-mapping-file">name-to-id mapping file</span>? This could be stored
permanently, read by subsequent processing runs, and updated with
new entries. ("Persistent ID mapping"?)</p>
</li>
<li><p class="first">Perhaps the <tt class="docutils literal">Component.supports</tt> method should deal with
individual features ("meta" etc.) instead of formats ("html" etc.)?</p>
</li>
<li><p class="first">Think about <span class="target" id="large-documents">large documents</span> made up of multiple subdocument
files. Issues: continuity (<a class="reference internal" href="#persistent-sequences">persistent sequences</a> above),
cross-references (<a class="reference internal" href="#name-to-id-mapping-file">name-to-id mapping file</a> above and <a class="reference internal" href="#targets-in-other-documents">targets in
other documents</a> below), splitting (<a class="reference internal" href="#document-splitting">document splitting</a> below).</p>
<p>When writing a book, the author probably wants to split it up into
files, perhaps one per chapter (but perhaps even more detailed).
However, we'd like to be able to have references from one chapter to
another, and have continuous numbering (pages and chapters, as
applicable). Of course, none of this is implemented yet. There has
been some thought put into some aspects; see <a class="reference external" href="../ref/rst/directives.html#including-an-external-document-fragment">the "include"
directive</a> and the <a class="reference internal" href="#reference-merging">Reference Merging</a> transform below.</p>
<p>When I was working with SGML in Japan, we had a system where there
was a top-level coordinating file, book.sgml, which contained the
top-level structure of a book: the <book> element, containing the
book <title> and empty component elements (<preface>, <chapter>,
<appendix>, etc.), each with filename attributes pointing to the
actual source for the component. Something like this:</p>
<pre class="literal-block">
<book id="bk01">
<title>Title of the Book</title>
<preface inrefid="pr01"></preface>
<chapter inrefid="ch01"></chapter>
<chapter inrefid="ch02"></chapter>
<chapter inrefid="ch03"></chapter>
<appendix inrefid="ap01"></appendix>
</book>
</pre>
<p>(The "inrefid" attribute stood for "insertion reference ID".)</p>
<p>The processing system would process each component separately, but
it would recognize and use the book file to coordinate chapter and
page numbering, and keep a persistent ID to (title, page number)
mapping database for cross-references. Docutils could use a similar
system for large-scale, multipart documents.</p>
<p>Aahz's idea:</p>
<blockquote>
<p>First the ToC:</p>
<pre class="literal-block">
.. ToC-list::
Introduction.txt
Objects.txt
Data.txt
Control.txt
</pre>
<p>Then a sample use:</p>
<pre class="literal-block">
.. include:: ToC.txt
As I said earlier in chapter :chapter:`Objects.txt`, the
reference count gets increased every time a binding is made.
</pre>
<p>Which produces:</p>
<pre class="literal-block">
As I said earlier in chapter 2, the
reference count gets increased every time a binding is made.
</pre>
<p>The ToC in this form doesn't even need to be references to actual
reST documents; I'm simply doing it that way for a minimum of
future-proofing, in case I do want to add the ability to pick up
references within external chapters.</p>
</blockquote>
<p>Perhaps, instead of ToC (which would overload the "contents"
directive concept already in use), we could use "manifest". A
"manifest" directive might associate local reference names with
files:</p>
<pre class="literal-block">
.. manifest::
intro: Introduction.txt
objects: Objects.txt
data: Data.txt
control: Control.txt
</pre>
<p>Then the sample becomes:</p>
<pre class="literal-block">
.. include:: manifest.txt
As I said earlier in chapter :chapter:`objects`, the
reference count gets increased every time a binding is made.
</pre>
</li>
<li><p class="first">Add support for <span class="target" id="multiple-output-files">multiple output files</span> and <span class="target" id="generic-data-handling">generic data
handling</span>:</p>
<p>It should be possible for a component to <strong>emit or reference</strong> data
to be either <strong>included or referenced</strong> in the output document.
Examples of such data are stylesheets or images.</p>
<p>For this, we need a "data" object which stores the data either
inline or by referring to a file. The Docutils framework is
responsible for either:</p>
<ul class="simple">
<li>storing the data in the appropriate location (e.g. in the
directory of the output file, or in a user-specified directory)
and providing the paths of the stored files to the writer, <em>or</em></li>
<li>providing the data itself to the writer so that it can be embedded
in the output document.</li>
</ul>
<p>This approach decouples data handling from the data source (which
can either be embedded or referenced) and the destination (which can
either be embedded or referenced as well).</p>
<p>See <<a class="reference external" href="http://article.gmane.org/gmane.text.docutils.devel/3631">http://article.gmane.org/gmane.text.docutils.devel/3631</a>>.</p>
</li>
<li><p class="first">Add testing for Docutils' front end tools?</p>
</li>
<li><p class="first">Publisher: "Ordinary setup" shouldn't requre specific ordering; at
the very least, there ought to be error checking higher up in the
call chain. [Aahz]</p>
<p><tt class="docutils literal">Publisher.get_settings</tt> requires that all components be set up
before it's called. Perhaps the I/O <em>objects</em> shouldn't be set, but
I/O <em>classes</em>. Then options are set up (<tt class="docutils literal">.set_options</tt>), and
<tt class="docutils literal">Publisher.set_io</tt> (or equivalent code) is called with source &
destination paths, creating the I/O objects.</p>
<p>Perhaps I/O objects shouldn't be instantiated until required. For
split output, the Writer may be called multiple times, once for each
doctree, and each doctree should have a separate Output object (with
a different path). Is the "Builder" pattern applicable here?</p>
</li>
<li><p class="first">Perhaps I/O objects should become full-fledged components (i.e.
subclasses of <tt class="docutils literal">docutils.Component</tt>, as are Readers, Parsers, and
Writers now), and thus have associated option/setting specs and
transforms.</p>
</li>
<li><p class="first">Multiple file I/O suggestion from Michael Hudson: use a file-like
object or something you can iterate over to get file-like objects.</p>
</li>
<li><p class="first">Add an "--input-language" option & setting? Specify a different
language module for input (bibliographic fields, directives) than
for output. The "--language" option would set both input & output
languages.</p>
</li>
<li><p class="first">Auto-generate reference tables for language-dependent features?
Could be generated from the source modules. A special command-line
option could be added to Docutils front ends to do this. (Idea from
Engelbert Gruber.)</p>
</li>
<li><p class="first">Enable feedback of some kind from internal decisions, such as
reporting the successful input encoding. Modify runtime settings?
System message? Simple stderr output?</p>
</li>
<li><p class="first">Rationalize Writer settings (HTML/LaTeX/PEP) -- share settings.</p>
</li>
<li><p class="first">Add an "--include file" command-line option (config setting too?),
equivalent to ".. include:: file" as the first line of the doc text?
Especially useful for character entity sets, text transform specs,
boilerplate, etc.</p>
</li>
<li><p class="first">Support "include" as embedded inline-compatible directive in substitution
definitions, e.g.</p>
<pre class="literal-block">
.. |version| include:: version.txt
This document describes version |version| of ...
</pre>
<p>(cf. Grzegorz Adam Hankiewicz's post from 2014-10-01 in docutils-devel)</p>
</li>
<li><p class="first">Add an <tt class="docutils literal">:optional: <replacement text></tt> option to the "include"
directive? This would not throw an error for a missing file, instead a
warning is given and <tt class="docutils literal"><replacement text></tt> is used instead. It would be
the responsibility of the author to ensure the missing file does not lead
to problems later in the document.</p>
<p>Use cases:</p>
<ul>
<li><p class="first">Standard rST syntax to replace Sphinx's "literalinclude":</p>
<pre class="literal-block">
.. include:: blah.cpp
:literal:
:optional: file ``blah.cpp`` not found
</pre>
</li>
<li><p class="first">Variable content taken from a file, e.g.</p>
<p>version.txt:</p>
<pre class="literal-block">
.. |version| replace:: 3.1
</pre>
<p>optionally used as:</p>
<pre class="literal-block">
.. include:: version.txt
:optional: .. |version| replace:: unknown
This document describes version |version| of ...
</pre>
<p>(cf. Grzegorz Adam Hankiewicz's post from 2014-10-01 in docutils-devel)</p>
</li>
</ul>
</li>
<li><p class="first">Parameterize the Reporter object or class? See the <a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/1112">2004-02-18
"rest checking and source path"</a> thread.</p>
</li>
<li><p class="first">Add a "disable_transforms" setting? And a dummy Writer subclass
that does nothing when its .write() method is called? Would allow
for easy syntax checking. See the <a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/1112">2004-02-18 "rest checking and
source path"</a> thread.</p>
</li>
<li><p class="first">Add a generic meta-stylesheet mechanism? An external file could
associate style names ("class" attributes) with specific elements.
Could be generalized to arbitrary output attributes; useful for HTML
& XMLs. Aahz implemented something like this in
sandbox/aahz/Effective/EffMap.py.</p>
</li>
<li><p id="classes-for-table-cells">William Dode suggested that table cells be assigned "class"
attributes by columns, so that stylesheets can affect text
alignment. Unfortunately, there doesn't seem to be a way (in HTML
at least) to leverage the "colspec" elements (HTML "col" tags) by
adding classes to them. The resulting HTML is very verbose:</p>
<pre class="literal-block">
<td class="col1">111</td>
<td class="col2">222</td>
...
</pre>
<p>At the very least, it should be an option. People who don't use it
shouldn't be penalized by increases in their HTML file sizes.</p>
<p>Table rows could also be assigned classes (like odd/even). That
would be easier to implement.</p>
<p>How should it be implemented?</p>
<ul class="simple">
<li>There could be writer options (column classes & row classes) with
standard values.</li>
<li>The table directive could grow some options. Something like
":cell-classes: col1 col2 col3" (either must match the number of
columns, or repeat to fill?) and ":row-classes: odd even" (repeat
to fill; body rows only, or header rows too?).</li>
</ul>
<p>Probably per-table directive options are best. The "class" values
could be used by any writer, and applying such classes to all tables
in a document with writer options is too broad.</p>
</li>
<li><p class="first">Add file-specific settings support to config files, like:</p>
<pre class="literal-block">
[file index.txt]
compact-lists: no
</pre>
<p>Is this even possible? Should the criterion be the name of the
input file or the output file? Alternative (more explicit) syntax:</p>
<pre class="literal-block">
[source_file index.txt]
...
[dest_file index.html]
...
</pre>
<p>Or rather allow settings configuration from the rst source file
(see <a class="reference internal" href="#misc-settings">misc.settings</a> directive)?</p>
</li>
<li><p class="first">The "validator" support added to OptionParser is very similar to
"<a class="reference external" href="http://code.enthought.com/traits/">traits</a>" in <a class="reference external" href="http://www.scipy.org/">SciPy</a>. Perhaps something could be done with them?
(Had I known about traits when I was implementing docutils.frontend,
I may have used them instead of rolling my own.)</p>
</li>
<li><p class="first">tools/buildhtml.py: Extend the --prune option ("prune" config
setting) to accept file names (generic path) in addition to
directories (e.g. --prune=docs/user/rst/cheatsheet.txt, which should
<em>not</em> be converted to HTML).</p>
</li>
<li><p class="first">Add support for <span class="target" id="plugins">plugins</span>.</p>
</li>
<li><p class="first"><span class="target" id="config-directories">Config directories</span>: Currently, ~/.docutils, ./docutils.conf/, &
/etc/docutils.conf are read as configuration files. Proposal: allow
~/.docutils to be a a configuration <em>directory</em>, along with
/etc/docutils/ and ./docutils.conf/. Within these directories,
check for config.txt files. We can also have subdirectories here,
for plugins, S5 themes, components (readers/writers/parsers) etc.</p>
<p>Docutils will continue to support configuration files for backwards
compatibility.</p>
</li>
<li><p class="first">Add support for document decorations other than headers & footers?
For example, top/bottom/side navigation bars for web pages. Generic
decorations?</p>
<p>Seems like a bad idea as long as it isn't independent from the ouput
format (for example, navigation bars are only useful for web pages).</p>
</li>
<li><p class="first">docutils_update: Check for a <tt class="docutils literal">Makefile</tt> in a directory, and run
<tt class="docutils literal">make</tt> if found? This would allow for variant processing on
specific source files, such as running rst2s5.py instead of
rst2html.py.</p>
</li>
<li><p class="first">Add a "disable table of contents" setting? The S5 writer could set
it as a default. Rationale:</p>
<blockquote>
<p>The <tt class="docutils literal">contents</tt> (table of contents) directive must not be used
[in S5/HTML documents]. It changes the CSS class of headings
and they won't show up correctly in the screen presentation.</p>
<p class="attribution">—<a class="reference external" href="../user/slide-shows.html">Easy Slide Shows With reStructuredText & S5</a></p>
</blockquote>
<p>Analogue to the <tt class="docutils literal">sectnum_xform</tt> setting, it could be used by the
latex writer to switch to a LaTeX generated ToC (currently, the latex
writer calls it "use_latex_toc").</p>
</li>
</ul>
<div class="section" id="object-numbering-and-object-references">
<h2><a class="toc-backref" href="#id19">object numbering and object references</a></h2>
<p>For equations, tables & figures.</p>
<p>These would be the equivalent of DocBook's "formal" elements.</p>
<p>In LaTeX, automatic counters are implemented for sections, equations and
floats (figures, tables) (configurable via stylesheets or in the
latex-preamble). Objects can be given <a class="reference external" href="../ref/rst/restructuredtext.html#reference-names">reference names</a> with the
<tt class="docutils literal"><span class="pre">\label{<refname}</span></tt> command, <tt class="docutils literal"><span class="pre">\ref{<refname>}</span></tt> inserts the
corresponding number.</p>
<p>No such mechanism exists in HTML.</p>
<ul>
<li><p class="first">We need <span class="target" id="persistent-sequences">persistent sequences</span>, similar to chapter and footnote
numbers. See <a class="reference external" href="http://xml.openoffice.org/">OpenOffice.org XML</a> "fields".</p>
<ul class="simple">
<li>Should the sequences be automatic or manual (user-specifyable)?</li>
</ul>
</li>
<li><p class="first">It is already possible to give <a class="reference external" href="../ref/rst/restructuredtext.html#reference-names">reference names</a> to objects via
internal hyperlink targets or the "name" directive option:</p>
<pre class="literal-block">
.. _figure name:
.. figure:: image.png
</pre>
<p>or</p>
<pre class="literal-block">
.. figure:: image.png
:name: figure name
</pre>
<p>Improve the mapping of "phrase references" to IDs/labels with
Literal transcription (i.e. ü -> ue, ß -> ss, å -> aa) instead of just
stripping the accents and other non-ASCII chars.
Use <a class="reference external" href="http://pypi.python.org/pypi/Unidecode">http://pypi.python.org/pypi/Unidecode</a>?</p>
<p>A "table" directive has been implemented, supporting table titles.</p>
<p>Perhaps the name could derive from the title/caption?</p>
</li>
<li><p class="first">We need syntax for object references. Cf. <a class="reference external" href="http://xml.openoffice.org/">OpenOffice.org XML</a>
"reference fields":</p>
<ul>
<li><p class="first">Parameterized substitutions are too complicated
(cf. <cite>or not to do</cite>: <a class="reference external" href="rst/alternatives.html#object-references">object references</a>)</p>
</li>
<li><p class="first">An interpreted text approach is simpler and better:</p>
<pre class="literal-block">
See Figure :ref:`figure name` and Equation :ref:`eq:identity`.
</pre>
</li>
<li><p class="first">"equation", "figure", and "page" roles could generate appropriate
boilerplate text:</p>
<pre class="literal-block">
See :figure:`figure name` on :page:`figure name`.
</pre>
<p>See <a class="reference internal" href="#interpreted-text">Interpreted Text</a> below.</p>
<p>Reference boilerplate could be specified in the document
(defaulting to nothing):</p>
<pre class="literal-block">
.. fignum::
:prefix-ref: "Figure "
:prefix-caption: "Fig. "
:suffix-caption: :
</pre>
<p>The position of the role (prefix or suffix) could also be utilized</p>
</li>
</ul>
</li>
</ul>
<p>See also the <a class="reference external" href="http://www.loria.fr/~rougier/coding/article/rst2html.py">Modified rst2html</a>
by Nicolas Rougier for a sample implementation.</p>
</div>
</div>
<div class="section" id="documentation">
<h1><a class="toc-backref" href="#id20">Documentation</a></h1>
<div class="section" id="user-docs">
<h2><a class="toc-backref" href="#id21">User Docs</a></h2>
<ul class="simple">
<li>Add a FAQ entry about using Docutils (with reStructuredText) on a
server and that it's terribly slow. See the first paragraphs in
<<a class="reference external" href="http://article.gmane.org/gmane.text.docutils.user/1584">http://article.gmane.org/gmane.text.docutils.user/1584</a>>.</li>
<li>Add document about what Docutils has previously been used for
(web/use-cases.txt?).</li>
<li>Improve index in docs/user/config.txt.</li>
</ul>
</div>
<div class="section" id="developer-docs">
<h2><a class="toc-backref" href="#id22">Developer Docs</a></h2>
<ul class="simple">
<li>Complete <a class="reference external" href="../api/runtime-settings.html">Docutils Runtime Settings</a>.</li>
<li>Improve the internal module documentation (docstrings in the code).
Specific deficiencies listed below.<ul>
<li>docutils.parsers.rst.states.State.build_table: data structure
required (including StringList).</li>
<li>docutils.parsers.rst.states: more complete documentation of parser
internals.</li>
</ul>
</li>
<li>docs/ref/doctree.txt: DTD element structural relationships,
semantics, and attributes. In progress; element descriptions to be
completed.</li>
<li>Document the <tt class="docutils literal">pending</tt> elements, how they're generated and what
they do.</li>
<li>Document the transforms (perhaps in docstrings?): how they're used,
what they do, dependencies & order considerations.</li>
<li>Document the HTML classes used by html4css1.py.</li>
<li>Write an overview of the Docutils architecture, as an introduction
for developers. What connects to what, why, and how. Either update
PEP 258 (see <a class="reference internal" href="#peps">PEPs</a> below) or as a separate doc.</li>
<li>Give information about unit tests. Maybe as a howto?</li>
<li>Document the docutils.nodes APIs.</li>
<li>Complete the docs/api/publisher.txt docs.</li>
</ul>
</div>
<div class="section" id="how-tos">
<h2><a class="toc-backref" href="#id23">How-Tos</a></h2>
<ul class="simple">
<li>Creating Docutils Writers</li>
<li>Creating Docutils Readers</li>
<li>Creating Docutils Transforms</li>
<li>Creating Docutils Parsers</li>
<li>Using Docutils as a Library</li>
</ul>
</div>
<div class="section" id="peps">
<h2><a class="toc-backref" href="#id24">PEPs</a></h2>
<ul>
<li><p class="first">Complete PEP 258 Docutils Design Specification.</p>
<ul>
<li><p class="first">Fill in the blanks in API details.</p>
</li>
<li><p class="first">Specify the nodes.py internal data structure implementation?</p>
<blockquote>
<p>[Tibs:] Eventually we need to have direct documentation in
there on how it all hangs together - the DTD is not enough
(indeed, is it still meant to be correct? [Yes, it is.
--DG]).</p>
</blockquote>
</li>
</ul>
</li>
<li><p class="first">Rework PEP 257, separating style from spec from tools, wrt Docutils?
See Doc-SIG from 2001-06-19/20.</p>
</li>
</ul>
</div>
</div>
<div class="section" id="python-source-reader">
<h1><a class="toc-backref" href="#id25">Python Source Reader</a></h1>
<p>General:</p>
<ul class="simple">
<li>Analyze Tony Ibbs' PySource code.</li>
<li>Analyze Doug Hellmann's HappyDoc project.</li>
<li>Investigate how POD handles literate programming.</li>
<li>Take the best ideas and integrate them into Docutils.</li>
</ul>
<p>Miscellaneous ideas:</p>
<ul>
<li><p class="first">Ask Python-dev for opinions (GvR for a pronouncement) on special
variables (__author__, __version__, etc.): convenience vs. namespace
pollution. Ask opinions on whether or not Docutils should recognize
& use them.</p>
</li>
<li><p class="first">If we can detect that a comment block begins with <tt class="docutils literal">##</tt>, a la
JavaDoc, it might be useful to indicate interspersed section headers
& explanatory text in a module. For example:</p>
<pre class="literal-block">
"""Module docstring."""
##
# Constants
# =========
a = 1
b = 2
##
# Exception Classes
# =================
class MyException(Exception): pass
# etc.
</pre>
</li>
<li><p class="first">Should standalone strings also become (module/class) docstrings?
Under what conditions? We want to prevent arbitrary strings from
becomming docstrings of prior attribute assignments etc. Assume
that there must be no blank lines between attributes and attribute
docstrings? (Use lineno of NEWLINE token.)</p>
<p>Triple-quotes are sometimes used for multi-line comments (such as
commenting out blocks of code). How to reconcile?</p>
</li>
<li><p class="first">HappyDoc's idea of using comment blocks when there's no docstring
may be useful to get around the conflict between <a class="reference external" href="../peps/pep-0258.html#additional-docstrings">additional
docstrings</a> and <tt class="docutils literal">from __future__ import</tt> for module docstrings.
A module could begin like this:</p>
<pre class="literal-block">
#!/usr/bin/env python
# :Author: Me
# :Copyright: whatever
"""This is the public module docstring (``__doc__``)."""
# More docs, in comments.
# All comments at the beginning of a module could be
# accumulated as docstrings.
# We can't have another docstring here, because of the
# ``__future__`` statement.
from __future__ import division
</pre>
<p>Using the JavaDoc convention of a doc-comment block beginning with
<tt class="docutils literal">##</tt> is useful though. It allows doc-comments and implementation
comments.</p>
</li>
<li><p class="first">HappyDoc uses an initial comment block to set "parser configuration
values". Do the same thing for Docutils, to set runtime settings on
a per-module basis? I.e.:</p>
<pre class="literal-block">
# Docutils:setting=value
</pre>
<p>Could be used to turn on/off function parameter comment recognition
& other marginal features. Could be used as a general mechanism to
augment config files and command-line options (but which takes
precedence?).</p>
</li>
<li><p class="first">Multi-file output should be divisible at arbitrary level.</p>
</li>
<li><p class="first">Support all forms of <tt class="docutils literal">import</tt> statements:</p>
<ul class="simple">
<li><tt class="docutils literal">import module</tt>: listed as "module"</li>
<li><tt class="docutils literal">import module as alias</tt>: "alias (module)"</li>
<li><tt class="docutils literal">from module import identifier</tt>: "identifier (from module)"</li>
<li><tt class="docutils literal">from module import identifier as alias</tt>: "alias (identifier
from module)"</li>
<li><tt class="docutils literal">from module import *</tt>: "all identifiers (<tt class="docutils literal">*</tt>) from module"</li>
</ul>
</li>
<li><p class="first">Have links to colorized Python source files from API docs? And
vice-versa: backlinks from the colorized source files to the API
docs!</p>
</li>
<li><p class="first">In summaries, use the first <em>sentence</em> of a docstring if the first
line is not followed by a blank line.</p>
</li>
</ul>
</div>
<div class="section" id="restructuredtext-parser">
<h1><a class="toc-backref" href="#id26">reStructuredText Parser</a></h1>
<p>Also see the <a class="reference external" href="rst/alternatives.html#or-not-to-do">... Or Not To Do?</a> list.</p>
<div class="section" id="misc">
<h2><a class="toc-backref" href="#id27">Misc</a></h2>
<ul>
<li><p class="first">Another list problem:</p>
<pre class="literal-block">
* foo
* bar
* baz
</pre>
<p>This ends up as a definition list. This is more of a usability
issue.</p>
</li>
<li><p class="first">This case is probably meant to be a nested list, but it ends up as a
list inside a block-quote without an error message:</p>
<pre class="literal-block">
- foo
- bar
</pre>
<p>It should probably just be an error.</p>
<p>The problem with this is that you don't notice easily in HTML that
it's not a nested list but a block-quote -- there's not much of a
visual difference.</p>
</li>
<li><p class="first">Treat enumerated lists that are not arabic and consist of only one
item in a single line as ordinary paragraphs. See
<<a class="reference external" href="http://article.gmane.org/gmane.text.docutils.user/2635">http://article.gmane.org/gmane.text.docutils.user/2635</a>>.</p>
</li>
<li><p class="first">The citation syntax could use some improvements. See
<<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/2499">http://thread.gmane.org/gmane.text.docutils.user/2499</a>> (and the
sub-thread at
<<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/2499/focus=3028">http://thread.gmane.org/gmane.text.docutils.user/2499/focus=3028</a>>,
and the follow-ups at
<<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/3087">http://thread.gmane.org/gmane.text.docutils.user/3087</a>>,
<<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/3110">http://thread.gmane.org/gmane.text.docutils.user/3110</a>>,
<<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/3114">http://thread.gmane.org/gmane.text.docutils.user/3114</a>>),
<<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/2443">http://thread.gmane.org/gmane.text.docutils.user/2443</a>>,
<<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/2715">http://thread.gmane.org/gmane.text.docutils.user/2715</a>>,
<<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/3027">http://thread.gmane.org/gmane.text.docutils.user/3027</a>>,
<<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/3120">http://thread.gmane.org/gmane.text.docutils.user/3120</a>>,
<<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/3253">http://thread.gmane.org/gmane.text.docutils.user/3253</a>>.</p>
</li>
<li><p class="first">The current list-recognition logic has too many false positives, as
in</p>
<pre class="literal-block">
* Aorta
* V. cava superior
* V. cava inferior
</pre>
<p>Here <tt class="docutils literal">V.</tt> is recognized as an enumerator, which leads to
confusion. We need to find a solution that resolves such problems
without complicating the spec to much.</p>
<p>See <<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/2524">http://thread.gmane.org/gmane.text.docutils.user/2524</a>>.</p>
</li>
<li><p class="first">Add indirect links via citation references & footnote references.
Example:</p>
<pre class="literal-block">
`Goodger (2005)`_ is helpful.
.. _Goodger (2005): [goodger2005]_
.. [goodger2005] citation text
</pre>
<p>See <<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/2499">http://thread.gmane.org/gmane.text.docutils.user/2499</a>>.</p>
</li>
<li><p class="first">Complain about bad URI characters
(<a class="reference external" href="http://article.gmane.org/gmane.text.docutils.user/2046">http://article.gmane.org/gmane.text.docutils.user/2046</a>) and
disallow internal whitespace
(<a class="reference external" href="http://article.gmane.org/gmane.text.docutils.user/2214">http://article.gmane.org/gmane.text.docutils.user/2214</a>).</p>
</li>
<li><p class="first">Create <tt class="docutils literal">info</tt>-level system messages for unnecessarily
backslash-escaped characters (as in <tt class="docutils literal">"\something"</tt>, rendered as
"something") to allow checking for errors which silently slipped
through.</p>
</li>
<li><p class="first">Add (functional) tests for untested roles.</p>
</li>
<li><p class="first">Add test for ":figwidth: image" option of "figure" directive. (Test
code needs to check if PIL is available on the system.)</p>
</li>
<li><p class="first">Add support for CJK double-width whitespace (indentation) &
punctuation characters (markup; e.g. double-width "*", "-", "+")?</p>
</li>
<li><p class="first">Add motivation sections for constructs in spec.</p>
</li>
<li><p class="first">Support generic hyperlink references to <span class="target" id="targets-in-other-documents">targets in other
documents</span>? Not in an HTML-centric way, though (it's trivial to say
<tt class="docutils literal"><span class="pre">http://www.example.com/doc#name</span></tt>, and useless in non-HTML
contexts). XLink/XPointer? <tt class="docutils literal">.. baseref::</tt>? See Doc-SIG
2001-08-10.</p>
</li>
<li><p id="adaptable-file-extensions">In target URLs, it would be useful to not explicitly specify the
file extension. If we're generating HTML, then ".html" is
appropriate; if PDF, then ".pdf"; etc. How about using ".*" to
indicate "choose the most appropriate filename extension"? For
example:</p>
<pre class="literal-block">
.. _Another Document: another.*
</pre>
<p>What is to be done for output formats that don't <em>have</em> hyperlinks?
For example, LaTeX targeted at print. Hyperlinks may be "called
out", as footnotes with explicit URLs. (Don't convert the links.)</p>
<p>But then there's also LaTeX targeted at PDFs, which <em>can</em> have
links. Perhaps a runtime setting for "*" could explicitly provide
the extension, defaulting to the output file's extension.</p>
<p>Should the system check for existing files? No, not practical.</p>
<p>Handle documents only, or objects (images, etc.) also?</p>
<p>If this handles images also, how to differentiate between document
and image links? Element context (within "image")? Which image
extension to use for which document format? Again, a runtime
setting would suffice.</p>
<p>This may not be just a parser issue; it may need framework support.</p>
<p>Mailing list threads: <a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/1239">Images in both HTML and LaTeX</a> (especially
<a class="reference external" href="http://article.gmane.org/gmane.text.docutils.user/1278">this summary of Lea's objections</a>), <a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/1915">more-universal links?</a>,
<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/2438">Output-format-sensitive link targets?</a></p>
<p>Idea from Jim Fulton: an external lookup table of targets:</p>
<blockquote>
<p>I would like to specify the extension (e.g. .txt) [in the
source, rather than <tt class="docutils literal">filename.*</tt>], but tell the converter to
change references to the files anticipating that the files will
be converted too.</p>
<p>For example:</p>
<pre class="literal-block">
.. _Another Document: another.txt
rst2html.py --convert-links "another.txt bar.txt" foo.txt
</pre>
<p>That is, name the files for which extensions should be converted.</p>
<p>Note that I want to refer to original files in the original text
(another.txt rather than another.txt) because I want the
unconverted text to stand on its own.</p>
<p>Note that in most cases, people will be able to use globs:</p>
<pre class="literal-block">
rst2html.py --convert-link-extensions-for "`echo *.txt`" foo.txt
</pre>
<p>It might be nice to be able to use multiple arguments, as in:</p>
<pre class="literal-block">
rst2html.py --convert-link-extensions-for *.txt -- foo.txt
</pre>
<pre class="literal-block">
> What is to be done for output formats
> that don't have hyperlinks?
</pre>
<p>Don't convert the links.</p>
<pre class="literal-block">
> Handle documents only, or objects
> (images, etc.) also?
</pre>
<p>No, documents only, but there really is no need for gueswork.
Just get the file names as command-line arguments. EIBTI
[explicit is better than implicit].</p>
</blockquote>
<p>For images, we probably need separate solution (which is being
worked on), whereas for documents, the issue is basically
interlinking between reStructuredText documents. IMO, this cries
for support for multiple input and output files, i.e. support for
documents which comprise multiple files. Adding adaptable file
extensions seems like a kludge. // FW</p>
</li>
<li><p class="first">Implement the header row separator modification to table.el. (Wrote
to Takaaki Ota & the table.el mailing list on 2001-08-12, suggesting
support for "=====" header rows. On 2001-08-17 he replied, saying
he'd put it on his to-do list, but "don't hold your breath".)</p>
</li>
<li><p class="first">Fix the parser's indentation handling to conform with the stricter
definition in the spec. (Explicit markup blocks should be strict or
forgiving?)</p>
<!-- XXX What does this mean? Can you elaborate, David? -->
</li>
<li><p class="first">Make the parser modular. Allow syntax constructs to be added or
disabled at run-time. Subclassing is probably not enough because it
makes it difficult to apply multiple extensions.</p>
</li>
<li><p class="first">Generalize the "doctest block" construct (which is overly
Python-centric) to other interactive sessions? "Doctest block"
could be renamed to "I/O block" or "interactive block", and each of
these could also be recognized as such by the parser:</p>
<ul>
<li><p class="first">Shell sessions:</p>
<pre class="literal-block">
$ cat example1.txt
A block beginning with a "$ " prompt is interpreted as a shell
session interactive block. As with Doctest blocks, the
interactive block ends with the first blank line, and wouldn't
have to be indented.
</pre>
</li>
<li><p class="first">Root shell sessions:</p>
<pre class="literal-block">
# cat example2.txt
A block beginning with a "# " prompt is interpreted as a root
shell session (the user is or has to be logged in as root)
interactive block. Again, the block ends with a blank line.
</pre>
</li>
</ul>
<p>Other standard (and unambiguous) interactive session prompts could
easily be added (such as "> " for WinDOS).</p>
<p>Tony Ibbs spoke out against this idea (2002-06-14 Doc-SIG thread
"docutils feedback").</p>
</li>
<li><p class="first">Add support for pragma (syntax-altering) directives.</p>
<p>Some pragma directives could be local-scope unless explicitly
specified as global/pragma using ":global:" options.</p>
</li>
<li><p class="first">Support whitespace in angle-bracketed standalone URLs according to
Appendix E ("Recommendations for Delimiting URI in Context") of <a class="reference external" href="http://www.rfc-editor.org/rfc/rfc2396.txt">RFC
2396</a>.</p>
</li>
<li><p class="first">Use the vertical spacing of the source text to determine the
corresponding vertical spacing of the output?</p>
</li>
<li><p class="first">[From Mark Nodine] For cells in simple tables that comprise a
single line, the justification can be inferred according to the
following rules:</p>
<ol class="arabic simple">
<li>If the text begins at the leftmost column of the cell,
then left justification, ELSE</li>
<li>If the text begins at the rightmost column of the cell,
then right justification, ELSE</li>
<li>Center justification.</li>
</ol>
<p>The onus is on the author to make the text unambiguous by adding
blank columns as necessary. There should be a parser setting to
turn off justification-recognition (normally on would be fine).</p>
<p>Decimal justification?</p>
<p>All this shouldn't be done automatically. Only when it's requested
by the user, e.g. with something like this:</p>
<pre class="literal-block">
.. table::
:auto-indent:
(Table goes here.)
</pre>
<p>Otherwise it will break existing documents.</p>
</li>
<li><p class="first">Generate a warning or info message for paragraphs which should have
been lists, like this one:</p>
<pre class="literal-block">
1. line one
3. line two
</pre>
</li>
<li><p class="first">Generalize the "target-notes" directive into a command-line option
somehow? See docutils-develop 2003-02-13.</p>
</li>
<li><p class="first">Allow a "::"-only paragraph (first line, actually) to introduce a
<span class="target" id="literal-block-without-a-blank-line">literal block without a blank line</span>? (Idea from Paul Moore.)</p>
<pre class="literal-block">
::
This is a literal block
</pre>
<p>Is indentation enough to make the separation between a paragraph
which contains just a <tt class="docutils literal">::</tt> and the literal text unambiguous?
(There's one problem with this concession: If one wants a definition
list item which defines the term "::", we'd have to escape it.) It
would only be reasonable to apply it to "::"-only paragraphs though.
I think the blank line is visually necessary if there's text before
the "::":</p>
<pre class="literal-block">
The text in this paragraph needs separation
from the literal block following::
This doesn't look right.
</pre>
</li>
<li><p class="first">Add new syntax for <span class="target" id="nested-inline-markup">nested inline markup</span>? Or extend the parser to
parse nested inline markup somehow? See the <a class="reference external" href="rst/alternatives.html#nested-inline-markup">collected notes</a>.</p>
</li>
<li><p class="first">Drop the backticks from embedded URIs with omitted reference text?
Should the angle brackets be kept in the output or not?</p>
<pre class="literal-block">
<file_name>_
</pre>
<p>Probably not worth the trouble.</p>
</li>
<li><p class="first">How about a syntax for alternative hyperlink behavior, such as "open
in a new window" (as in HTML's <tt class="docutils literal"><a <span class="pre">target="_blank"></span></tt>)?</p>
<p>The MoinMoin wiki uses a caret ("^") at the beginning of the URL
("^" is not a legal URI character). That could work for both inline
and explicit targets:</p>
<pre class="literal-block">
The `reference docs <^url>`__ may be handy.
.. _name: ^url
</pre>
<p>This may be too specific to HTML. It hasn't been requested very
often either.</p>
</li>
<li><p class="first">Add an option to add URI schemes at runtime.</p>
</li>
<li><p class="first"><span class="target" id="segmented-lists">Segmented lists</span>:</p>
<pre class="literal-block">
: segment : segment : segment
: segment : segment : very long
segment
: segment : segment : segment
</pre>
<p>The initial colon (":") can be thought of as a type of bullet</p>
<p>We could even have segment titles:</p>
<pre class="literal-block">
:: title : title : title
: segment : segment : segment
: segment : segment : segment
</pre>
<p>This would correspond well to DocBook's SegmentedList. Output could
be tabular or "name: value" pairs, as described in DocBook's docs.</p>
</li>
<li><p class="first">Allow backslash-escaped colons in field names:</p>
<pre class="literal-block">
:Case Study\: Event Handling: This chapter will be dropped.
</pre>
</li>
<li><p class="first">Enable grid <span class="target" id="tables-inside-xml-comments">tables inside XML comments</span>, where "<tt class="docutils literal"><span class="pre">--</span></tt>" ends comments.</p>
<p>Implementation possibilities:</p>
<ol class="arabic simple">
<li>Make the table syntax characters into "table" directive options.
This is the most flexible but most difficult, and we probably
don't need that much flexibility.</li>
<li>Substitute "~" for "-" with a specialized directive option
(e.g. ":tildes:").</li>
<li>Make the standard table syntax recognize "~" as well as "-", even
without a directive option. Individual tables would have to be
internally consistent.</li>
<li>Allow Unicode box characters for table markup
(<a class="reference external" href="http://sourceforge.net/p/docutils/feature-requests/6">feature request [6]</a>)</li>
</ol>
<p>Directive options are preferable to configuration settings, because
tables are document-specific. A pragma directive would be another
approach, to set the syntax once for a whole document.</p>
<p>Unicode box character markup would kill two birds with one stone.</p>
<p>In the meantime, the <a class="reference external" href="../ref/rst/directives.html#list-table">list-table</a> directive is a good replacement for
grid tables inside XML comments.</p>
</li>
<li><p class="first">Generalize docinfo contents (bibliographic fields): remove specific
fields, and have only a single generic "field"?</p>
</li>
<li><p class="first"><span class="target" id="line-numbers">Line numbers</span> and "source" in system messages:</p>
<ul>
<li><p class="first">Add "source" and "line" keyword arguments to all Reporter calls?
This would require passing source/line arguments along all
intermediate functions (where currently only <cite>line</cite> is used).</p>
<p>Or rather specify "line" only if actually needed?</p>
<p>Currently, <cite>document.reporter</cite> uses a state machine instance to
determine the "source" and "line" info from
<cite>statemachine.input_lines</cite> if not given explicitely. Except for
special cases, the "line" argument is not needed because,
<cite>document.statemachine</cite> keeps record of the current line number.</p>
</li>
<li><p class="first">For system messages generated after the parsing is completed (i.e. by
transforms or the writer) "line" info must be present in the doctree
elements.</p>
<p>Elements' .line assignments should be checked. (Assign to .source
too? Add a set_info method? To what?)</p>
<p>The "source" (and line number in the source) can either be added
explicitely to the elements or determined from the “raw” line
number by <cite>document.statemachine.get_source_and_line</cite>.</p>
</li>
<li><p class="first">Some line numbers in elements are not being set properly
(explicitly), just implicitly/automatically. See rev. 1.74 of
docutils/parsers/rst/states.py for an example of how to set.</p>
</li>
<li><p class="first">The line numbers of definition list items are wrong:</p>
<pre class="literal-block">
$ rst2pseudoxml.py --expose-internal-attribute line
1
2
3
5
6
7
<document source="<stdin>">
<definition_list>
<definition_list_item internal:line="3">
<term>
1
<definition>
<paragraph internal:line="2">
2
3
<definition_list_item internal:line="6">
<term>
5
<definition>
<paragraph internal:line="6">
6
7
</pre>
</li>
</ul>
</li>
<li><p id="none-source">Quite a few nodes are getting a "None" source attribute as well. In
particular, see the bodies of definition lists.</p>
</li>
</ul>
</div>
<div class="section" id="math-markup">
<h2><a class="toc-backref" href="#id28">Math Markup</a></h2>
<p>Since Docutils 0.8, a "math" role and directive using LaTeX math
syntax as input format is part of reStructuredText.</p>
<p>Open issues:</p>
<ul class="simple">
<li>Use a "Transform" for math format conversions as extensively discussed in
the "math directive issues" thread in May 2008
(<a class="reference external" href="http://osdir.com/ml/text.docutils.devel/2008-05/threads.html">http://osdir.com/ml/text.docutils.devel/2008-05/threads.html</a>)?</li>
<li>Generic "math-output" option (currently specific to HTML).
(List of math-output preferences?)</li>
<li>Try to be compatible with <a class="reference external" href="http://sphinx.pocoo.org/ext/math.html">Math support in Sphinx</a>?<ul>
<li>The <tt class="docutils literal">:label:</tt> option selects a label for the equation, by which it
can be cross-referenced, and causes an equation number to be issued.
In Docutils, the option <tt class="docutils literal">:name:</tt> sets the label.
Equation numbering is not implemented yet.</li>
<li>Option <tt class="docutils literal">:nowrap:</tt> prevents wrapping of the given math in a
math environment (you have to specify the math environment in the
content).</li>
</ul>
</li>
</ul>
<ul class="simple">
<li>Equation numbering and references. (Should be handled in a unified way
with other numbered entities like formal tables and images.)</li>
</ul>
<div class="section" id="alternative-input-formats">
<h3><a class="toc-backref" href="#id29">alternative input formats</a></h3>
<p>Use a directive option to specify an alternative input format, e.g. (but not
limited to):</p>
<dl class="docutils">
<dt><a class="reference external" href="http://www.w3.org/TR/MathML2/">MathML</a></dt>
<dd><p class="first">Not for hand-written code but maybe usefull when pasted in (or included
from a file)</p>
<p class="last">For an overview of MathML implementations and tests, see, e.g.,
the <a class="reference external" href="http://www.mathweb.org/wiki/MathML">mathweb wiki</a> or the <a class="reference external" href="http://wiki.contextgarden.net/MathML">ConTeXT MathML page</a>.</p>
</dd>
<dt><a class="reference external" href="http://www1.chapman.edu/~jipsen/mathml/asciimath.html">ASCIIMath</a></dt>
<dd><p class="first">Simple, ASCII based math input language (see also <a class="reference external" href="http://www.wjagray.co.uk/maths/ASCIIMathTutorial.html">ASCIIMath tutorial</a>).</p>
<ul class="last">
<li><p class="first">The Python module <a class="reference external" href="http://pypi.python.org/pypi/asciimathml/">ASCIIMathML</a> translates a string with ASCIIMath into a
MathML tree. Used, e.g., by <a class="reference external" href="http://fletcherpenney.net/multimarkdown/">MultiMarkdown</a>.</p>
<p>A more comprehensive implementation is <a class="reference external" href="http://sourceforge.net/projects/asciimathpython/">ASCIIMathPython</a> by
Paul Trembley (also used in his sandbox projects).</p>
</li>
<li><p class="first">For conversion to LaTeX, there is a JavaScript script at
<a class="reference external" href="http://dlippman.imathas.com/asciimathtex/ASCIIMath2TeX.js">http://dlippman.imathas.com/asciimathtex/ASCIIMath2TeX.js</a></p>
</li>
</ul>
</dd>
<dt><a class="reference external" href="http://www.unicode.org/notes/tn28/">Unicode Nearly Plain Text Encoding of Mathematics</a></dt>
<dd><p class="first">format for lightly marked-up representation of mathematical
expressions in Unicode.</p>
<p class="last">(Unicode Technical Note. Sole responsibility for its contents rests
with the author(s). Publication does not imply any endorsement by
the Unicode Consortium.)</p>
</dd>
<dt>itex</dt>
<dd>See <a class="reference external" href="http://article.gmane.org/gmane.text.docutils.user/118">the culmination of a relevant discussion in 2003</a>.</dd>
</dl>
</div>
<div class="section" id="latex-output">
<h3><a class="toc-backref" href="#id30">LaTeX output</a></h3>
<p>Which equation environments should be supported by the math directive?</p>
<ul>
<li><p class="first">one line:</p>
<ul class="simple">
<li>numbered: <cite>equation</cite></li>
<li>unnumbered: <cite>equation*</cite></li>
</ul>
</li>
<li><p class="first">multiline (test for <tt class="docutils literal">\\</tt> outside of a nested environment
(e.g. <cite>array</cite> or <cite>cases</cite>)</p>
<ul>
<li><p class="first">numbered: <cite>align</cite> (number every line)</p>
<p>(To give one common number to all lines, put them in a <cite>split</cite>
environment. Docutils then places it in an <cite>equation</cite> environment.)</p>
</li>
<li><p class="first">unnumbered: <cite>align*</cite></p>
</li>
<li><p class="first">Sphinx math also supports <cite>gather</cite> (checking for blank lines in
the content). Docutils puts content blocks separated by blank
lines in separate math-block doctree nodes. (The only difference of
<cite>gather</cite> to two consecutive "normal" environments seems to be that
page-breaks between the two are prevented.)</p>
</li>
</ul>
</li>
</ul>
<p>See <a class="reference external" href="http://www.math.uiuc.edu/~hildebr/tex/displays.html">http://www.math.uiuc.edu/~hildebr/tex/displays.html</a>.</p>
</div>
<div class="section" id="html-output">
<h3><a class="toc-backref" href="#id31">HTML output</a></h3>
<p>There is no native math support in HTML.</p>
<dl class="docutils">
<dt><a class="reference external" href="http://www.w3.org/TR/MathML2/">MathML</a></dt>
<dd><p class="first">Converters from LaTeX to MathML include</p>
<ul class="last">
<li><p class="first"><a class="reference external" href="../../../sandbox/jensj/latex_math/">latex_math</a> (Python) by Jens Jørgen Mortensen in the Docutils sandbox</p>
<p>This is the base for Docutils <a class="reference external" href="../../docutils/math/latex2mathml.py">latex2mathml</a> module used by
default with <tt class="docutils literal"><span class="pre">--math-output=MathML</span></tt>.</p>
</li>
<li><p class="first"><a class="reference external" href="http://gva.noekeon.org/blahtexml/">blahtexml</a> (C++), supported with <tt class="docutils literal"><span class="pre">--math-output=MathML</span> blahtexml</tt>.</p>
<p>Fast conversion, support for many symbols and environments, but
no "align" (or other equation-aligning) environment.</p>
</li>
<li><p class="first"><a class="reference external" href="http://dlmf.nist.gov/LaTeXML/">LaTeXML</a> (Perl), supported with <tt class="docutils literal"><span class="pre">--math-output=MathML</span> latexml</tt>.</p>
<p>Comprehensive macro support but very slow</p>
</li>
<li><p class="first"><a class="reference external" href="http://hutchinson.belmont.ma.us/tth/mml/">TtM</a> (C), <tt class="docutils literal"><span class="pre">--math-output=MathML</span> ttm</tt>, support may be removed.</p>
<p>No "matrix", "align" and "cases" environments.</p>
</li>
<li><p class="first"><a class="reference external" href="http://www.mathtoweb.com/">MathToWeb</a> (Java)</p>
</li>
<li><p class="first"><a class="reference external" href="http://www.tug.org/applications/tex4ht/mn.html">TeX4ht</a> (TeX based)</p>
</li>
<li><p class="first"><a class="reference external" href="http://golem.ph.utexas.edu/~distler/blog/itex2MMLcommands.html">itex</a> (also <a class="reference external" href="http://msevior.livejournal.com/26377.html">used in Abiword</a>)</p>
</li>
<li><p class="first"><a class="reference external" href="http://www.gold-saucer.org/mathml/greasemonkey/dist/display-latex">Steve’s LATEX-to-MathML translator</a>
('mini-language', javascript, Python)</p>
</li>
<li><p class="first"><a class="reference external" href="https://github.com/mathjax/MathJax-node">MathJax for Node</a></p>
</li>
<li><p class="first">Write a new converter? E.g. based on:</p>
<ul class="simple">
<li>a generic tokenizer (see e.g. a <a class="reference external" href="http://code.activestate.com/recipes/252124-latex-codec/">latex-codec recipe</a>,
<a class="reference external" href="http://mirror.ctan.org/biblio/bibtex/utils/mab2bib/latex.py">updated latex-codec</a>, )</li>
<li>the Unicode-Char <-> LaTeX mappings database <a class="reference external" href="http://milde.users.sourceforge.net/LUCR/Math/">unimathsymbols</a></li>
</ul>
</li>
</ul>
</dd>
</dl>
<!-- URL seems down:
.. _itex: http://pear.math.pitt.edu/mathzilla/itex2mmlItex.html -->
<dl class="docutils">
<dt>HTML/CSS</dt>
<dd><p class="first">format math in standard HTML enhanced by CSS rules
(<a class="reference external" href="http://www.cs.tut.fi/~jkorpela/math/">Overview</a>, <a class="reference external" href="http://www.zipcon.net/~swhite/docs/math/math.html">Examples and experiments</a>).</p>
<p>The <tt class="docutils literal"><span class="pre">math-output=html</span></tt> option uses the converter from <a class="reference external" href="http://elyxer.nongnu.org/">eLyXer</a>
(included with Docutils).</p>
<p>Alternatives: LaTeX-math to HTML/CSS converters include</p>
<ul class="last simple">
<li><a class="reference external" href="ttp://hutchinson.belmont.ma.us/tth/index.html">TtH</a> (C)</li>
<li><a class="reference external" href="http://para.inria.fr/~maranget/hevea/">Hevea</a> (Objective Caml)</li>
<li><a class="reference external" href="https://github.com/mathjax/MathJax-node">MathJax for Node</a></li>
</ul>
</dd>
<dt>images</dt>
<dd><p class="first">(PNG or SVG) like e.g. Wikipedia. (e.g. with <a class="reference external" href="http://dvisvgm.sourceforge.net/">dvisvgm</a> or the
pure-python MathML->SVG converter <a class="reference external" href="http://www.grigoriev.ru/svgmath/">SVGMath</a>)</p>
<ul class="last simple">
<li><a class="reference external" href="https://github.com/mathjax/MathJax-node">MathJax for Node</a></li>
</ul>
</dd>
</dl>
</div>
<div class="section" id="openoffice-output">
<h3><a class="toc-backref" href="#id32">OpenOffice output</a></h3>
<ul>
<li><p class="first">The <a class="reference external" href="http://www.oasis-open.org/standards#opendocumentv1.1">OpenDocument standard</a> version 1.1 says:</p>
<blockquote>
<p>Mathematical content is represented by MathML 2.0</p>
</blockquote>
<p>However, putting MathML into an ODP file seems tricky as these
(maybe outdated) links suppose:
<a class="reference external" href="http://idippedut.dk/post/2008/01/25/Do-your-math-ODF-and-MathML.aspx">http://idippedut.dk/post/2008/01/25/Do-your-math-ODF-and-MathML.aspx</a>
<a class="reference external" href="http://idippedut.dk/post/2008/03/03/Now-I-get-it-ODF-and-MathML.aspx">http://idippedut.dk/post/2008/03/03/Now-I-get-it-ODF-and-MathML.aspx</a></p>
</li>
<li><p class="first"><a class="reference external" href="http://ooolatex.sourceforge.net/">OOoLaTeX</a>: "a set of macros designed to bring the power of LaTeX
into OpenOffice."</p>
</li>
</ul>
</div>
</div>
<div class="section" id="directives">
<h2><a class="toc-backref" href="#id33">Directives</a></h2>
<p>Directives below are often referred to as "module.directive", the
directive function. The "module." is not part of the directive name
when used in a document.</p>
<ul>
<li><p class="first">Allow for field lists in list tables. See
<<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.devel/3392">http://thread.gmane.org/gmane.text.docutils.devel/3392</a>>.</p>
</li>
<li><p id="unify-tables">Unify table implementations and unify options of table directives
(<a class="reference external" href="http://article.gmane.org/gmane.text.docutils.user/1857">http://article.gmane.org/gmane.text.docutils.user/1857</a>).</p>
</li>
<li><p class="first">Allow directives to be added at run-time?</p>
</li>
<li><p class="first">Use the language module for directive option names?</p>
</li>
<li><p class="first">Add "substitution_only" and "substitution_ok" function attributes,
and automate context checking?</p>
</li>
<li><p class="first">Implement options or features on existing directives:</p>
<ul>
<li><p class="first">All directives that produce titled elements should grow implicit
reference names based on the titles.</p>
</li>
<li><p class="first">Allow the <span class="target" id="trim">:trim:</span> option for all directives when they occur in a
substitution definition, not only the <a class="reference external" href="../ref/rst/directives.html#unicode-character-codes">unicode</a> directive.</p>
</li>
<li><p class="first">Add the "class" option to the <a class="reference external" href="../ref/rst/directives.html#unicode-character-codes">unicode</a> directive. For example, you
might want to get characters or strings with borders around them.</p>
</li>
<li><p class="first"><span class="target" id="images-figure">images.figure</span>: "title" and "number", to indicate a formal
figure?</p>
</li>
<li><p class="first"><span class="target" id="parts-sectnum">parts.sectnum</span>: "local"?, "refnum"</p>
<p>A "local" option could enable numbering for sections from a
certain point down, and sections in the rest of the document are
not numbered. For example, a reference section of a manual might
be numbered, but not the rest. OTOH, an all-or-nothing approach
would probably be enough.</p>
<p>The "sectnum" directive should be usable multiple times in a
single document. For example, in a long document with "chapter"
and "appendix" sections, there could be a second "sectnum" before
the first appendix, changing the sequence used (from 1,2,3... to
A,B,C...). This is where the "local" concept comes in. This part
of the implementation can be left for later.</p>
<p>A "refnum" option (better name?) would insert reference names
(targets) consisting of the reference number. Then a URL could be
of the form <tt class="docutils literal"><span class="pre">http://host/document.html#2.5</span></tt> (or "2-5"?). Allow
internal references by number? Allow name-based <em>and</em>
number-based ids at the same time, or only one or the other (which
would the table of contents use)? Usage issue: altering the
section structure of a document could render hyperlinks invalid.</p>
</li>
<li><p class="first"><span class="target" id="parts-contents">parts.contents</span>: Add a "suppress" or "prune" option? It would
suppress contents display for sections in a branch from that point
down. Or a new directive, like "prune-contents"?</p>
<p>Add an option to include topics in the TOC? Another for sidebars?
The "topic" directive could have a "contents" option, or the
"contents" directive" could have an "include-topics" option. See
docutils-develop 2003-01-29.</p>
</li>
<li><p class="first"><span class="target" id="parts-header">parts.header</span> & <span class="target" id="parts-footer">parts.footer</span>: Support multiple, named headers
& footers? For example, separate headers & footers for odd, even,
and the first page of a document.</p>
<p>This may be too specific to output formats which have a notion of
"pages".</p>
</li>
<li><p class="first"><span class="target" id="misc-class">misc.class</span>:</p>
<ul class="simple">
<li>Add a <tt class="docutils literal">:parent:</tt> option for setting the parent's class
(<a class="reference external" href="http://article.gmane.org/gmane.text.docutils.devel/3165">http://article.gmane.org/gmane.text.docutils.devel/3165</a>).</li>
</ul>
</li>
<li><p class="first"><span class="target" id="misc-include">misc.include</span>:</p>
<ul>
<li><p class="first">Option to label lines?</p>
</li>
<li><p class="first">How about an environment variable, say RSTINCLUDEPATH or
RSTPATH, for standard includes (as in <tt class="docutils literal">.. include:: <name></tt>)?
This could be combined with a setting/option to allow
user-defined include directories.</p>
</li>
<li><p class="first">Add support for inclusion by URL?</p>
<pre class="literal-block">
.. include::
:url: http://www.example.org/inclusion.txt
</pre>
</li>
<li><p class="first">Strip blank lines from begin and end of a literal included file or
file section. This would correspond to the way a literal block is
handled.</p>
<p>As nodes.literal_block expects (and we have) the text as a string
(rather than a list of lines), using a regexp seems the way.</p>
</li>
</ul>
</li>
<li><p class="first"><span class="target" id="misc-raw">misc.raw</span>: add a "destination" option to the "raw" directive?</p>
<pre class="literal-block">
.. raw:: html
:destination: head
<link ...>
</pre>
<p>It needs thought & discussion though, to come up with a consistent
set of destination labels and consistent behavior.</p>
<p>And placing HTML code inside the <head> element of an HTML
document is rather the job of a templating system.</p>
</li>
<li><p class="first"><span class="target" id="body-sidebar">body.sidebar</span>: Allow internal section structure? Adornment
styles would be independent of the main document.</p>
<p>That is really complicated, however, and the document model
greatly benefits from its simplicity.</p>
</li>
</ul>
</li>
<li><p class="first">Implement directives. Each of the list items below begins with an
identifier of the form, "module_name.directive_function_name". The
directive name itself could be the same as the
directive_function_name, or it could differ.</p>
<ul>
<li><p class="first"><span class="target" id="html-imagemap">html.imagemap</span></p>
<p>It has the disadvantage that it's only easily implementable for
HTML, so it's specific to one output format.</p>
<p>(For non-HTML writers, the imagemap would have to be replaced with
the image only.)</p>
</li>
<li><p class="first"><span class="target" id="parts-endnotes">parts.endnotes</span> (or "footnotes"): See <a class="reference internal" href="#footnote-citation-gathering">Footnote & Citation Gathering</a>.</p>
</li>
<li><p class="first"><span class="target" id="parts-citations">parts.citations</span>: See <a class="reference internal" href="#footnote-citation-gathering">Footnote & Citation Gathering</a>.</p>
</li>
<li><p class="first"><span class="target" id="misc-language">misc.language</span>: Specify (= change) the language of a document at
parse time?</p>
<ul class="simple">
<li>The <a class="reference internal" href="#misc-settings">misc.settings</a> directive suggested below offers a more generic
approach.</li>
<li>The language of document parts can be indicated by the "special class
value" <tt class="docutils literal"><span class="pre">"language-"</span></tt> + <a class="reference external" href="http://www.rfc-editor.org/rfc/bcp/bcp47.txt">BCP 47</a> language code. Class arguments to
the title are attached to the document's base node - hence titled
documents can be given a different language at parse time. However,
"language by class attribute" does not change parsing (localized
directives etc.), only supporting writers.</li>
</ul>
</li>
<li><p class="first"><span class="target" id="misc-settings">misc.settings</span>: Set any(?) Docutils runtime setting from within
a document? Needs much thought and discussion.</p>
<p>Security concerns need to be taken into account (it shouldn't be
possible to enable <tt class="docutils literal">file_insertion_enabled</tt> from within a
document), and settings that only would have taken effect before
the directive (like <tt class="docutils literal"><span class="pre">tab-width</span></tt>) shouldn't be accessible either.</p>
<p>See this sub-thread:
<<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/3620/focus=3649">http://thread.gmane.org/gmane.text.docutils.user/3620/focus=3649</a>></p>
</li>
<li><p class="first"><span class="target" id="misc-gather">misc.gather</span>: Gather (move, or copy) all instances of a specific
element. A generalization of the <a class="reference internal" href="#footnote-citation-gathering">Footnote & Citation Gathering</a>
ideas.</p>
</li>
<li><p class="first">Add a custom "directive" directive, equivalent to "role"? For
example:</p>
<pre class="literal-block">
.. directive:: incr
.. class:: incremental
.. incr::
"``.. incr::``" above is equivalent to "``.. class:: incremental``".
</pre>
<p>Another example:</p>
<pre class="literal-block">
.. directive:: printed-links
.. topic:: Links
:class: print-block
.. target-notes::
:class: print-inline
</pre>
<p>This acts like macros. The directive contents will have to be
evaluated when referenced, not when defined.</p>
<ul class="simple">
<li>Needs a better name? "Macro", "substitution"?</li>
<li>What to do with directive arguments & options when the
macro/directive is referenced?</li>
</ul>
</li>
<li><p class="first">Make the meaning of block quotes overridable? Only a 1-shot
though; doesn't solve the general problem.</p>
</li>
<li><p class="first"><span class="target" id="conditional-directives">conditional directives</span>:</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">See also the implementation in <a class="reference external" href="http://sphinx.pocoo.org/">Sphinx</a>.</p>
</div>
<p>Docutils already has the ability to say "use this content for
Writer X" via the "raw" directive. It also does have the ability
to say "use this content for any Writer other than X" via the
"strip-elements with class" config value. However, using "raw"
input just to select a special writer is inconvenient in many
cases.
It wouldn't be difficult to get more straightforward support, though.</p>
<p>My first idea would be to add a set of conditional directives.
Let's call them "writer-is" and "writer-is-not" for discussion
purposes (don't worry about implemention details). We might
have:</p>
<pre class="literal-block">
.. writer-is:: text-only
::
+----------+
| SNMP |
+----------+
| UDP |
+----------+
| IP |
+----------+
| Ethernet |
+----------+
.. writer-is:: pdf
.. figure:: protocol_stack.eps
.. writer-is-not:: text-only pdf
.. figure:: protocol_stack.png
</pre>
<p>This could be an interface to the Filter transform
(docutils.transforms.components.Filter).</p>
<p>The ideas in <a class="reference internal" href="#adaptable-file-extensions">adaptable file extensions</a> above may also be
applicable here.</p>
<p>SVG's "switch" statement may provide inspiration.</p>
<p>Here's an example of a directive that could produce multiple
outputs (<em>both</em> raw troff pass-through <em>and</em> a GIF, for example)
and allow the Writer to select.</p>
<pre class="literal-block">
.. eqn::
.EQ
delim %%
.EN
%sum from i=o to inf c sup i~=~lim from {m -> inf}
sum from i=0 to m sup i%
.EQ
delim off
.EN
</pre>
</li>
<li><p class="first"><span class="target" id="body-example">body.example</span>: Examples; suggested by Simon Hefti. Semantics as
per Docbook's "example"; admonition-style, numbered, reference,
with a caption/title.</p>
</li>
<li><p class="first"><span class="target" id="body-index">body.index</span>: Index targets.</p>
<p>See <a class="reference external" href="./rst/alternatives.html#index-entries-indexes">Index Entries & Indexes</a>.</p>
</li>
<li><p class="first"><span class="target" id="body-literal">body.literal</span>: Literal block, possibly "formal" (see <a class="reference internal" href="#object-numbering-and-object-references">object
numbering and object references</a> above). Possible options:</p>
<ul>
<li><p class="first">"highlight" a range of lines</p>
</li>
<li><p class="first">include only a specified range of lines</p>
</li>
<li><p class="first">"number" or "line-numbers"? (since 0.9 available with "code" directive)</p>
</li>
<li><p class="first">"styled" could indicate that the directive should check for
style comments at the end of lines to indicate styling or
markup.</p>
<p>Specific derivatives (i.e., a "python-interactive" directive)
could interpret style based on cues, like the ">>> " prompt and
"input()"/"raw_input()" calls.</p>
</li>
</ul>
<p>See docutils-users 2003-03-03.</p>
</li>
<li><p class="first"><span class="target" id="body-listing">body.listing</span>: Code listing with title (to be numbered
eventually), equivalent of "figure" and "table" directives.</p>
</li>
<li><p class="first"><span class="target" id="pysource-usage">pysource.usage</span>: Extract a usage message from the program,
either by running it at the command line with a <tt class="docutils literal"><span class="pre">--help</span></tt> option
or through an exposed API. [Suggestion for Optik.]</p>
</li>
<li><p class="first"><span class="target" id="body-float">body.float</span>: Generic float that can be used for figures, tables,
code listings, flowcharts, ...</p>
<p>There is a Sphinx extension by Ignacio Fernández Galván <<a class="reference external" href="mailto:jellby@gmail.com">jellby@gmail.com</a>></p>
<blockquote>
<blockquote>
<p>I implemented something for generic floats in sphinx, and submitted a
pull request that is still waiting:</p>
<pre class="literal-block">
.. float::
:type: figure
:caption: My caption
</pre>
</blockquote>
<p><a class="reference external" href="https://github.com/sphinx-doc/sphinx/pull/1858">https://github.com/sphinx-doc/sphinx/pull/1858</a></p>
</blockquote>
</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="interpreted-text">
<h2><a class="toc-backref" href="#id34">Interpreted Text</a></h2>
<p>Interpreted text is entirely a reStructuredText markup construct, a
way to get around built-in limitations of the medium. Some roles are
intended to introduce new doctree elements, such as "title-reference".
Others are merely convenience features, like "RFC".</p>
<p>All supported interpreted text roles must already be known to the
Parser when they are encountered in a document. Whether pre-defined
in core/client code, or in the document, doesn't matter; the roles
just need to have already been declared. Adding a new role may
involve adding a new element to the DTD and may require extensive
support, therefore such additions should be well thought-out. There
should be a limited number of roles.</p>
<p>The only place where no limit is placed on variation is at the start,
at the Reader/Parser interface. Transforms are inserted by the Reader
into the Transformer's queue, where non-standard elements are
converted. Once past the Transformer, no variation from the standard
Docutils doctree is possible.</p>
<p>An example is the Python Source Reader, which will use interpreted
text extensively. The default role will be "Python identifier", which
will be further interpreted by namespace context into <class>,
<method>, <module>, <attribute>, etc. elements (see pysource.dtd),
which will be transformed into standard hyperlink references, which
will be processed by the various Writers. No Writer will need to have
any knowledge of the Python-Reader origin of these elements.</p>
<ul>
<li><p class="first">Add explicit interpreted text roles for the rest of the implicit
inline markup constructs: named-reference, anonymous-reference,
footnote-reference, citation-reference, substitution-reference,
target, uri-reference (& synonyms).</p>
</li>
<li><p class="first">Add directives for each role as well? This would allow indirect
nested markup:</p>
<pre class="literal-block">
This text contains |nested inline markup|.
.. |nested inline markup| emphasis::
nested ``inline`` markup
</pre>
</li>
<li><p class="first">Implement roles:</p>
<ul>
<li><p class="first">"<span class="target" id="raw-wrapped">raw-wrapped</span>" (or "<span class="target" id="raw-wrap">raw-wrap</span>"): Base role to wrap raw text
around role contents.</p>
<p>For example, the following reStructuredText source ...</p>
<pre class="literal-block">
.. role:: red(raw-formatting)
:prefix:
:html: <font color="red">
:latex: {\color{red}
:suffix:
:html: </font>
:latex: }
colored :red:`text`
</pre>
<p>... will yield the following document fragment:</p>
<pre class="literal-block">
<paragraph>
colored
<inline classes="red">
<raw format="html">
<font color="red">
<raw format="latex">
{\color{red}
<inline classes="red">
text
<raw format="html">
</font>
<raw format="latex">
}
</pre>
<p>Possibly without the intermediate "inline" node.</p>
</li>
<li><p class="first"><span class="target" id="acronym-and-abbreviation">"acronym" and "abbreviation"</span>: Associate the full text with a
short form. Jason Diamond's description:</p>
<blockquote>
<p>I want to translate <tt class="docutils literal"><span class="pre">`reST`:acronym:</span></tt> into <tt class="docutils literal"><acronym
<span class="pre">title='reStructuredText'>reST</acronym></span></tt>. The value of the
title attribute has to be defined out-of-band since you can't
parameterize interpreted text. Right now I have them in a
separate file but I'm experimenting with creating a directive
that will use some form of reST syntax to let you define them.</p>
</blockquote>
<p>Should Docutils complain about undefined acronyms or
abbreviations?</p>
<p>What to do if there are multiple definitions? How to
differentiate between CSS (Content Scrambling System) and CSS
(Cascading Style Sheets) in a single document? David Priest
responds,</p>
<blockquote>
<p>The short answer is: you don't. Anyone who did such a thing
would be writing very poor documentation indeed. (Though I
note that <a class="reference external" href="rst/alternatives.html#parameterized-interpreted-text">somewhere else in the docs</a>, there's mention of
allowing replacement text to be associated with the
abbreviation. That takes care of the duplicate
acronyms/abbreviations problem, though a writer would be
foolish to ever need it.)</p>
</blockquote>
<p>How to define the full text? Possibilities:</p>
<ol class="arabic">
<li><p class="first">With a directive and a definition list?</p>
<pre class="literal-block">
.. acronyms::
reST
reStructuredText
DPS
Docstring Processing System
</pre>
<p>Would this list remain in the document as a glossary, or would
it simply build an internal lookup table? A "glossary"
directive could be used to make the intention clear.
Acronyms/abbreviations and glossaries could work together.</p>
<p>Then again, a glossary could be formed by gathering individual
definitions from around the document.</p>
</li>
<li><p class="first">Some kind of <a class="reference external" href="rst/alternatives.html#parameterized-interpreted-text">inline parameter syntax</a>?</p>
<pre class="literal-block">
`reST <reStructuredText>`:acronym: is `WYSIWYG <what you
see is what you get>`:acronym: plaintext markup.
</pre>
</li>
<li><p class="first">A combination of 1 & 2?</p>
<p>The multiple definitions issue could be handled by establishing
rules of priority. For example, directive-based lookup tables
have highest priority, followed by the first inline definition.
Multiple definitions in directive-based lookup tables would
trigger warnings, similar to the rules of <a class="reference external" href="../ref/rst/restructuredtext.html#implicit-hyperlink-targets">implicit hyperlink
targets</a>.</p>
</li>
<li><p class="first">Using substitutions?</p>
<pre class="literal-block">
.. |reST| acronym:: reST
:text: reStructuredText
</pre>
</li>
</ol>
<p>What do we do for other formats than HTML which do not support
tool tips? Put the full text in parentheses?</p>
</li>
<li><p class="first">"figure", "table", "listing", "chapter", "page", etc: See <a class="reference internal" href="#object-numbering-and-object-references">object
numbering and object references</a> above.</p>
</li>
<li><p class="first">"glossary-term": This would establish a link to a glossary. It
would require an associated "glossary-entry" directive, whose
contents could be a definition list:</p>
<pre class="literal-block">
.. glossary-entry::
term1
definition1
term2
definition2
</pre>
<p>This would allow entries to be defined anywhere in the document,
and collected (via a "glossary" directive perhaps) at one point.</p>
</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="doctree-pruning">
<h2><a class="toc-backref" href="#id35">Doctree pruning</a></h2>
<p>The number of doctree nodes can be reduced by "normalizing" some related
nodes. This makes the document model and the writers somewhat simpler.</p>
<ul>
<li><p class="first">The "doctest" element should go away. The construct could simply be
a front-end to generic literal blocks. We could immediately (in 0.7)
remove the doctest node from the doctree, but leave the
syntax in reST. The reST parser could represent doctest blocks as
literal blocks with a class attribute. The syntax could be left in
reST (for a set period of time?).</p>
</li>
<li><p class="first">"Normalize" special admonitions (note, hint, warning, ...) during parsing
(similar to <span class="target" id="transforms-writer-aux-admonitions">transforms.writer_aux.Admonitions</span>). There is no need to
keep them as distinct elements in the doctree specification.</p>
<p>Keep the special admonition directives in reStructuredText syntax?</p>
</li>
</ul>
</div>
</div>
<div class="section" id="unimplemented-transforms">
<h1><a class="toc-backref" href="#id36">Unimplemented Transforms</a></h1>
<ul>
<li><p class="first"><span class="target" id="footnote-citation-gathering">Footnote & Citation Gathering</span></p>
<p>Collect and move footnotes & citations to the end of a document or the
place of a "footnotes" or "citations" directive
(see <cite><./ref/rst/directives.html>_</cite>)</p>
<dl class="docutils">
<dt>Footnotes:</dt>
<dd><p class="first">Collect all footnotes that are referenced in the document before the
directive (and after an eventually preceding <tt class="docutils literal">.. footnotes::</tt>
directive) and insert at this place.</p>
<p class="last">Allows "endnotes" at a configurable place.</p>
</dd>
<dt>Citations:</dt>
<dd><p class="first">Collect citations that are referenced ...</p>
<p>Citations can be:</p>
<ol class="loweralpha simple">
<li>defined in the document as citation elements</li>
<li>auto-generated from entries in a bibliographic database.<ul>
<li>based on <a class="reference external" href="http://code.google.com/p/bibstuff/">bibstuff</a>?</li>
<li>also have a look at<ul>
<li><a class="reference external" href="http://www.cs.cornell.edu/people/egs/crosstex/">CrossTeX</a>, a backwards-compatible, improved bibtex
re-implementation in Python (including HTML export).
(development stalled since 2 years)</li>
<li><a class="reference external" href="http://pybtex.sourceforge.net/">Pybtex</a>,a drop-in replacement for BibTeX written in Python.<ul>
<li>BibTeX styles & (experimental) pythonic style API.</li>
<li>Database in BibTeX, BibTeXML and YAML formats.</li>
<li>full Unicode support.</li>
<li>Write to TeX, HTML and plain text.</li>
</ul>
</li>
<li><a class="reference external" href="http://e6h.org/%7Eegh/hg/zotero-plain/">Zotero plain</a>
supports Zotero databases and <a class="reference external" href="http://www.citationstyles.org/">CSL</a> styles with Docutils with an
<tt class="docutils literal">xcite</tt> role.</li>
<li><a class="reference external" href="http://sphinxcontrib-bibtex.readthedocs.org/">sphinxcontrib-bibtex</a> Sphinx extension with "bibliography"
directive and "cite" role supporting BibTeX databases.</li>
<li><a class="reference external" href="http://www.loria.fr/~rougier/coding/article/rst2html.py">Modified rst2html</a> by
Nicolas Rougier.</li>
</ul>
</li>
</ul>
</li>
</ol>
<ul class="last simple">
<li>Automatically insert a "References" heading?</li>
</ul>
</dd>
</dl>
</li>
</ul>
<ul>
<li><p class="first"><span class="target" id="reference-merging">Reference Merging</span></p>
<p>When merging two or more subdocuments (such as docstrings),
conflicting references may need to be resolved. There may be:</p>
<ul class="simple">
<li>duplicate reference and/or substitution names that need to be made
unique; and/or</li>
<li>duplicate footnote numbers that need to be renumbered.</li>
</ul>
<p>Should this be done before or after reference-resolving transforms
are applied? What about references from within one subdocument to
inside another?</p>
</li>
<li><p class="first"><span class="target" id="document-splitting">Document Splitting</span></p>
<p>If the processed document is written to multiple files (possibly in
a directory tree), it will need to be split up. Internal references
will have to be adjusted.</p>
<p>(HTML only? Initially, yes. Eventually, anything should be
splittable.)</p>
<p>Ideas:</p>
<ul>
<li><p class="first">Insert a "destination" attribute into the root element of each
split-out document, containing the path/filename. The Output
object or Writer will recognize this attribute and split out the
files accordingly. Must allow for common headers & footers,
prev/next, breadcrumbs, etc.</p>
</li>
<li><p class="first">Transform a single-root document into a document containing
multiple subdocuments, recursively. The content model of the
"document" element would have to change to:</p>
<pre class="literal-block">
<!ELEMENT document
( (title, subtitle?)?,
decoration?,
(docinfo, transition?)?,
%structure.model;,
document* )>
</pre>
<p>(I.e., add the last line -- 0 or more document elements.)</p>
<p>Let's look at the case of hierarchical (directories and files)
HTML output. Each document element containing further document
elements would correspond to a directory (with an index.html file
for the content preceding the subdocuments). Each document
element containing no subdocuments (i.e., structure model elements
only) corresponds to a concrete file with no directory.</p>
<p>The natural transform would be to map sections to subdocuments,
but possibly only a given number of levels deep.</p>
</li>
</ul>
</li>
<li><p class="first"><span class="target" id="navigation">Navigation</span></p>
<p>If a document is split up, each segment will need navigation links:
parent, children (small TOC), previous (preorder), next (preorder).
Part of <a class="reference internal" href="#document-splitting">Document Splitting</a>?</p>
</li>
<li><p class="first"><span class="target" id="list-of-system-messages">List of System Messages</span></p>
<p>The <tt class="docutils literal">system_message</tt> elements are inserted into the document tree,
adjacent to the problems themselves where possible. Some (those
generated post-parse) are kept until later, in
<tt class="docutils literal">document.messages</tt>, and added as a special final section,
"Docutils System Messages".</p>
<p>Docutils could be made to generate hyperlinks to all known
system_messages and add them to the document, perhaps to the end of
the "Docutils System Messages" section.</p>
<p>Fred L. Drake, Jr. wrote:</p>
<blockquote>
<p>I'd like to propose that both parse- and transformation-time
messages are included in the "Docutils System Messages" section.
If there are no objections, I can make the change.</p>
</blockquote>
<p>The advantage of the current way of doing things is that parse-time
system messages don't require a transform; they're already in the
document. This is valuable for testing (unit tests,
tools/quicktest.py). So if we do decide to make a change, I think
the insertion of parse-time system messages ought to remain as-is
and the Messages transform ought to move all parse-time system
messages (remove from their originally inserted positions, insert in
System Messages section).</p>
</li>
<li><p class="first"><span class="target" id="index-generation">Index Generation</span></p>
</li>
</ul>
</div>
<div class="section" id="html-writer">
<h1><a class="toc-backref" href="#id37">HTML Writer</a></h1>
<ul>
<li><p class="first">Make it easier to find out fragment names (#foo-bar) of <tt class="docutils literal">_`inline
targets`</tt>. Currently you have to either look at the source or
guess the fragment.</p>
<p>For example, we could add support for self-referencing targets
(i.e. inline targets would [unobtrusively] link to themselves, so
that you can just click them and then copy the address). Or we
could add support for titles that display the fragment name (as in
<<a class="reference external" href="http://subversion.tigris.org/mailing-list-guidelines.html">http://subversion.tigris.org/mailing-list-guidelines.html</a>>; just
hover the paragraphs).</p>
<p>Either way it should be optional and deactivated by default.</p>
<p>This would be useful for documents like Docutils' bug list or to-do
list.</p>
</li>
<li><p class="first">Make the <span class="target" id="list-compacting">list compacting</span> logic more generic: For example, allow
for literal blocks or line blocks inside of compact list items.</p>
<p>This is not implementable as long as list compacting is done by
omitting <tt class="docutils literal"><p></tt> tags. List compacting would need to be done by
adjusting CSS margins instead.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">2015-04-02:</th><td class="field-body"><p class="first">The new html writer no longer strips <p> tags but adds the
class value <tt class="docutils literal">simple</tt> to the list.
Formatting is done by CSS --- configurable by a custom style
sheet.</p>
<p class="last">Auto-compactization can be overridden by the <tt class="docutils literal">open</tt> vs.
<tt class="docutils literal">compact</tt> class arguments.</p>
</td>
</tr>
</tbody>
</table>
</li>
<li><p class="first">Idea for field-list rendering: hanging indent:</p>
<pre class="literal-block">
Field name (bold): First paragraph of field body begins
with the field name inline.
If the first item of a field body is not a paragraph,
it would begin on the following line.
</pre>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">2015-04-02:</th><td class="field-body">The new html writer writes field-lists as definition lists
with class <tt class="docutils literal"><span class="pre">field-list</span></tt>.
Formatting is done by CSS --- configurable by a custom style
sheet. The default style sheet has some examples, including a
run-in field-list style.</td>
</tr>
</tbody>
</table>
</li>
<li><p class="first">Add more support for <link> elements, especially for navigation
bars.</p>
<p>The framework does not have a notion of document relationships, so
probably <a class="reference internal" href="#misc-raw">raw.destination</a> should be used.</p>
<p>We'll have framework support for document relationships when support
for <a class="reference internal" href="#multiple-output-files">multiple output files</a> is added. The HTML writer could
automatically generate <link> elements then.</p>
</li>
<li><p class="first">Base list compaction on the spacing of source list? Would require
parser support. (Idea: fantasai, 16 Dec 2002, doc-sig.)</p>
</li>
<li><p class="first">Add a tool tip ("title" attribute?) to footnote back-links
identifying them as such. Text in Docutils language module.</p>
</li>
</ul>
</div>
<div class="section" id="pep-html-writer">
<h1><a class="toc-backref" href="#id38">PEP/HTML Writer</a></h1>
<ul>
<li><p class="first">Remove the generic style information (duplicated from html4css1.css)
from pep.css to avoid redundancy.</p>
<p>Set <tt class="docutils literal"><span class="pre">stylesheet-path</span></tt> to "html4css.css,pep.css" and the
<tt class="docutils literal"><span class="pre">stylesheet-dirs</span></tt> accordingly instead. (See the xhtml11 writer for an
example.)</p>
</li>
</ul>
</div>
<div class="section" id="s5-html-writer">
<h1><a class="toc-backref" href="#id39">S5/HTML Writer</a></h1>
<ul>
<li><p class="first">Add a way to begin an untitled slide.</p>
</li>
<li><p class="first">Add a way to begin a new slide, continuation, using the same title
as the previous slide? (Unnecessary?) You need that if you have a
lot of items in one section which don't fit on one slide.</p>
<p>Maybe either this item or the previous one can be realized using
transitions.</p>
</li>
<li><p class="first">Have a timeout on incremental items, so the colour goes away after 1
second.</p>
</li>
<li><p class="first">Add an empty, black last slide (optionally). Currently the handling
of the last slide is not very nice, it re-cycles through the
incremental items on the last slide if you hit space-bar after the
last item.</p>
</li>
<li><p class="first">Add a command-line option to disable advance-on-click.</p>
</li>
<li><p class="first">Add a speaker's master document, which would contain a small version
of the slide text with speaker's notes interspersed. The master
document could use <tt class="docutils literal"><span class="pre">target="whatever"</span></tt> to direct links to a
separate window on a second monitor (e.g., a projector).</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This item and the following items are partially
accomplished by the S5 1.2 code (currently in alpha), which has
not yet been integrated into Docutils.</p>
</div>
</li>
<li><p class="first">Speaker's notes -- how to intersperse? Could use reST comments
(".."), but make them visible in the speaker's master document. If
structure is necessary, we could use a "comment" directive (to avoid
nonsensical DTD changes, the "comment" directive could produce an
untitled topic element).</p>
<p>The speaker's notes could (should?) be separate from S5's handout
content.</p>
</li>
<li><p class="first">The speaker's master document could use frames for easy navigation:
TOC on the left, content on the right.</p>
<ul class="simple">
<li>It would be nice if clicking in the TOC frame simultaneously
linked to both the speaker's notes frame and to the slide window,
synchronizing both. Needs JavaScript?</li>
<li>TOC would have to be tightly formatted -- minimal indentation.</li>
<li>TOC auto-generated, as in the PEP Reader. (What if there already
is a "contents" directive in the document?)</li>
<li>There could be another frame on the left (top-left or bottom-left)
containing a single "Next" link, always pointing to the next slide
(synchronized, of course). Also "Previous" link? FF/Rew go to
the beginning of the next/current parent section? First/Last
also? Tape-player-style buttons like <tt class="docutils literal">|<< << < > >> >>|</tt>?</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="epub-html-writer">
<h1><a class="toc-backref" href="#id40">Epub/HTML Writer</a></h1>
<p>Add epub as an output format.</p>
<blockquote>
epub is an open file format for ebooks based on HTML, specified by the
<a class="reference external" href="http://www.idpf.org/">International Digital Publishing Forum</a>. Thus, documents in epub
format are suited to be read with <a class="reference external" href="http://en.wikipedia.org/wiki/List_of_e-book_readers">electronic reading devices</a>.</blockquote>
<p>Pack the output of a HTML writer and supporting files (e.g. images)
into one single epub document.</p>
<p>There are <a class="reference external" href="../user/links.html#ePub">links to two 3rd party ePub writers</a> in the Docutils link list.
Test and consider moving the better one into the docutils core.</p>
</div>
<div class="section" id="latex-writer">
<h1><a class="toc-backref" href="#id41">LaTeX writer</a></h1>
<p>Also see the <a class="reference external" href="../user/latex.html#problems">Problems</a> section in the <a class="reference external" href="../user/latex.html">latex writer documentation</a>.</p>
<div class="section" id="bug-fixes">
<h2><a class="toc-backref" href="#id42">Bug fixes</a></h2>
<ul>
<li><p class="first">Too deeply nested lists fail: generate a warning and provide
a workaround.</p>
</li>
<li><p class="first">Spaces in inline literal text:</p>
<pre class="literal-block">
Now note the
spacing between the words of this sentence (words
should be grouped in pairs).
</pre>
<p>Discuss the desired behaviour and implement a consistent one.</p>
</li>
<li><p class="first">File names of included graphics (see also <cite>grffile</cite> package).</p>
</li>
</ul>
</div>
<div class="section" id="generate-clean-and-configurable-latex-source">
<h2><a class="toc-backref" href="#id43">Generate clean and configurable LaTeX source</a></h2>
<ul class="simple">
<li>Check the generated source with package <cite>nag</cite>.</li>
</ul>
<div class="section" id="configurable-placement-of-figure-and-table-floats">
<h3><a class="toc-backref" href="#id44">Configurable placement of figure and table floats</a></h3>
<ul>
<li><p class="first">Special class argument to individually place figures?</p>
<p>Either:</p>
<blockquote>
<p>placement-<optional arg> -> figure[<optional arg>]{...}</p>
</blockquote>
<p>e.g. <tt class="docutils literal">.. class:: <span class="pre">placement-htb</span></tt>,</p>
<p>or more verbose:</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">H:</th><td class="field-body">place-here</td>
</tr>
<tr class="field"><th class="field-name">h:</th><td class="field-body">place-here-if-possible</td>
</tr>
<tr class="field"><th class="field-name">t:</th><td class="field-body">place-top</td>
</tr>
<tr class="field"><th class="field-name">b:</th><td class="field-body">place-bottom</td>
</tr>
<tr class="field"><th class="field-name">p:</th><td class="field-body">place-on-extra-page</td>
</tr>
</tbody>
</table>
<p>e.g.: <tt class="docutils literal">.. class:: <span class="pre">place-here-if-possible</span> <span class="pre">place-top</span> <span class="pre">place-bottom</span></tt></p>
<p>Maybe support both variants?</p>
</li>
</ul>
</div>
<div class="section" id="latex-constructs-and-packages-instead-of-re-implementations">
<h3><a class="toc-backref" href="#id45">LaTeX constructs and packages instead of re-implementations</a></h3>
<p>Which packages do we want to use?</p>
<blockquote>
<ul>
<li><p class="first">base and "recommended" packages</p>
<p>(packages that should be in a "reasonably sized and reasonably modern
LaTeX installation like the <cite>texlive-latex-recommended</cite> Debian package,
say):</p>
</li>
<li><p class="first">No "fancy" or "exotic" requirements.</p>
</li>
<li><p class="first">pointers to advanced packages and their use in the <a class="reference external" href="../user/latex.html">latex writer
documentation</a>.</p>
</li>
</ul>
</blockquote>
<ul>
<li><p class="first"><tt class="docutils literal">alltt</tt> environment for literal block.</p>
</li>
<li><p class="first">footnotes</p>
<ul class="simple">
<li>True footnotes with LaTeX auto-numbering (as option <tt class="docutils literal"><span class="pre">--latex-footnotes</span></tt>)
(also for target-footnotes):<ul>
<li>attach footnote text to footnote-symobol node</li>
<li>write footnote{<footnote text>}</li>
<li>consider cases where LaTeX does not support footnotes
(inside tables, headings, ...)?</li>
<li>consider multiple footnote refs to common footnote text.</li>
</ul>
<!-- Quote:
If the symbol you want is not one of the ones listed, you'll need to
redefine ``\@fnsymbol`` and add it, e.g. perhaps like::
\def\@fnsymbol#1{\ifcase#1\hbox{}\or *\or \dagger\or \ddagger\or
\mathchar "278\or \mathchar "27B\or \|\or **\or \dagger\dagger \or
\ddagger\ddagger \or \mathchar"27C \else\@ctrerr\fi\relax}
which would allow \symbolfootnote[10]{footnote} to have a club as its
mark. -->
</li>
<li>document customization (links to how-to and packages):</li>
</ul>
<!-- Footnote packages:
:footnote: texlive-latex-recommended % savenotes environment
:footmisc: texlive-latex-extra % formatting options
:manyfoot: texlive-latex-extra
:bigfoot: texlive-latex-extra
:perpage: texlive-latex-extra
:ftnxtra: new on CTAN
fixes the issue of footnote inside \caption{},
tabular environment and \section{} like commands.
German tutorial:
http://www2.informatik.hu-berlin.de/~ahamann/studies/footnotes.pdf -->
<!-- Footnote FAQs:
`Footnotes whose texts are identical
<http://www.tex.ac.uk/cgi-bin/texfaq2html?label=repfootnote>`__
* label per hand or use footmisc
`More than one sequence of footnotes
<http://www.tex.ac.uk/cgi-bin/texfaq2html?label=multfoot>`__
* manyfoot, bigfoot
`Footnotes in tables
<http://www.tex.ac.uk/cgi-bin/texfaq2html?label=footintab>`__
* `tabularx` and longtable allow footnotes.
* `footnote` provides a "savenotes" environment which collects all
footnotes and emits them at ``end{savenotes}``
`Footnotes in LaTeX section headings
<http://www.tex.ac.uk/cgi-bin/texfaq2html?label=ftnsect>`__
* Take advantage of the fact that the mandatory argument doesn't
move if the optional argument is present::
\section[title] {title\footnote{title ftnt}}
* Use the footmisc package, with package option stable - this modifies
footnotes so that they softly and silently vanish away if used in a
moving argument.
* Use ftnxtra.
`Footnotes numbered per page
<http://www.tex.ac.uk/cgi-bin/texfaq2html?label=footnpp>`__
* perpage provides a general mechanism for resetting counters per page
* footmisc provides a package option perpage -->
</li>
<li><p class="first">use <cite>eqlist</cite> or <cite>enumitem</cite> (texlive-latex-extra) for field-lists?</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">--use-latex-when-possible</span></tt> »super option« that would set the
following:</p>
<pre class="literal-block">
--no-section-numbering
--use-latex-toc
--use-latex-docinfo
--use-latex-abstract
--use-latex-footnotes
--use-latex-citations
? (My preference is to default to use-latex-* whenever possible [GM])
</pre>
</li>
</ul>
</div>
</div>
<div class="section" id="default-layout">
<h2><a class="toc-backref" href="#id46">Default layout</a></h2>
<ul>
<li><p class="first">Use italic instead of slanted for titlereference?</p>
</li>
<li><p class="first">Start a new paragraph after lists (as currently)
or continue (no blank line in source, no parindent in output)?</p>
<p>Overriding:</p>
<ul class="simple">
<li>continue if the <a class="reference external" href="../ref/rst/directives.html#compound-paragraph">compound paragraph</a> directive is used, or</li>
<li>force a new paragraph with an empty comment.</li>
</ul>
</li>
<li><p class="first">Sidebar handling (environment with <cite>framed</cite>, <cite>marginnote</cite>, <cite>wrapfig</cite>,
...)?</p>
</li>
<li><p class="first">Use optionlist for docinfo?</p>
</li>
<li><p class="first">Keep literal-blocks together on a page, avoid pagebreaks.</p>
<p>Failed experiments up to now: samepage, minipage, pagebreak 1 to 4 before
the block.</p>
<p>Should be possible with <tt class="docutils literal"><span class="pre">--literal-block-env==lstlistings</span></tt> and some
configuration...</p>
</li>
<li><p class="first">More space between title and subtitle?</p>
<pre class="literal-block">
- \\ % subtitle%
+ \\[0.5em] % subtitle%
</pre>
</li>
</ul>
<div class="section" id="tables">
<h3><a class="toc-backref" href="#id47">Tables</a></h3>
<ul>
<li><p class="first">Improve/simplify logic to set the column width in the output.</p>
<ul class="simple">
<li>Assumed reST line length for table width setting configurable, or</li>
<li>use <cite>ltxtable</cite> (a combination of <cite>tabularx</cite> (auto-width) and
<cite>longtable</cite> (page breaks)), or</li>
<li>use tabularx column type <tt class="docutils literal">X</tt> and let LaTeX decide width, or</li>
<li>use <a class="reference external" href="http://tug.ctan.org/cgi-bin/ctanPackageInformation.py?id=tabulary">tabulary</a>?</li>
</ul>
</li>
<li><p class="first">From comp.text.tex (13. 4. 2011):</p>
<blockquote>
<p>When using fixed width columns, you should ensure that the total
width does not exceed linewidth: if the first column is p{6cm}
the second one should be p{dimexprlinewidth-6cm-4tabcolsep}
because the glue tabcolsep is added twice at every column edge.
You may also consider to set tabcolsep to a different value...</p>
</blockquote>
</li>
<li><p class="first">csv-tables do not have a colwidth.</p>
</li>
<li><p class="first">Add more classes or options, e.g. for</p>
<ul class="simple">
<li>column width set by latex,</li>
<li>horizontal alignment and rules.</li>
<li>long table vs. tabular (see next item).</li>
</ul>
</li>
<li><p class="first">Use tabular instead of longtable for tables in legends or generally
inside a float?</p>
<p>Alternatively, default to tabular and use longtable only if specified
by config setting or class argument (analogue to booktable)?</p>
</li>
<li><p class="first">Table heads and footer for longtable (firstpage lastpage ..)?</p>
</li>
<li><p class="first">In tools.txt the option tables right column, there should be some more
spacing between the description and the next paragraph "Default:".</p>
</li>
<li><p class="first">Paragraph separation in tables is hairy.
see <a class="reference external" href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=struttab">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=struttab</a></p>
<ul class="simple">
<li>The strut solution did not work.</li>
<li>setting extrarowheight added ad top of row not between paragraphs in
a cell. ALTHOUGH i set it to 2pt because, text is too close to the topline.</li>
<li>baselineskip/stretch does not help.</li>
</ul>
</li>
<li><p class="first">Should there be two hlines after table head and on table end?</p>
</li>
<li><p class="first">Place titled tables in a float ('table' environment)?</p>
<p>The 'table', 'csv-table', and 'list-table' directives support an (optional)
table title. In analogy to the 'figure' directive this should map to a
table float.</p>
</li>
</ul>
</div>
<div class="section" id="image-and-figure-directives">
<h3><a class="toc-backref" href="#id48">Image and figure directives</a></h3>
<ul>
<li><p class="first">compare the test case in:</p>
<ul class="simple">
<li><a class="reference external" href="../../test/functional/input/data/standard.txt">../../test/functional/input/data/standard.txt</a></li>
<li><a class="reference external" href="../../test/functional/expected/standalone_rst_html4css1.html">../../test/functional/expected/standalone_rst_html4css1.html</a></li>
<li><a class="reference external" href="../../test/functional/expected/standalone_rst_latex.tex">../../test/functional/expected/standalone_rst_latex.tex</a></li>
</ul>
</li>
<li><p class="first">The default CSS styling for HTML output (plain.css, default.css) lets
text following a right- or left-aligned image float to the side of the
image/figure.</p>
<ul class="simple">
<li>Use this default also for LaTeX?</li>
<li>Wrap text around figures/images with class argument "wrap"
(like the odt writer)?</li>
</ul>
<p>Use <cite>wrapfig</cite> (or other recommended) package.</p>
</li>
<li><p class="first">support more graphic formats (especially SVG, the only standard
vector format for HTML)</p>
<p>There is a <a class="reference external" href="http://mirror.ctan.org/macros/latex/contrib/flashmovie">SWF package</a> at CTAN.</p>
</li>
</ul>
</div>
</div>
<div class="section" id="missing-features">
<h2><a class="toc-backref" href="#id49">Missing features</a></h2>
<ul>
<li><p class="first">support "figwidth" argument for figures.</p>
<p>As the 'figwidth' argument is still ignored and the "natural width" of
a figure in LaTeX is 100 % of the text width, setting the 'align'
argument has currently no effect on the LaTeX output.</p>
</li>
<li><p class="first">Let <cite>meta</cite> directive insert PDF-keywords into header?</p>
</li>
<li><p class="first">Multiple author entries in docinfo (same thing as in html).
(already solved?)</p>
</li>
<li><p class="first">Consider supporting the "compact" option and class argument (from
rst2html) as some lists look better compact and others need the space.</p>
</li>
<li><p class="first">Better citation support
(see <a class="reference internal" href="#footnote-citation-gathering">Footnote & Citation Gathering</a>).</p>
</li>
<li><p class="first">If <tt class="docutils literal"><span class="pre">use-latex-citations</span></tt> is used, a bibliography is inserted right at the
end of the document.</p>
<p>Put in place of the to-be-implemented "citations" directive
(see <a class="reference internal" href="#footnote-citation-gathering">Footnote & Citation Gathering</a>).</p>
</li>
</ul>
<div class="section" id="unicode-to-latex">
<h3><a class="toc-backref" href="#id50">Unicode to LaTeX</a></h3>
<p>The <a class="reference external" href="http://www.lyx.org">LyX</a> document processor has a comprehensive
Unicode to LaTeX conversion feature with a file called <tt class="docutils literal">unicodesymbols</tt>
that lists LaTeX counterparts for a wide range of Unicode characters.</p>
<ul class="simple">
<li>Use this in the LaTeXTranslator?
Think of copyright issues!</li>
<li>The "ucs" package has many translations in ...doc/latex/ucs/config/</li>
<li>The <a class="reference external" href="http://code.google.com/p/bibstuff/">bibstuff</a> tool ships a <cite>latex_codec</cite> Python module!</li>
</ul>
</div>
<div class="section" id="allow-choice-between-utf8-standard-and-utf8x-extended-encodings">
<h3><a class="toc-backref" href="#id51">Allow choice between utf8 (standard) and utf8x (extended) encodings</a></h3>
<ul class="simple">
<li>Allow the user to select <em>utf8</em> or <em>utf8x</em> LaTeX encoding. (Docutil's
output encoding becomes LaTeX's input encoding.)</li>
</ul>
<p>The <cite>ucs</cite> package provides extended support for UTF-8 encoding in LaTeX
via the <cite>inputenc</cite>-option <tt class="docutils literal">utf8x</tt>. It is, however, a non-standard
extension and no longer developed.</p>
<dl class="docutils">
<dt>Ideas:</dt>
<dd><ol class="first last loweralpha simple">
<li>Python has 4 names for the UTF-8 encoding (<tt class="docutils literal">utf_8, U8, UTF, utf8</tt>)
give a special meaning to one of the aliases,</li>
<li>scan "stylesheets" and "latex-preamble" options and use <tt class="docutils literal">utf8x</tt>
if it contains <tt class="docutils literal">ucs</tt></li>
</ol>
</dd>
</dl>
</div>
<div class="section" id="xetex-writer">
<h3><a class="toc-backref" href="#id52">XeTeX writer</a></h3>
<ul class="simple">
<li>Glyphs missing in the font are left out in the PDF without warning
(e.g. ⇔ left-right double arrow in the functional test output).</li>
<li>Disable word-wrap (hyphenation) in literal text locally with
<tt class="docutils literal"><span class="pre">providecommand{\nohyphenation}{\addfontfeatures{HyphenChar=None}}</span></tt>?</li>
</ul>
</div>
<div class="section" id="problematic-urls">
<h3><a class="toc-backref" href="#id53">problematic URLs</a></h3>
<ul>
<li><p class="first">^^ LaTeX's special syntax for characters results in "strange" replacements
(both with href and url).</p>
<p><a class="reference external" href="../strange^^name">file with ^^</a>:
<a class="reference external" href="../strange^^name">../strange^^name</a></p>
</li>
<li><p class="first">Unbalanced braces, { or }, will fail (both with href and url):</p>
<pre class="literal-block">
`file with { <../strange{name>`__
`<../strange{name>`__
</pre>
</li>
</ul>
<p>Currently, a warning is written to the error output stream.</p>
<p>For correct printing, we can</p>
<ul>
<li><p class="first">use the href command with "normal" escaped name argument, or</p>
</li>
<li><p class="first">define a url-command in the preamble</p>
<pre class="literal-block">
\urldef{\fragileURLi}\nolinkurl{myself%node@gateway.net}
</pre>
</li>
</ul>
<p>but need to find a way to insert it as href argument.</p>
<p>The following fails:</p>
<pre class="literal-block">
\href{http://www.w3.org/XML/Schema^^dev}{\fragileURLi}
</pre>
<p>Use %-replacement like <a class="reference external" href="http://nowhere/url_with%28parens%29">http://nowhere/url_with%28parens%29</a> ?</p>
<p>-> does not work for file paths (with pdflatex and xpdf).</p>
</div>
<div class="section" id="add-stylesheet-option">
<h3><a class="toc-backref" href="#id54">add-stylesheet option</a></h3>
<p>From <a class="reference external" href="http://article.gmane.org/gmane.text.docutils.devel/3429/">http://article.gmane.org/gmane.text.docutils.devel/3429/</a></p>
<p>The problem is that since we have a default value, we have to
differentiate between adding another stylesheet and replacing the
default. I suggest that the existing --stylesheet & --stylesheet-path
options keep their semantics to replace the existing settings. We
could introduce new --add-stylesheet & --add-stylesheet-path options,
which accumulate; further --stylesheet/--stylesheet-path options would
clear these lists. The stylesheet or stylesheet_path setting (only
one may be set), plus the added_stylesheets and added_stylesheet_paths
settings, describe the combined styles.</p>
<p>For example, this run will have only one custom stylesheet:</p>
<blockquote>
rstpep2html.py --stylesheet-path custom.css ...</blockquote>
<p>This run will use the default stylesheet, and the custom one:</p>
<blockquote>
rstpep2html.py --add-stylesheet-path custom.css ...</blockquote>
<p>This run will use the default stylesheet, a custom local stylesheet,
and an external stylesheet:</p>
<blockquote>
<dl class="docutils">
<dt>rstpep2html.py --add-stylesheet-path custom.css </dt>
<dd>--add-stylesheet <a class="reference external" href="http://www.example.org/external.css">http://www.example.org/external.css</a> ...</dd>
</dl>
</blockquote>
<p>This run will use only the second custom stylesheet:</p>
<blockquote>
<dl class="docutils">
<dt>rstpep2html.py --add-stylesheet-path custom.css </dt>
<dd>--stylesheet-path second.css ...</dd>
</dl>
</blockquote>
</div>
</div>
</div>
<div class="section" id="front-end-tools">
<h1><a class="toc-backref" href="#id55">Front-End Tools</a></h1>
<ul>
<li><p class="first">What about if we don't know which Reader and/or Writer we are
going to use? If the Reader/Writer is specified on the
command-line? (Will this ever happen?)</p>
<p>Perhaps have different types of front ends:</p>
<ol class="loweralpha simple">
<li><span class="target" id="fully-qualified">Fully qualified</span>: Reader and Writer are hard-coded into the
front end (e.g. <tt class="docutils literal">pep2html [options]</tt>, <tt class="docutils literal">pysource2pdf
[options]</tt>).</li>
<li><span class="target" id="partially-qualified">Partially qualified</span>: Reader is hard-coded, and the Writer is
specified a sub-command (e.g. <tt class="docutils literal">pep2 html [options]</tt>,
<tt class="docutils literal">pysource2 pdf [options]</tt>). The Writer is known before option
processing happens, allowing the OptionParser to be built
dynamically. Alternatively, the Writer could be hard-coded and
the Reader specified as a sub-command (e.g. <tt class="docutils literal">htmlfrom pep
[options]</tt>).</li>
<li><span class="target" id="unqualified">Unqualified</span>: Reader and Writer are specified as subcommands
(e.g. <tt class="docutils literal">publish pep html [options]</tt>, <tt class="docutils literal">publish pysource pdf
[options]</tt>). A single front end would be sufficient, but
probably only useful for testing purposes.</li>
<li><span class="target" id="dynamic">Dynamic</span>: Reader and/or Writer are specified by options, with
defaults if unspecified (e.g. <tt class="docutils literal">publish <span class="pre">--writer</span> pdf
[options]</tt>). Is this possible? The option parser would have
to be told about new options it needs to handle, on the fly.
Component-specific options would have to be specified <em>after</em>
the component-specifying option.</li>
</ol>
<p>Allow common options before subcommands, as in CVS? Or group all
options together? In the case of the <a class="reference internal" href="#fully-qualified">fully qualified</a>
front ends, all the options will have to be grouped together
anyway, so there's no advantage (we can't use it to avoid
conflicts) to splitting common and component-specific options
apart.</p>
</li>
<li><p class="first">Parameterize help text & defaults somehow? Perhaps a callback? Or
initialize <tt class="docutils literal">settings_spec</tt> in <tt class="docutils literal">__init__</tt> or <tt class="docutils literal">init_options</tt>?</p>
</li>
<li><p class="first">Disable common options that don't apply?
(This should now be easier with <tt class="docutils literal">frontend.filter_settings_spec</tt>.)</p>
</li>
<li><p class="first">Add <tt class="docutils literal"><span class="pre">--section-numbering</span></tt> command line option. The "sectnum"
directive should override the <tt class="docutils literal"><span class="pre">--no-section-numbering</span></tt> command
line option then.</p>
</li>
<li><p class="first">Create a single <a class="reference internal" href="#dynamic">dynamic</a> or <a class="reference internal" href="#unqualified">unqualified</a> front end that can be
installed?</p>
</li>
</ul>
<!-- Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End: -->
</div>
</div>
</body>
</html>
|