10d88b603Schristos************************************************************************ 20d88b603Schristos* Official mandoc TODO. 3*9ff1f2acSchristos* Id: TODO,v 1.218 2016/06/05 21:06:04 schwarze Exp 40d88b603Schristos************************************************************************ 50d88b603Schristos 6fec65c98SchristosMany issues are annotated for difficulty as follows: 7fec65c98Schristos 8fec65c98Schristos - loc = locality of the issue 9fec65c98Schristos * single file issue, affects file only, or very few 10fec65c98Schristos ** single module issue, affects several files of one module 11fec65c98Schristos *** cross-module issue, significantly impacts multiple modules 12fec65c98Schristos and may require substantial changes to internal interfaces 13fec65c98Schristos - exist = difficulty of the existing code in this area 14fec65c98Schristos * affected code is straightforward and easy to read and change 15fec65c98Schristos ** affected code is somewhat complex, but once you understand 16fec65c98Schristos the design, not particularly difficult to understand 17fec65c98Schristos *** affected code uses a special, exceptionally tricky design 18fec65c98Schristos - algo = difficulty of the new algorithm to be written 19fec65c98Schristos * the required logic and code is straightforward 20fec65c98Schristos ** the required logic is somewhat complex and needs a careful design 21fec65c98Schristos *** the required logic is exceptionally tricky, 22fec65c98Schristos maybe an approach to solve that is not even known yet 23fec65c98Schristos - size = the amount of code to be written or changed 24fec65c98Schristos * a small number of lines (at most 100, usually much less) 25fec65c98Schristos ** a considerable amount of code (several dozen to a few hundred) 26fec65c98Schristos *** a large amount of code (many hundreds, maybe thousands) 27fec65c98Schristos - imp = importance of the issue 28fec65c98Schristos * mostly for completeness 29fec65c98Schristos ** would be nice to have 30fec65c98Schristos *** issue causes considerable inconvenience 31fec65c98Schristos 32fec65c98SchristosObviously, as the issues have not been solved yet, these annotations 33fec65c98Schristosare mere guesses, and some may be wrong. 34fec65c98Schristos 350d88b603Schristos************************************************************************ 3670f041f9Sjoerg* crashes 370d88b603Schristos************************************************************************ 380d88b603Schristos 39fec65c98Schristos- The abort() in bufcat(), html.c, can be triggered via buffmt_includes() 40fec65c98Schristos by running -Thtml -Oincludes on a file containing a long .In argument. 41fec65c98Schristos Fixing this will probably require reworking the whole bufcat() concept. 42fec65c98Schristos loc ** exist * algo * size ** imp ** 430d88b603Schristos 440d88b603Schristos************************************************************************ 450d88b603Schristos* missing features 460d88b603Schristos************************************************************************ 470d88b603Schristos 480d88b603Schristos--- missing roff features ---------------------------------------------- 490d88b603Schristos 500d88b603Schristos- .ad (adjust margins) 510d88b603Schristos .ad l -- adjust left margin only (flush left) 520d88b603Schristos .ad r -- adjust right margin only (flush right) 530d88b603Schristos .ad c -- center text on line 540d88b603Schristos .ad b -- adjust both margins (alias: .ad n) 550d88b603Schristos .na -- temporarily disable adjustment without changing the mode 560d88b603Schristos .ad -- re-enable adjustment without changing the mode 570d88b603Schristos Adjustment mode is ignored while in no-fill mode (.nf). 58fec65c98Schristos loc *** exist *** algo ** size ** imp ** (parser reorg would help) 5970f041f9Sjoerg 6070f041f9Sjoerg- .fc (field control) 6170f041f9Sjoerg found by naddy@ in xloadimage(1) 62fec65c98Schristos loc ** exist *** algo * size * imp * 6370f041f9Sjoerg 6470f041f9Sjoerg- .nr third argument (auto-increment step size, requires \n+) 6570f041f9Sjoerg found by bentley@ in sbcl(1) Mon, 9 Dec 2013 18:36:57 -0700 66fec65c98Schristos loc * exist * algo * size * imp ** 670d88b603Schristos 680d88b603Schristos- .ns (no-space mode) occurs in xine-config(1) 69*9ff1f2acSchristos when implementing this, also let .TH set it 700d88b603Schristos reported by brad@ Sat, 15 Jan 2011 15:45:23 -0500 71fec65c98Schristos loc *** exist *** algo *** size ** imp * 720d88b603Schristos 73fec65c98Schristos- .ta (tab settings) 74fec65c98Schristos #1 most important issue naddy@ Mon, 16 Feb 2015 20:59:17 +0100 75fec65c98Schristos ircbug(1) gnats(1) reported by brad@ Sat, 15 Jan 2011 15:50:51 -0500 76fec65c98Schristos also Tcl_NewStringObj(3) via wiz@ Wed, 5 Mar 2014 22:27:43 +0100 77fec65c98Schristos also posix2time(3) Carsten Kunze Mon, 1 Dec 2014 13:03:10 +0100 78fec65c98Schristos loc ** exist *** algo ** size ** imp *** 790d88b603Schristos 8070f041f9Sjoerg- .ti (temporary indent) 81fec65c98Schristos found by naddy@ in xloadimage(1) [devel/libvstr] vstr(3) 8270f041f9Sjoerg found by bentley@ in nmh(1) Mon, 23 Apr 2012 13:38:28 -0600 83fec65c98Schristos loc ** exist ** algo ** size * imp ** (parser reorg helps a lot) 8470f041f9Sjoerg 8570f041f9Sjoerg- .while and .shift 8670f041f9Sjoerg found by jca@ in ratpoison(1) Sun, 30 Jun 2013 12:01:09 +0200 87fec65c98Schristos loc * exist ** algo ** size ** imp ** 8870f041f9Sjoerg 8970f041f9Sjoerg- \h horizontal move 90fec65c98Schristos #2 most important issue naddy@ Mon, 16 Feb 2015 20:59:17 +0100 91fec65c98Schristos found in cclive(1) nasm(1) bogofilter(1) asciidoc/DocBook output 92fec65c98Schristos bentley@ on discuss@ Sat, 21 Sep 2013 22:29:34 -0600 93fec65c98Schristos naddy@ Thu, 4 Dec 2014 16:26:41 +0100 94fec65c98Schristos loc ** exist ** algo ** size * imp *** (parser reorg helps a lot) 9570f041f9Sjoerg 9670f041f9Sjoerg- \n+ and \n- numerical register increment and decrement 9770f041f9Sjoerg found by bentley@ in sbcl(1) Mon, 9 Dec 2013 18:36:57 -0700 98fec65c98Schristos loc * exist * algo * size * imp ** 99fec65c98Schristos 100fec65c98Schristos- \n(.$ macro argument count number register; ocserv(8) by autogen 101fec65c98Schristos found by sthen@ Thu, 19 Feb 2015 22:03:01 +0000 102fec65c98Schristos loc * exist ** algo * size * imp ** 103fec65c98Schristos 104fec65c98Schristos- \w'' improve width measurements 105fec65c98Schristos would not be very useful without an expression parser, see below 106fec65c98Schristos needed for Tcl_NewStringObj(3) via wiz@ Wed, 5 Mar 2014 22:27:43 +0100 107fec65c98Schristos loc ** exist *** algo *** size * imp *** 1080d88b603Schristos 109*9ff1f2acSchristos- \\ in high-level macro arguments 110*9ff1f2acSchristos Currently, \\ is expanded in two situations: 111*9ff1f2acSchristos 1) macro and string definition (roff.c setstrn()) 112*9ff1f2acSchristos 2) macro argument parsing (mandoc.c mandoc_getarg()) 113*9ff1f2acSchristos For user defined macros, the second happens in time because of ROFF_REPARSE. 114*9ff1f2acSchristos But for standard high-level macros, it only happens after entering the 115*9ff1f2acSchristos high level parsers, which is too late because the code doesn't get 116*9ff1f2acSchristos back to roff.c roff_res() from that point. Because this requires 117*9ff1f2acSchristos distinguishing requests, user-defined macros and standard macros 118*9ff1f2acSchristos on the roff_res() level, it is hard to solve without the parser reorg. 119*9ff1f2acSchristos Found by naddy@ in devel/cutils cobfusc(1) Mon, 16 Feb 2015 19:10:52 +0100 120*9ff1f2acSchristos loc *** exist *** algo *** size ** imp * 121*9ff1f2acSchristos 1220d88b603Schristos- using undefined strings or macros defines them to be empty 1230d88b603Schristos wl@ Mon, 14 Nov 2011 14:37:01 +0000 124fec65c98Schristos loc * exist * algo * size * imp * 1250d88b603Schristos 1260d88b603Schristos--- missing mdoc features ---------------------------------------------- 1270d88b603Schristos 1280d88b603Schristos- .Bl -column .Xo support is missing 1290d88b603Schristos ultimate goal: 1300d88b603Schristos restore .Xr and .Dv to 1310d88b603Schristos lib/libc/compat-43/sigvec.3 1320d88b603Schristos lib/libc/gen/signal.3 1330d88b603Schristos lib/libc/sys/sigaction.2 134fec65c98Schristos loc * exist *** algo *** size * imp ** 1350d88b603Schristos 1360d88b603Schristos- edge case: decide how to deal with blk_full bad nesting, e.g. 1370d88b603Schristos .Sh .Nm .Bk .Nm .Ek .Sh found by jmc@ in ssh-keygen(1) 1380d88b603Schristos from jmc@ Wed, 14 Jul 2010 18:10:32 +0100 139fec65c98Schristos loc * exist *** algo *** size ** imp ** 1400d88b603Schristos 141fec65c98Schristos- .Bd -centered implies -filled, not -unfilled, which is not 142fec65c98Schristos easy to implement; it requires code similar to .ce, which 143fec65c98Schristos we don't have either. 144fec65c98Schristos Besides, groff has bug causing text right *before* .Bd -centered 145fec65c98Schristos to be centered as well. 146fec65c98Schristos loc *** exist *** algo ** size ** imp ** (parser reorg would help) 1470d88b603Schristos 1480d88b603Schristos- .Bd -filled should not be the same as .Bd -ragged, but align both 1490d88b603Schristos the left and right margin. In groff, it is implemented in terms 1500d88b603Schristos of .ad b, which we don't have either. Found in cksum(1). 151fec65c98Schristos loc *** exist *** algo ** size ** imp ** (parser reorg would help) 1520d88b603Schristos 1530d88b603Schristos- implement blank `Bl -column', such as 1540d88b603Schristos .Bl -column 1550d88b603Schristos .It foo Ta bar 1560d88b603Schristos .El 157fec65c98Schristos loc * exist *** algo *** size * imp * 1580d88b603Schristos 1590d88b603Schristos- explicitly disallow nested `Bl -column', which would clobber internal 1600d88b603Schristos flags defined for struct mdoc_macro 161fec65c98Schristos loc * exist * algo * size * imp ** 1620d88b603Schristos 1630d88b603Schristos- In .Bl -column .It, the end of the line probably has to be regarded 1640d88b603Schristos as an implicit .Ta, if there could be one, see the following mildly 1650d88b603Schristos ugly code from login.conf(5): 1660d88b603Schristos .Bl -column minpasswordlen program xetcxmotd 1670d88b603Schristos .It path Ta path Ta value of Dv _PATH_DEFPATH 1680d88b603Schristos .br 1690d88b603Schristos Default search path. 1700d88b603Schristos reported by Michal Mazurek <akfaew at jasminek dot net> 1710d88b603Schristos via jmc@ Thu, 7 Apr 2011 16:00:53 +0059 172fec65c98Schristos loc * exist *** algo ** size * imp ** 1730d88b603Schristos 1740d88b603Schristos- inside `.Bl -column' phrases, punctuation is handled like normal 1750d88b603Schristos text, e.g. `.Bl -column .It Fl x . Ta ...' should give "-x -." 1760d88b603Schristos 1770d88b603Schristos- inside `.Bl -column' phrases, TERMP_IGNDELIM handling by `Pf' 1780d88b603Schristos is not safe, e.g. `.Bl -column .It Pf a b .' gives "ab." 1790d88b603Schristos but should give "ab ." 1800d88b603Schristos 181fec65c98Schristos- check whether it is correct that `D1' uses INDENT+1; 182fec65c98Schristos does it need its own constant? 183fec65c98Schristos loc * exist ** algo ** size * imp ** 1840d88b603Schristos 1850d88b603Schristos- prohibit `Nm' from having non-text HEAD children 1860d88b603Schristos (e.g., NetBSD mDNSShared/dns-sd.1) 1870d88b603Schristos (mdoc_html.c and mdoc_term.c `Nm' handlers can be slightly simplified) 1880d88b603Schristos 189fec65c98Schristos- support translated section names 190fec65c98Schristos e.g. x11/scrotwm scrotwm_es.1:21:2: error: NAME section must be first 191fec65c98Schristos that one uses NOMBRE because it is spanish... 192fec65c98Schristos deraadt tends to think that section-dependent macro behaviour 193fec65c98Schristos is a bad idea in the first place, so this may be irrelevant 194fec65c98Schristos loc ** exist ** algo ** size * imp ** 195fec65c98Schristos 1960d88b603Schristos- When there is free text in the SYNOPSIS and that free text contains 1970d88b603Schristos the .Nm macro, groff somehow understands to treat the .Nm as an in-line 1980d88b603Schristos macro, while mandoc treats it as a block macro and breaks the line. 1990d88b603Schristos No idea how the logic for distinguishing in-line and block instances 2000d88b603Schristos should be, needs investigation. 2010d88b603Schristos uqs@ Thu, 2 Jun 2011 11:03:51 +0200 2020d88b603Schristos uqs@ Thu, 2 Jun 2011 11:33:35 +0200 203fec65c98Schristos loc * exist ** algo *** size * imp ** 2040d88b603Schristos 2050d88b603Schristos--- missing man features ----------------------------------------------- 2060d88b603Schristos 2070d88b603Schristos- -T[x]html doesn't stipulate non-collapsing spaces in literal mode 2080d88b603Schristos 2090d88b603Schristos--- missing tbl features ----------------------------------------------- 2100d88b603Schristos 211*9ff1f2acSchristos- horizontal lines in the layout still consume data cells 212*9ff1f2acSchristos and can be mixed with actual data on the same table line 213*9ff1f2acSchristos synaptics(4) found by tedu@ Mon, 17 Aug 2015 21:17:42 -0400 214*9ff1f2acSchristos loc ** exist ** algo ** size ** imp *** 215*9ff1f2acSchristos 216*9ff1f2acSchristos- the "w" layout option is ignored 217*9ff1f2acSchristos synaptics(4) found by tedu@ Mon, 17 Aug 2015 21:17:42 -0400 218*9ff1f2acSchristos loc * exist * algo * size * imp ** 219*9ff1f2acSchristos 220*9ff1f2acSchristos- the "s" layout column specifier is used for placement of data 221*9ff1f2acSchristos into columns, but ignored during column width calculations 222*9ff1f2acSchristos synaptics(4) found by tedu@ Mon, 17 Aug 2015 21:17:42 -0400 223*9ff1f2acSchristos loc * exist ** algo *** size * imp ** 224*9ff1f2acSchristos 225*9ff1f2acSchristos- support mdoc(7) and man(7) macros inside tbl(7) code; 226*9ff1f2acSchristos probably requires the parser reorg and letting tbl(7) 227*9ff1f2acSchristos use roff_node such that macro sets can mix; 228*9ff1f2acSchristos informed by bapt@ that FreeBSD needs this. 229*9ff1f2acSchristos loc *** exist ** algo *** size ** imp *** 230*9ff1f2acSchristos 231fec65c98Schristos- look at the POSIX manuals in the books/man-pages-posix port, 232fec65c98Schristos they use some unsupported tbl(7) features. 233fec65c98Schristos loc * exist ** algo ** size ** imp *** 234fec65c98Schristos 235fec65c98Schristos- use Unicode U+2500 to U+256C for table borders 236fec65c98Schristos in tbl(7) -Tutf-8 output 237fec65c98Schristos suggested by bentley@ Tue, 14 Oct 2014 04:10:55 -0600 238fec65c98Schristos loc * exist ** algo * size * imp ** 2390d88b603Schristos 240fec65c98Schristos--- missing eqn features ----------------------------------------------- 241fec65c98Schristos 242*9ff1f2acSchristos- In a matrix, break the output line after each matrix line. 243*9ff1f2acSchristos Found in the discussion at CDBUG 2015. 244*9ff1f2acSchristos Suggested by Avi Weinstock. 245*9ff1f2acSchristos loc * exist * algo * size * imp ** 246*9ff1f2acSchristos 247fec65c98Schristos- The "size" keyword is parsed, but ignored by the formatter. 248fec65c98Schristos loc * exist * algo * size * imp * 249fec65c98Schristos 250fec65c98Schristos- The spacing characters `~', `^', and tab are currently ignored, 251fec65c98Schristos see User's Guide (Second Edition) page 2 section 4. 252fec65c98Schristos loc * exist * algo ** size * imp ** 253fec65c98Schristos 254fec65c98Schristos- Mark and lineup are parsed and ignored, 255fec65c98Schristos see User's Guide (Second Edition) page 5 section 15. 256fec65c98Schristos loc ** exist ** algo ** size ** imp ** 2570d88b603Schristos 2580d88b603Schristos--- missing misc features ---------------------------------------------- 2590d88b603Schristos 26070f041f9Sjoerg- italic correction (\/) in PostScript mode 26170f041f9Sjoerg Werner LEMBERG on groff at gnu dot org Sun, 10 Nov 2013 12:47:46 262fec65c98Schristos loc ** exist ** algo * size * imp * 26370f041f9Sjoerg 264*9ff1f2acSchristos- change the default PAGER to more -Es and use the pager 265*9ff1f2acSchristos even for apropos title line output; req by bapt@ 266*9ff1f2acSchristos loc * exist * algo * size * imp *** 267fec65c98Schristos 268fec65c98Schristos- makewhatis(8) for preformatted pages: 269fec65c98Schristos parse the section number from the header line 270fec65c98Schristos and compare to the section number from the directory name 271fec65c98Schristos loc * exist * algo * size * imp ** 272fec65c98Schristos 273fec65c98Schristos- Does makewhatis(8) detect missing NAME sections, missing names, 274fec65c98Schristos and missing descriptions in all the file formats? 275fec65c98Schristos loc * exist * algo * size * imp *** 27670f041f9Sjoerg 2770d88b603Schristos- clean up escape sequence handling, creating three classes: 2780d88b603Schristos (1) fully implemented, or parsed and ignored without loss of content 2790d88b603Schristos (2) unimplemented, potentially causing loss of content 2800d88b603Schristos or serious mangling of formatting (e.g. \n) -> ERROR 2810d88b603Schristos see textproc/mgdiff(1) for nice examples 2820d88b603Schristos (3) undefined, just output the character -> perhaps WARNING 283fec65c98Schristos loc *** exist ** algo ** size ** imp *** (parser reorg helps) 284fec65c98Schristos 285fec65c98Schristos- kettenis wants base roff, ms, and me Fri, 1 Jan 2010 22:13:15 +0100 (CET) 286fec65c98Schristos loc ** exist ** algo ** size *** imp * 287fec65c98Schristos 288*9ff1f2acSchristos- Vsevolod Stakhov (FreeBSD) needs either a markdown output formatter 289*9ff1f2acSchristos for mandoc -mdoc or a markdown to mdoc converter because they 290*9ff1f2acSchristos have to maintain manuals needed both in markdown and mdoc format. 291*9ff1f2acSchristos Look at the libsoldout (markdown -> whatever) 292*9ff1f2acSchristos loc * exist * algo * size ** imp ** 293fec65c98Schristos 294*9ff1f2acSchristos--- compatibility checks ----------------------------------------------- 295fec65c98Schristos 296fec65c98Schristos- is .Bk implemented correctly in modern groff? 297fec65c98Schristos sobrado@ Tue, 19 Apr 2011 22:12:55 +0200 298fec65c98Schristos 299fec65c98Schristos- compare output to Heirloom roff, Solaris roff, and 300fec65c98Schristos http://repo.or.cz/w/neatroff.git http://litcave.rudi.ir/ 301fec65c98Schristos 302fec65c98Schristos- look at AT&T DWB http://www2.research.att.com/sw/download 303fec65c98Schristos Carsten Kunze <carsten dot kunze at arcor dot de> has patches 304fec65c98Schristos Mon, 4 Aug 2014 17:01:28 +0200 3050d88b603Schristos 3060d88b603Schristos- look at pages generated from reStructeredText, e.g. devel/mercurial hg(1) 3070d88b603Schristos These are a weird mixture of man(7) and custom autogenerated low-level 3080d88b603Schristos roff stuff. Figure out to what extent we can cope. 3090d88b603Schristos For details, see http://docutils.sourceforge.net/rst.html 3100d88b603Schristos noted by stsp@ Sat, 24 Apr 2010 09:17:55 +0200 3110d88b603Schristos reminded by nicm@ Mon, 3 May 2010 09:52:41 +0100 3120d88b603Schristos 313fec65c98Schristos- look at pages generated from ronn(1) github.com/rtomayko/ronn 314fec65c98Schristos (based on markdown) 315fec65c98Schristos 31670f041f9Sjoerg- look at pages generated from Texinfo source by yat2m, e.g. security/gnupg 31770f041f9Sjoerg First impression is not that bad. 31870f041f9Sjoerg 319fec65c98Schristos- look at pages generated by pandoc; see 320fec65c98Schristos https://github.com/jgm/pandoc/blob/master/src/Text/Pandoc/Writers/Man.hs 321fec65c98Schristos porting planned by kili@ Thu, 19 Jun 2014 19:46:28 +0200 322fec65c98Schristos 3230d88b603Schristos- check compatibility with Plan9: 3240d88b603Schristos http://swtch.com/usr/local/plan9/tmac/tmac.an 3250d88b603Schristos http://swtch.com/plan9port/man/man7/man.html 3260d88b603Schristos "Anthony J. Bentley" <anthonyjbentley@gmail.com> 28 Dec 2010 21:58:40 -0700 3270d88b603Schristos 328*9ff1f2acSchristos- check compatibility with COHERENT troff: 329*9ff1f2acSchristos http://www.nesssoftware.com/home/mwc/source.php 330*9ff1f2acSchristos 331fec65c98Schristos- check compatibility with the man(7) formatter 332fec65c98Schristos https://raw.githubusercontent.com/rofl0r/hardcore-utils/master/man.c 333fec65c98Schristos 334fec65c98Schristos- check compatibility with 335fec65c98Schristos http://ikiwiki.info/plugins/contrib/mandoc/ 336fec65c98Schristos https://github.com/schmonz/ikiwiki/compare/mandoc 337fec65c98Schristos Amitai Schlair Mon, 19 May 2014 14:05:53 -0400 338fec65c98Schristos 3390d88b603Schristos************************************************************************ 3400d88b603Schristos* formatting issues: ugly output 3410d88b603Schristos************************************************************************ 3420d88b603Schristos 343fec65c98Schristos- revisit empty in-line macros 344fec65c98Schristos look at the difference between "Em x Em ." and "Sq x Em ." 345fec65c98Schristos Carsten Kunze Fri, 12 Dec 2014 00:15:41 +0100 346fec65c98Schristos loc *** exist *** algo *** size * imp ** 347fec65c98Schristos 348fec65c98Schristos- a column list with blank `Ta' cells triggers a spurious 3490d88b603Schristos start-with-whitespace printing of a newline 3500d88b603Schristos 351fec65c98Schristos- In .Bl -column, .It a<tab>"b<tab>c" 352fec65c98Schristos shows the quotes in groff, but not in mandoc 353fec65c98Schristos loc * exist *** algo ** size * imp ** 354fec65c98Schristos 3550d88b603Schristos- In .Bl -column, 3560d88b603Schristos .It Em Authentication<tab>Key Length 3570d88b603Schristos ought to render "Key Length" with emphasis, too, 3580d88b603Schristos see OpenBSD iked.conf(5). 3590d88b603Schristos reported again Nicolas Joly via wiz@ Wed, 12 Oct 2011 00:20:00 +0200 360fec65c98Schristos loc * exist *** algo *** size ** imp *** 3610d88b603Schristos 3620d88b603Schristos- empty phrases in .Bl column produce too few blanks 3630d88b603Schristos try e.g. .Bl -column It Ta Ta 3640d88b603Schristos reported by millert Fri, 02 Apr 2010 16:13:46 -0400 365fec65c98Schristos loc * exist *** algo *** size * imp ** 3660d88b603Schristos 3670d88b603Schristos- .%T can have trailing punctuation. Currently, it puts the trailing 3680d88b603Schristos punctuation into a trailing MDOC_TEXT element inside its own scope. 3690d88b603Schristos That element should rather be outside its scope, such that the 3700d88b603Schristos punctuation does not get underlines. This is not trivial to 3710d88b603Schristos implement because .%T then needs some features of in_line_eoln() - 3720d88b603Schristos slurp all arguments into one single text element - and one feature 3730d88b603Schristos of in_line() - put trailing punctuation out of scope. 3740d88b603Schristos Found in mount_nfs(8) and exports(5), search for "Appendix". 375fec65c98Schristos loc ** exist ** algo *** size * imp ** 3760d88b603Schristos 37770f041f9Sjoerg- Trailing punctuation after .%T triggers EOS spacing, at least 37870f041f9Sjoerg outside .Rs (eek!). Simply setting ARGSFL_DELIM for .%T is not 37970f041f9Sjoerg the right solution, it sends mandoc into an endless loop. 38070f041f9Sjoerg reported by Nicolas Joly Sat, 17 Nov 2012 11:49:54 +0100 381fec65c98Schristos loc * exist ** algo ** size * imp ** 382fec65c98Schristos 383fec65c98Schristos- global variables in the SYNOPSIS of section 3 pages 384fec65c98Schristos .Vt vs .Vt/.Va vs .Ft/.Va vs .Ft/.Fa ... 385fec65c98Schristos from kristaps@ Tue, 08 Jun 2010 11:13:32 +0200 38670f041f9Sjoerg 3870d88b603Schristos- in enclosures, mandoc sometimes fancies a bogus end of sentence 3880d88b603Schristos reminded by jmc@ Thu, 23 Sep 2010 18:13:39 +0059 389fec65c98Schristos loc * exist ** algo *** size * imp *** 390fec65c98Schristos 391fec65c98Schristos- a line starting with "\fB something" counts as starting with whitespace 392fec65c98Schristos and triggers a line break; found in audio/normalize-mp3(1) 393fec65c98Schristos loc ** exist * algo ** size * imp ** 3940d88b603Schristos 39570f041f9Sjoerg- formatting /usr/local/man/man1/latex2man.1 with groff and mandoc 39670f041f9Sjoerg reveals lots of bugs both in groff and mandoc... 39770f041f9Sjoerg reported by bentley@ Wed, 22 May 2013 23:49:30 -0600 39870f041f9Sjoerg 399fec65c98Schristos--- PDF issues --------------------------------------------------------- 400fec65c98Schristos 401fec65c98Schristos- PDF output doesn't use a monospaced font for .Bd -literal 402fec65c98Schristos Example: "mandoc -Tpdf afterboot.8 > output.pdf && pdfviewer output.pdf". 403fec65c98Schristos Search the text "Routing tables". 404fec65c98Schristos Also check what PostScript mode does when fixing this. 405fec65c98Schristos reported by juanfra@ Wed, 04 Jun 2014 21:44:58 +0200 406fec65c98Schristos instructions from juanfra@ Wed, 11 Jun 2014 02:21:01 +0200 407fec65c98Schristos add a new <</Type /Font>> block to the PDF files with /BaseFont /Courier 408fec65c98Schristos and change the /Name from /F0 to the new font (/F5 (?)). 409fec65c98Schristos loc * exist ** algo ** size * imp ** 410fec65c98Schristos 411fec65c98Schristos--- HTML issues -------------------------------------------------------- 412fec65c98Schristos 413fec65c98Schristos- <dl><dt><dd> formatting is ugly 414fec65c98Schristos hints are easy to find on the web, e.g. 415fec65c98Schristos http://stackoverflow.com/questions/1713048/ 416fec65c98Schristos see also matthew@ Fri, 18 Jul 2014 19:25:12 -0700 417fec65c98Schristos loc * exist * algo ** size * imp *** 418fec65c98Schristos 419*9ff1f2acSchristos- In -man -Thtml, .nf does not preserve indentation. 420*9ff1f2acSchristos It should either convert blanks to 421*9ff1f2acSchristos or use <pre> rather than <div> (like .Bd -literal does). 422*9ff1f2acSchristos Reported by afresh1@ 12 Apr 2016 14:35:45 -0700 423*9ff1f2acSchristos 424*9ff1f2acSchristos- .Bf at the beginning of a paragraph inserts a bogus 1ex horizontal 425*9ff1f2acSchristos space, see for example random(3). Introduced in 426*9ff1f2acSchristos http://mdocml.bsd.lv/cgi-bin/cvsweb/mdoc_html.c.diff?r1=1.91&r2=1.92 427*9ff1f2acSchristos reported by deraadt@ Mon, 28 Sep 2015 20:14:13 -0600 (MDT) 428*9ff1f2acSchristos loc ** exist ** algo ** size * imp * 429*9ff1f2acSchristos 430fec65c98Schristos- jsg on icb, Nov 3, 2014: 431fec65c98Schristos try to guess Xr in man(7) for hyperlinking 432fec65c98Schristos 433fec65c98Schristos- The tables used to render the three-part page headers actually force 434fec65c98Schristos the width of the <body> to the max-width given for <html>. 435fec65c98Schristos Not yet sure how to fix that... 436fec65c98Schristos Observed by an Anonymous Coward on undeadly.org: 437fec65c98Schristos http://undeadly.org/cgi?action=article&sid=20140925064244&pid=1 438fec65c98Schristos loc * exist * algo ** size * imp *** 439fec65c98Schristos 440fec65c98Schristos- consider whether <var> can be used for Ar Dv Er Ev Fa Va. 441fec65c98Schristos from bentley@ Wed, 13 Aug 2014 09:17:55 -0600 442fec65c98Schristos 443*9ff1f2acSchristos- generate <img> tags in HTML 444*9ff1f2acSchristos idea from florian@ Tue, 7 Apr 2015 00:26:28 +0000 445*9ff1f2acSchristos may be possible to implement with .Lk img://something.png alt_text 446*9ff1f2acSchristos 447fec65c98Schristos- check https://github.com/trentm/mdocml 448fec65c98Schristos 4490d88b603Schristos************************************************************************ 4500d88b603Schristos* formatting issues: gratuitous differences 4510d88b603Schristos************************************************************************ 4520d88b603Schristos 453fec65c98Schristos- .Fn reopens a new scope after punctuation in mandoc, 454fec65c98Schristos but closes its scope for good in groff. 455fec65c98Schristos Do we want to change mandoc or groff? 456fec65c98Schristos Steffen Nurpmeso Sat, 08 Nov 2014 13:34:59 +0100 457fec65c98Schristos loc * exist ** algo ** size * imp ** 4580d88b603Schristos 459fec65c98Schristos- In .Bl -enum -width 0n, groff continues one the same line after 460fec65c98Schristos the number, mandoc breaks the line. 461fec65c98Schristos mail to kristaps@ Mon, 20 Jul 2009 02:21:39 +0200 462fec65c98Schristos loc * exist ** algo ** size * imp ** 4630d88b603Schristos 4640d88b603Schristos- .Pp between two .It in .Bl -column should produce one, 4650d88b603Schristos not two blank lines, see e.g. login.conf(5). 4660d88b603Schristos reported by jmc@ Sun, 17 Apr 2011 14:04:58 +0059 4670d88b603Schristos reported again by sthen@ Wed, 18 Jan 2012 02:09:39 +0000 (UTC) 468fec65c98Schristos loc * exist *** algo ** size * imp ** 4690d88b603Schristos 4700d88b603Schristos- If the *first* line after .It is .Pp, break the line right after 4710d88b603Schristos the tag, do not pad with space characters before breaking. 4720d88b603Schristos See the description of the a, c, and i commands in sed(1). 473fec65c98Schristos loc * exist ** algo ** size * imp ** 4740d88b603Schristos 4750d88b603Schristos- If the first line after .It is .D1, do not assert a blank line 4760d88b603Schristos in between, see for example tmux(1). 4770d88b603Schristos reported by nicm@ 13 Jan 2011 00:18:57 +0000 478fec65c98Schristos loc * exist ** algo ** size * imp ** 4790d88b603Schristos 48070f041f9Sjoerg- Trailing punctuation after .It should trigger EOS spacing. 48170f041f9Sjoerg reported by Nicolas Joly Sat, 17 Nov 2012 11:49:54 +0100 48270f041f9Sjoerg Probably, this should be fixed somewhere in termp_it_pre(), not sure. 483fec65c98Schristos loc * exist ** algo ** size * imp ** 48470f041f9Sjoerg 4850d88b603Schristos- .Nx 1.0a 4860d88b603Schristos should be "NetBSD 1.0A", not "NetBSD 1.0a", 4870d88b603Schristos see OpenBSD ccdconfig(8). 488fec65c98Schristos loc * exist * algo * size * imp ** 4890d88b603Schristos 4900d88b603Schristos- In .Bl -tag, if a tag exceeds the right margin and must be continued 4910d88b603Schristos on the next line, it must be indented by -width, not width+1; 4920d88b603Schristos see "rule block|pass" in OpenBSD ifconfig(8). 493fec65c98Schristos loc * exist *** algo ** size * imp ** 4940d88b603Schristos 4950d88b603Schristos- When the -width string contains macros, the macros must be rendered 4960d88b603Schristos before measuring the width, for example 4970d88b603Schristos .Bl -tag -width ".Dv message" 4980d88b603Schristos in magic(5), located in src/usr.bin/file, is the same 4990d88b603Schristos as -width 7n, not -width 11n. 5000d88b603Schristos The same applies to .Bl -column column widths; 5010d88b603Schristos reported again by Nicolas Joly Thu, 1 Mar 2012 13:41:26 +0100 via wiz@ 5 Mar 50270f041f9Sjoerg reported again by Franco Fichtner Fri, 27 Sep 2013 21:02:28 +0200 503fec65c98Schristos loc *** exist *** algo *** size ** imp *** 50470f041f9Sjoerg An easy partial fix would be to just skip the first word if it starts 50570f041f9Sjoerg with a dot, including any following white space, when measuring. 506fec65c98Schristos loc * exist * algo * size * imp *** 5070d88b603Schristos 5080d88b603Schristos- The \& zero-width character counts as output. 5090d88b603Schristos That is, when it is alone on a line between two .Pp, 5100d88b603Schristos we want three blank lines, not two as in mandoc. 511fec65c98Schristos loc ** exist ** algo ** size * imp ** 5120d88b603Schristos 5130d88b603Schristos- Header lines of excessive length: 5140d88b603Schristos Port OpenBSD man_term.c rev. 1.25 to mdoc_term.c 5150d88b603Schristos and document it in mdoc(7) and man(7) COMPATIBILITY 5160d88b603Schristos found while talking to Chris Bennett 517fec65c98Schristos loc * exist * algo * size * imp * 5180d88b603Schristos 519*9ff1f2acSchristos- Sequences of multiple man(7) paragraphs (.PP, .IP) interspersed 520*9ff1f2acSchristos with .ps and .nf/.fi produce execessive blank lines, see libJudy 521*9ff1f2acSchristos and graphics/dcmtk. The parser reorg may help with this. 522*9ff1f2acSchristos 5230d88b603Schristos- trailing whitespace must be ignored even when followed by a font escape, 5240d88b603Schristos see for example 5250d88b603Schristos makes 5260d88b603Schristos \fBdig \fR 5270d88b603Schristos operate in batch mode 5280d88b603Schristos in dig(1). 529fec65c98Schristos loc ** exist ** algo ** size * imp ** 530fec65c98Schristos 531fec65c98Schristos************************************************************************ 532*9ff1f2acSchristos* portability 533*9ff1f2acSchristos************************************************************************ 534*9ff1f2acSchristos 535*9ff1f2acSchristos- systems having UTF-8 but not en_US.UTF-8 536*9ff1f2acSchristos call locale(1) from ./configure, select a UTF-8-locale, 537*9ff1f2acSchristos and use that for test-wchar.c and term_ascii.c 538*9ff1f2acSchristos to Markus Waldeck Sat, 18 Jul 2015 01:55:37 +0200 539*9ff1f2acSchristos loc * exist * algo * size * imp * 540*9ff1f2acSchristos 541*9ff1f2acSchristos************************************************************************ 542fec65c98Schristos* warning issues 543fec65c98Schristos************************************************************************ 544fec65c98Schristos 545*9ff1f2acSchristos- provide a way in mandoc(1) to warn about broken .Xr links; 546*9ff1f2acSchristos probably cannot be on by default in -Tlint because it needs 547*9ff1f2acSchristos to access the manpath and mandoc.db(3) after parsing. 548*9ff1f2acSchristos asked for by jmc@ Fri, 4 Dec 2015 22:39:40 +0000 549*9ff1f2acSchristos 550*9ff1f2acSchristos- Report errors in -O suboption parsing. 551*9ff1f2acSchristos loc * exist * algo * size * imp ** 552*9ff1f2acSchristos 553*9ff1f2acSchristos- warn when .Sh or .Ss contain other macros 554*9ff1f2acSchristos Steffen Nurpmeso, savannah.gnu.org/bugs/index.php?45034 555*9ff1f2acSchristos loc * exist * algo * size * imp ** 556*9ff1f2acSchristos 557fec65c98Schristos- check that MANDOCERR_BADTAB is thrown in the right cases, 558fec65c98Schristos i.e. when finding a literal tab character in fill mode, 559fec65c98Schristos and possibly change the wording of the warning message 560fec65c98Schristos to refer to fill mode, not literal mode 561fec65c98Schristos See the mail from Werner LEMBERG on the groff list, 562fec65c98Schristos Fri, 14 Feb 2014 18:54:42 +0100 (CET) 563fec65c98Schristos loc * exist ** algo ** size * imp ** 564fec65c98Schristos 565fec65c98Schristos- warn about attempts to call non-callable macros 566fec65c98Schristos Steffen Nurpmeso Tue, 11 Nov 2014 22:55:16 +0100 567fec65c98Schristos Note that formatting is inconsistent in groff. 568fec65c98Schristos .Fn Po prints "Po()", .Ar Sh prints "file ..." and no "Sh". 569fec65c98Schristos Relatively hard because the relevant code is scattered 570fec65c98Schristos all over mdoc_macro.c and all subtly different. 571fec65c98Schristos loc ** exist ** algo ** size ** imp ** 572fec65c98Schristos 573fec65c98Schristos- warn about "new sentence, new line" 574fec65c98Schristos loc ** exist ** algo *** size * imp ** 575fec65c98Schristos 576fec65c98Schristos- mandoc_special does not really check the escape sequence, 577fec65c98Schristos but just the overall format 578fec65c98Schristos loc ** exist ** algo *** size ** imp ** 579fec65c98Schristos 580fec65c98Schristos- integrate mdoclint into mandoc ("end-of-line whitespace" thread) 581fec65c98Schristos from jmc@ Mon, 13 Jul 2009 17:12:09 +0100 582fec65c98Schristos from kristaps@ Mon, 13 Jul 2009 18:34:53 +0200 583fec65c98Schristos from jmc@ Mon, 13 Jul 2009 17:45:37 +0059 584fec65c98Schristos from kristaps@ Mon, 13 Jul 2009 19:02:03 +0200 585fec65c98Schristos (mostly done, check what remains) 586fec65c98Schristos 587fec65c98Schristos- -Tlint parser errors and warnings to stdout 588fec65c98Schristos to tech@mdocml, naddy@ Wed, 28 Sep 2011 11:21:46 +0200 589fec65c98Schristos wait! kristaps@ Sun, 02 Oct 2011 17:12:52 +0200 590fec65c98Schristos 591fec65c98Schristos************************************************************************ 592fec65c98Schristos* documentation issues 593fec65c98Schristos************************************************************************ 594fec65c98Schristos 595fec65c98Schristos- mention hyphenation rules: 596fec65c98Schristos breaking at letter-letter in text mode (not macro args) 597fec65c98Schristos proper hyphenation is unimplemented 598fec65c98Schristos 599fec65c98Schristos- talk about spacing around delimiters 600fec65c98Schristos to jmc@, kristaps@ Sat, 23 Apr 2011 17:41:27 +0200 601fec65c98Schristos 602fec65c98Schristos- mark macros as: page structure domain, manual domain, general text domain 603fec65c98Schristos is this useful? 604fec65c98Schristos 605fec65c98Schristos- mention /usr/share/misc/mdoc.template in mdoc(7)? 606fec65c98Schristos 607fec65c98Schristos- Is all the content from http://www.std.com/obi/BSD/doc/usd/28.tbl/tbl 608fec65c98Schristos covered in tbl(7)? 6090d88b603Schristos 6100d88b603Schristos************************************************************************ 6110d88b603Schristos* performance issues 6120d88b603Schristos************************************************************************ 6130d88b603Schristos 614fec65c98Schristos- Why are we using MAP_SHARED, not MAP_PRIVATE for mmap(2)? 615fec65c98Schristos How does SQLITE_CONFIG_PAGECACHE actually work? Document it! 616fec65c98Schristos from kristaps@ Sat, 09 Aug 2014 13:51:36 +0200 617fec65c98Schristos 6180d88b603SchristosSeveral areas can be cleaned up to make mandoc even faster. These are 6190d88b603Schristos 6200d88b603Schristos- improve hashing mechanism for macros (quite important: performance) 6210d88b603Schristos 6220d88b603Schristos- improve hashing mechanism for characters (not as important) 6230d88b603Schristos 6240d88b603Schristos- the PDF file is HUGE: this can be reduced by using relative offsets 6250d88b603Schristos 6260d88b603Schristos- instead of re-initialising the roff predefined-strings set before each 6270d88b603Schristos parse, create a read-only version the first time and copy it 628fec65c98Schristos loc * exist ** algo ** size * imp ** 6290d88b603Schristos 6300d88b603Schristos************************************************************************ 6310d88b603Schristos* structural issues 6320d88b603Schristos************************************************************************ 6330d88b603Schristos 6340d88b603Schristos- We use the input line number at several places to distinguish 6350d88b603Schristos same-line from different-line input. That plainly doesn't work 6360d88b603Schristos with user-defined macros, leading to random breakage. 6370d88b603Schristos 6380d88b603Schristos- Find better ways to prevent endless loops 6390d88b603Schristos in roff(7) macro and string expansion. 6400d88b603Schristos 6410d88b603Schristos- Finish cleanup of date handling. 6420d88b603Schristos Decide which formats should be recognized where. 6430d88b603Schristos Update both mdoc(7) and man(7) documentation. 6440d88b603Schristos Triggered by Tim van der Molen Tue, 22 Feb 2011 20:30:45 +0100 645fec65c98Schristos 646fec65c98Schristos- struct mparse refactoring 647fec65c98Schristos Steffen Nurpmeso Thu, 04 Sep 2014 12:50:00 +0200 648fec65c98Schristos 649fec65c98Schristos- Consider creating some views that will make the database more 650fec65c98Schristos readable from the sqlite3 shell. Consider using them to 651fec65c98Schristos abstract from the database structure, too. 652fec65c98Schristos suggested by espie@ Sat, 19 Apr 2014 14:52:57 +0200 653fec65c98Schristos 654fec65c98Schristos************************************************************************ 655fec65c98Schristos* CGI issues 656fec65c98Schristos************************************************************************ 657fec65c98Schristos 658fec65c98Schristos - Enable HTTP compression by detecting gzip encoding and filtering 659fec65c98Schristos output through libz. 660fec65c98Schristos - Sandbox (see OpenSSH). 661fec65c98Schristos - Enable caching support via HTTP 304 and If-Modified-Since. 662fec65c98Schristos - Allow for cgi.h to be overridden by CGI environment variables. 663fec65c98Schristos Otherwise, binary distributions will inherit the compile-time 664fec65c98Schristos behaviour, which is not optimal. 665fec65c98Schristos - Have Mac OSX systems automatically disable -static compilation of the 666fec65c98Schristos CGI: -static isn't supported. 667fec65c98Schristos 668fec65c98Schristos************************************************************************ 669fec65c98Schristos* to improve in the groff_mdoc(7) macros 670fec65c98Schristos************************************************************************ 671fec65c98Schristos 672fec65c98Schristos- use uname(1) to set doc-default-operating-system at install time 673fec65c98Schristos tobimensch Mon, 1 Dec 2014 00:25:07 +0100 674