1************************************************************************ 2* Official mandoc TODO. 3* $Id: TODO,v 1.338 2025/07/22 13:36:54 schwarze Exp $ 4************************************************************************ 5 6Many issues are annotated for difficulty as follows: 7 8 - loc = locality of the issue 9 * single file issue, affects file only, or very few 10 ** single module issue, affects several files of one module 11 *** cross-module issue, significantly impacts multiple modules 12 and may require substantial changes to internal interfaces 13 - exist = difficulty of the existing code in this area 14 * affected code is straightforward and easy to read and change 15 ** affected code is somewhat complex, but once you understand 16 the design, not particularly difficult to understand 17 *** affected code uses a special, exceptionally tricky design 18 - algo = difficulty of the new algorithm to be written 19 * the required logic and code is straightforward 20 ** the required logic is somewhat complex and needs a careful design 21 *** the required logic is exceptionally tricky, 22 maybe an approach to solve that is not even known yet 23 - size = the amount of code to be written or changed 24 * a small number of lines (at most 100, usually much less) 25 ** a considerable amount of code (several dozen to a few hundred) 26 *** a large amount of code (many hundreds, maybe thousands) 27 - imp = importance of the issue 28 * mostly for completeness 29 ** would be nice to have 30 *** issue causes considerable inconvenience 31 32Obviously, as the issues have not been solved yet, these annotations 33are mere guesses, and some may be wrong. 34 35************************************************************************ 36* assertion failures 37************************************************************************ 38 39- .if n .ce in the middle of .TS data 40 afl case f1/id:000103,sig:06,src:009024+009105,op:splice,rep:2 (jes@) 41 While roff_parseln() prevents .ce and similar requests in the middle 42 of a tbl, the guard is no longer effective when the .ce is wrapped 43 in a roff block, for example a conditional. The resulting assertion 44 has never been seen in any real-world manual page. 45 This is too dangerous to fix before release because it requires 46 reorganizing the very delicate internals of roff_parseln(), 47 which risks causing more severe bugs. 48 loc * exist *** algo *** size * imp * 49 50 51************************************************************************ 52* bugs: invalid output 53************************************************************************ 54 55- wrong number of layout columns in tbl(7) code generated by -T man 56 https://savannah.gnu.org/bugs/?57720 57 The reason likely is that tbl(7) does not support the -Bl -column 58 feature of not explicitly specifying the last table column. 59 loc ** exist * algo ** size * imp *** 60 61- eqn(7) delimiters cause conditional lines to misbehave 62 nabijaczleweli 8 Sep 2021 15:24:48 +0200 63 loc * exist *** algo *** size * imp * 64 65- roff.c, roff_expand() should not remove blanks before comments 66 to Oliver Corff, Sep 7, 2021 67 loc * exist * algo * size * imp * 68 but watch out for regressions in the high-level parsers 69 maybe it should not even remove comments? - consider T{\" 70 71- In the body of conditional requests, escape sequence expansion 72 must not be performed if the condition is false. This implies 73 the first part of a request line must be expanded before 74 request parsing (like it is now), but expansion in the second 75 part must be delayed. 76 to Nab 8 Aug 2023 20:05:32 +0200 Subject: if/ie d condition always true 77 loc ** exist *** algo *** size ** imp * 78 79 80************************************************************************ 81* missing features 82************************************************************************ 83 84--- missing roff features ---------------------------------------------- 85 86- .ad (adjust margins) 87 .ad l -- adjust left margin only (flush left) 88 .ad r -- adjust right margin only (flush right) 89 .ad c -- center text on line 90 .ad b -- adjust both margins (alias: .ad n) 91 .na -- temporarily disable adjustment without changing the mode 92 .ad -- re-enable adjustment without changing the mode 93 Adjustment mode is ignored while in no-fill mode (.nf). 94 loc *** exist *** algo ** size ** imp ** (parser reorg would help) 95 96- .fc (field control) 97 found by naddy@ in xloadimage(1) 98 loc ** exist *** algo * size * imp * 99 100- .ns (no-space mode) occurs in xine-config(1) 101 when implementing this, also let .TH set it 102 reported by brad@ Sat, 15 Jan 2011 15:45:23 -0500 103 loc *** exist *** algo *** size ** imp * 104 105- \w'' improve width measurements 106 would not be very useful without an expression parser, see below 107 needed for Tcl_NewStringObj(3) via wiz@ Wed, 5 Mar 2014 22:27:43 +0100 108 loc ** exist *** algo *** size * imp *** 109 110- .als only works for macros in mandoc, not for user-defined strings. 111 Also, the "val" field in struct roffkv would have to be replaced 112 with a pointer to a reference-counted wrapper, and an alias 113 would have to point to the same wrapper as the original. 114 .als to undefined does nothing; the alias is not created. 115 .rm'ing the original leaves the alias to point to the old value. 116 .de .als .de changes both, but 117 .de .als .rm .de only changes the new value, not the alias. 118 Found in groffer(1) version 1.19 119 Jan Stary 20 Apr 2019 20:16:54 +0200 120 loc * exist ** algo ** size ** imp * 121 122- roff string condition comparisons fail when vars contain quotes: 123 .ds s ' 124 .if '\*s'' \&... 125 hard to fix because of the basic architecture (string replacement 126 happens before roff(7) syntax parsing) 127 Found in groffer(1) version 1.19 128 Jan Stary 20 Apr 2019 20:16:54 +0200 129 loc * exist *** algo *** size ** imp * 130 131- mandoc replaces all ASCII control characters except tab and line feed 132 with '?' during input. It would be better to replace them with 133 Unicode escapes in preconv_encode() or somewhere in the vicinity, 134 such that the already existing better replacement strings show 135 up in the output. Emulating groff is not desirable: groff replaces 136 0x00, 0x0b, and 0x0d to 0x1f with the empty string (bad because 137 that's easy to overlook for the document author), 0x01 with '.' 138 (very confusing), and passes through 0x02 to 0x08, 0x0c, and 0x7f 139 raw (bad because that is insecure output). Remember that 0x07 may 140 need special handling because it is sometimes used for certain 141 delimiters, so it may need handling *after* roff.c rather than before. 142 reminded by John Gardner 16 Jun 2020 14:26:28 +1000 143 Actually, more ASCII control characters than just 0x07 may need 144 later handling because they can for example be used in macro names. 145 So they may need handling after roff(7) processing. 146 pointed out by John Gardner 23 Jun 2020 18:28:08 +1000 147 more info from John Gardner 29 Jun 2020 19:54:04 +1000 148 loc ** exist ** algo ** size ** imp * 149 150- many missing features used in old groff_char(7), 151 some can possibly be supported 152 kamil at netbsd 12 Nov 2020 17:27:09 +0100 + reply 153 154- \s with arbitrary arg delimiters as already supported for other escapes 155 found following jmc@'s mail 28 Apr 2021 18:31:41 +0100 156 loc * exist * algo * size * imp * 157 158--- missing mdoc features ---------------------------------------------- 159 160- support mixed case for section names 161 also, first section is not "NAME" should not appear more than once per page 162 Alejandro Colomar 28 Apr 2023 16:57:49 +0200 163 loc * exist * algo * size * imp *** 164 165- .Sh and .Ss should be parsed and partially callable, see groff_mdoc(7) 166 reed at reedmedia dot net Sat, 21 Dec 2019 17:13:07 -0600 167 loc ** exist ** algo ** size ** imp * 168 169- .Bl -column .Xo support is missing 170 ultimate goal: 171 restore .Xr and .Dv to 172 lib/libc/compat-43/sigvec.3 173 lib/libc/gen/signal.3 174 lib/libc/sys/sigaction.2 175 loc * exist *** algo *** size * imp ** 176 177- edge case: decide how to deal with blk_full bad nesting, e.g. 178 .Sh .Nm .Bk .Nm .Ek .Sh found by jmc@ in ssh-keygen(1) 179 from jmc@ Wed, 14 Jul 2010 18:10:32 +0100 180 loc * exist *** algo *** size ** imp ** 181 182- .Bd -filled should not be the same as .Bd -ragged, but align both 183 the left and right margin. In groff, it is implemented in terms 184 of .ad b, which we don't have either. Found in cksum(1). 185 loc *** exist *** algo ** size ** imp ** (parser reorg would help) 186 187- implement blank `Bl -column', such as 188 .Bl -column 189 .It foo Ta bar 190 .El 191 loc * exist *** algo *** size * imp * 192 193- explicitly disallow nested `Bl -column', which would clobber internal 194 flags defined for struct mdoc_macro 195 loc * exist * algo * size * imp ** 196 197- In .Bl -column .It, the end of the line probably has to be regarded 198 as an implicit .Ta, if there could be one, see the following mildly 199 ugly code from login.conf(5): 200 .Bl -column minpasswordlen program xetcxmotd 201 .It path Ta path Ta value of Dv _PATH_DEFPATH 202 .br 203 Default search path. 204 reported by Michal Mazurek <akfaew at jasminek dot net> 205 via jmc@ Thu, 7 Apr 2011 16:00:53 +0059 206 loc * exist *** algo ** size * imp ** 207 208- inside `.Bl -column' phrases, punctuation is handled like normal 209 text, e.g. `.Bl -column .It Fl x . Ta ...' should give "-x -." 210 211- inside `.Bl -column' phrases, TERMP_IGNDELIM handling by `Pf' 212 is not safe, e.g. `.Bl -column .It Pf a b .' gives "ab." 213 but should give "ab ." 214 215- prohibit `Nm' from having non-text HEAD children 216 (e.g., NetBSD mDNSShared/dns-sd.1) 217 (mdoc_html.c and mdoc_term.c `Nm' handlers can be slightly simplified) 218 219- support translated section names 220 e.g. x11/scrotwm scrotwm_es.1:21:2: error: NAME section must be first 221 that one uses NOMBRE because it is spanish... 222 deraadt tends to think that section-dependent macro behaviour 223 is a bad idea in the first place, so this may be irrelevant 224 loc ** exist ** algo ** size * imp ** 225 226- When there is free text in the SYNOPSIS and that free text contains 227 the .Nm macro, groff somehow understands to treat the .Nm as an in-line 228 macro, while mandoc treats it as a block macro and breaks the line. 229 No idea how the logic for distinguishing in-line and block instances 230 should be, needs investigation. 231 uqs@ Thu, 2 Jun 2011 11:03:51 +0200 232 uqs@ Thu, 2 Jun 2011 11:33:35 +0200 233 loc * exist ** algo *** size * imp ** 234 235--- missing man features ----------------------------------------------- 236 237- When calling less(1), specify -P to print "name(sec) lines ..." 238 in the bottom line instead of "/tmp/man..." 239 Jan Engelhardt (SuSE) via Matej Cepl 06 Apr 2025 14:42:52 +0200 240 loc * exist * algo * size * imp ** 241 242- MANWIDTH 243 Markus Waldeck <waldeck at gmx dot de> 9 Jun 2015 05:49:56 +0200 244 Laura Morales <lauretas at mail dot com> 26 Apr 2018 08:15:55 +0200 245 Kamil Rytarowski <kamil at netbsd> 13 Nov 2020 00:19:36 +0100 246 patch from Kamil 13 Nov 2020 22:37:07 +0100 247 loc * exist * algo * size * imp * 248 249- groff_www(7) .MTO and .URL 250 These macros were used by the GNU grep(1) man page. 251 The groff_www(7) manual page itself uses them, too. 252 We should probably *not* add them to mandoc. 253 Just mentioning this here to keep track of the abuse. 254 Laura Morales <lauretas at mail dot com> 20 Apr 2018 07:33:02 +0200 255 loc ** exist * algo * size ** imp * 256 257--- missing tbl features ----------------------------------------------- 258 259- vertical centering in cells vertically spanned with ^ 260 pali dot rohar at gmail dot com 16 Jul 2018 13:03:35 +0200 261 loc * exist *** algo *** size ** imp * 262 263- support mdoc(7) and man(7) macros inside tbl(7) code; 264 probably requires the parser reorg and letting tbl(7) 265 use roff_node such that macro sets can mix; 266 informed by bapt@ that FreeBSD needs this: 3 Jan 2015 23:32:23 +0100 267 loc *** exist ** algo *** size ** imp *** 268 269- look at the POSIX manuals in the books/man-pages-posix port, 270 they use some unsupported tbl(7) features, mostly macros in tbl(7). 271 loc * exist ** algo ** size ** imp *** 272 273- look what Joerg Schilling manual pages use 274 Thu, 19 Mar 2015 18:31:48 +0100 275 276--- missing eqn features ----------------------------------------------- 277 278- In a matrix, break the output line after each matrix line. 279 Found in the discussion at CDBUG 2015. Suggested by Avi Weinstock. 280 This may not be the ideal solution after all: eqn(7) matrices 281 are lists of columns, so Avi's proposal would show each *column* 282 on its own *line*, which is likely to cause confusion. 283 A better solution, but much harder to implement, would be to 284 actually show the coordinates of column vectors on different 285 terminal output lines, using the clumnated output facilities 286 developed for .Bl -tag, .Bl -column, and also used for tbl(7). 287 loc * exist * algo ** size ** imp ** 288 289- The "size" keyword is parsed, but ignored by the formatter. 290 loc * exist * algo * size * imp * 291 292- The spacing characters `~', `^', and tab are currently ignored, 293 see User's Guide (Second Edition) page 2 section 4. 294 loc * exist * algo ** size * imp ** 295 296- Mark and lineup are parsed and ignored, 297 see User's Guide (Second Edition) page 5 section 15. 298 loc ** exist ** algo ** size ** imp ** 299 300- GNU eqn converts some operators to special characters, for example, 301 input HYPHEN-MINUS becomes output \(mi, unless it is part of a 302 quoted word. mandoc(1) only does this when the operator is 303 surrounded by blanks, not when it is part of an unquoted word. 304 Also, check whether there are more such cases (e.g., +?). 305 reported by bentley@ 20 Jun 2017 02:04:29 -0600 306 loc * exist ** algo ** size * imp * 307 308- Primes, opprime, and ' 309 bentley@ Thu, 13 Jul 2017 23:14:20 -0600 310 311--- missing misc features ---------------------------------------------- 312 313- use the default volume headers for sections with suffixes 314 certainly affects man(7); possibly mdoc(7)?; and also groff(1) 315 Alejandro Colomar 21 Aug 2022 316 317- consider whether man(1) fallback code in main.c/fs_*() can find files 318 like man3c/fopen.3c (illumos, Solaris) and man3p/fopen.3p (POSIX) 319 discussed with Robert Mustacchi 21 Sep 2021 10:39:40 -0700 320 loc * exist * algo ** size * imp ** 321 322- let makewhatis(8) follow symbolic links to dirs below READ_ALLOWED_PATH 323 this may be feasible using fts_set(FTS_FOLLOW) 324 mail to sternenseemann 19 Aug 2021 19:11:50 +0200 325 loc * exist ** algo ** size * imp ** 326 327- handle Unicode letters in tags in both HTML and terminal output 328 thread "section headers with diacritics" starting with 329 Mario Blaettermann 24 Mar 2022 18:13:23 +0100 330 loc ** exist * algo * size * imp ** 331 332- -T man does not handle eqn(7) and tbl(7) 333 Stephen Gregoratto 16 Feb 2020 01:28:07 +1100 334 also https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=901636 335 loc ** exist ** algo ** size *** imp ** 336 337- man -ks 1,8 route; kn@ Jul 13, 2018 orally 338 339- italic correction (\/) in PostScript mode 340 Werner LEMBERG on groff at gnu dot org Sun, 10 Nov 2013 12:47:46 341 loc ** exist ** algo * size * imp * 342 343- change the default PAGER to more -Es and use the pager 344 even for apropos title line output; req by bapt@ 345 loc * exist * algo * size * imp *** 346 347- clean up escape sequence handling, creating three classes: 348 (1) fully implemented, or parsed and ignored without loss of content 349 (2) unimplemented, potentially causing loss of content 350 or serious mangling of formatting (e.g. \n) -> ERROR 351 see textproc/mgdiff(1) for nice examples 352 (3) undefined, just output the character -> perhaps WARNING 353 loc *** exist ** algo ** size ** imp *** (parser reorg helps) 354 355- man.conf(5) alias aliasname dirname or just -Mb -Mx -Mp 356 mail to jmc@ Mar 23, 2015 03:53:14PM +0100 357 loc * exist * algo * size * imp ** 358 359- kettenis wants base roff, ms, and me Fri, 1 Jan 2010 22:13:15 +0100 (CET) 360 loc ** exist ** algo ** size *** imp * 361 362--- compatibility checks ----------------------------------------------- 363 364- is .Bk implemented correctly in modern groff? 365 sobrado@ Tue, 19 Apr 2011 22:12:55 +0200 366 367- compare output to Heirloom roff, Solaris roff, and 368 http://repo.or.cz/w/neatroff.git http://litcave.rudi.ir/ 369 370- look at AT&T DWB http://www2.research.att.com/sw/download 371 Carsten Kunze <carsten dot kunze at arcor dot de> has patches 372 Mon, 4 Aug 2014 17:01:28 +0200 373 ported version: https://github.com/n-t-roff/DWB3.3 374 Carsten Kunze Wed, 22 Apr 2015 11:21:43 +0200 375 376- look at pages generated from reStructeredText, e.g. devel/mercurial hg(1) 377 These are a weird mixture of man(7) and custom autogenerated low-level 378 roff stuff. Figure out to what extent we can cope. 379 For details, see http://docutils.sourceforge.net/rst.html 380 noted by stsp@ Sat, 24 Apr 2010 09:17:55 +0200 381 reminded by nicm@ Mon, 3 May 2010 09:52:41 +0100 382 383- look at pages generated from ronn(1) github.com/rtomayko/ronn 384 (based on markdown) 385 386- look at pages generated from Texinfo source by yat2m, e.g. security/gnupg 387 First impression is not that bad. 388 389- look at pages generated by pandoc; see 390 https://github.com/jgm/pandoc/blob/master/src/Text/Pandoc/Writers/Man.hs 391 porting planned by kili@ Thu, 19 Jun 2014 19:46:28 +0200 392 393- check compatibility with Plan9: 394 http://swtch.com/usr/local/plan9/tmac/tmac.an 395 http://swtch.com/plan9port/man/man7/man.html 396 "Anthony J. Bentley" <anthonyjbentley@gmail.com> 28 Dec 2010 21:58:40 -0700 397 398- check compatibility with COHERENT troff: 399 http://www.nesssoftware.com/home/mwc/source.php 400 401- check compatibility with the man(7) formatter 402 https://raw.githubusercontent.com/rofl0r/hardcore-utils/master/man.c 403 404- check compatibility with 405 http://ikiwiki.info/plugins/contrib/mandoc/ 406 https://github.com/schmonz/ikiwiki/compare/mandoc 407 Amitai Schlair Mon, 19 May 2014 14:05:53 -0400 408 409- check compatibility with 410 https://git.sr.ht/~sircmpwn/scdoc 411 412- check features of the Slackware man.conf(5) format 413 Carsten Kunze Wed, 11 Mar 2015 17:57:24 +0100 414 415- look at http://www.snake.net/software/troffcvt/ (troff to HTML) 416 mentioned by Oliver Corff 22 Jan 2021 01:36:49 +0100 417 418 419************************************************************************ 420* formatting issues: ugly output 421************************************************************************ 422 423- revisit empty in-line macros 424 look at the difference between "Em x Em ." and "Sq x Em ." 425 Carsten Kunze Fri, 12 Dec 2014 00:15:41 +0100 426 loc *** exist *** algo *** size * imp ** 427 428- a column list with blank `Ta' cells triggers a spurious 429 start-with-whitespace printing of a newline 430 431- In .Bl -column, .It a<tab>"b<tab>c" 432 shows the quotes in groff, but not in mandoc 433 loc * exist *** algo ** size * imp ** 434 435- In .Bl -column, 436 .It Em Authentication<tab>Key Length 437 ought to render "Key Length" with emphasis, too, 438 see OpenBSD iked.conf(5). 439 reported again Nicolas Joly via wiz@ Wed, 12 Oct 2011 00:20:00 +0200 440 loc * exist *** algo *** size ** imp *** 441 442- empty phrases in .Bl column produce too few blanks 443 try e.g. .Bl -column It Ta Ta 444 reported by millert Fri, 02 Apr 2010 16:13:46 -0400 445 loc * exist *** algo *** size * imp ** 446 447- .%T can have trailing punctuation. Currently, it puts the trailing 448 punctuation into a trailing MDOC_TEXT element inside its own scope. 449 That element should rather be outside its scope, such that the 450 punctuation does not get underlines. This is not trivial to 451 implement because .%T then needs some features of in_line_eoln() - 452 slurp all arguments into one single text element - and one feature 453 of in_line() - put trailing punctuation out of scope. 454 Found in mount_nfs(8) and exports(5), search for "Appendix". 455 loc ** exist ** algo *** size * imp ** 456 457- Trailing punctuation after .%T triggers EOS spacing, at least 458 outside .Rs (eek!). Simply setting ARGSFL_DELIM for .%T is not 459 the right solution, it sends mandoc into an endless loop. 460 reported by Nicolas Joly Sat, 17 Nov 2012 11:49:54 +0100 461 loc * exist ** algo ** size * imp ** 462 463- global variables in the SYNOPSIS of section 3 pages 464 .Vt vs .Vt/.Va vs .Ft/.Va vs .Ft/.Fa ... 465 from kristaps@ Tue, 08 Jun 2010 11:13:32 +0200 466 467- implicit whitespace around inline equations 468 example code: where '$times$' denotes matrix multiplication 469 must not have an HTML line break, nor a blank, before <math> 470 partial solution: html.c {"math", HTML_NLINSIDE | HTML_INDENT}, 471 bentley@ Thu, 13 Jul 2017 19:00:59 -0600 472 473- in enclosures, mandoc sometimes fancies a bogus end of sentence 474 reminded by jmc@ Thu, 23 Sep 2010 18:13:39 +0059 475 loc * exist ** algo *** size * imp *** 476 477- the man(7) single-font macros (e.g. .B) use .itc, 478 so ".B foo\c" followed by "bar" prints "bar" in bold 479 gbranden@ Sun, 5 Jun 2022 18:08:46 -0500 480 481- a line starting with "\fB something" counts as starting with whitespace 482 and triggers a line break; found in audio/normalize-mp3(1) 483 This will become easier once escape sequences are represented 484 by syntax tree nodes. 485 loc ** exist * algo ** size * imp ** 486 487- formatting /usr/local/man/man1/latex2man.1 with groff and mandoc 488 reveals lots of bugs both in groff and mandoc... 489 reported by bentley@ Wed, 22 May 2013 23:49:30 -0600 490 491- Make an underlined blank an underscore rather than a blank in both 492 groff and mandoc terminal output (likely tricky, needs investigation) 493 job@ 21 Jan 2025 18:03:52 +0000 494 495--- PostScript and PDF issues ------------------------------------------ 496 497- PDF output doesn't use a monospaced font for .Bd -literal 498 Example: "mandoc -Tpdf afterboot.8 > output.pdf && pdfviewer output.pdf". 499 Search the text "Routing tables". 500 Also check what PostScript mode does when fixing this. 501 reported by juanfra@ Wed, 04 Jun 2014 21:44:58 +0200 502 instructions from juanfra@ Wed, 11 Jun 2014 02:21:01 +0200 503 add a new <</Type /Font>> block to the PDF files with /BaseFont /Courier 504 and change the /Name from /F0 to the new font (/F5 (?)). 505 re-reported by tb@ Mon, 16 Mar 2015 16:47:21 +0100 506 loc ** exist ** algo ** size * imp ** 507 508- Check for bad line breaks caused by PostScript and PDF using variable- 509 width fonts, for example in .Bl -width "string". The difficulty line 510 below describes a naive solution by simply scaling up widths internally 511 or adding default spacing (like in terminal output). If fixes are 512 needed in width measurements, it might be a bit harder, but likely 513 not unreasonably so. 514 reported by Jan Stary 20 May 2024 10:19:01 +0200 515 loc * exist * algo ** size * imp ** 516 517--- HTML issues -------------------------------------------------------- 518 519- support the idiom .TP .IP .TP for multi-paragraph list item bodies 520 to: Alejandro Colomar Thu, 19 Oct 2023 16:45:21 +0200 521 loc ** exist ** algo ** size ** imp ** 522 523- .Nm without an argument and .Bx cause premature </pre> 524 Nab Sun, 5 Jun 2022 18:30:09 +0200 525 526- .Aq Mt could set and reset "white-space: nowrap"; 527 Check whether other enclosure macros could profit from similar handling, 528 or whether that is covered by Unicode line-breaking classes WJ, ZW, GL, ZWJ. 529 John Gardner 25 Mar 2022 04:44:27 +1100 530 531- make the HTML scaffolding customizable with -O skip=... 532 mail to Oliver Corff 3 Jun 2021 17:28:02 +0200 533 more feedback from Oliver 3 Jun 2021 18:27:56 +0200 534 more feedback from Oliver 3 Jun 2021 23:37:18 +0200 535 would also be useful for 536 https://github.com/gbdev/rgbds-www/blob/master/ 537 maintainer/support/man_postproc.awk 538 539- .Bd -unfilled should not use monospaced font 540 anton@ 4 Mar 2021 08:19:35 +0100 541 loc ** exist * algo * size * imp ** 542 543- HTML formatting of .nf should avoid <br/>, 544 even when input lines start with whitespace, 545 and not close and re-open <pre> on .P 546 my mail to ports@ 27 Jun 2021 16:09:20 +0200 547 reported again by Mohamed Akram 25 Jun 2022 16:28:18 +0000 548 loc ** exist ** algo * size * imp ** 549 550- tbl(7) HTML output does not implement column width specifications 551 reported by Ted Bullock 11 Jan 2022 16:00:44 -0700 552 loc * exist * algo ? size ? imp * 553 554- link from flags in the SYNOPSIS to their descriptions 555 https://github.com/gbdev/rgbds-www/blob/master/ 556 maintainer/support/man_postproc.awk 557 loc * exist * algo ** size * imp * 558 559- get rid of the last handful of style= attributes such that 560 Content-Security-Policy: can be enabled without unsafe-inline 561 suggested by bentley@ Nov 10, 2019 at 06:02:49AM -0700 562 loc * exist * algo * size * imp ** 563 564- .Bf at the beginning of a paragraph inserts a bogus 1ex horizontal 565 space, see for example random(3). Introduced in 566 http://mdocml.bsd.lv/cgi-bin/cvsweb/mdoc_html.c.diff?r1=1.91&r2=1.92 567 reported by deraadt@ Mon, 28 Sep 2015 20:14:13 -0600 (MDT) 568 loc ** exist ** algo ** size * imp * 569 570- jsg on icb, Nov 3, 2014: 571 try to guess Xr in man(7) for hyperlinking 572 and render them with <a class="Xr" href=...> 573 https://github.com/Debian/debiman/issues/15 574 loc * exist * algo ** size ** imp ** 575 576- space characters can end up in href= attributes, for example coming 577 from the first .Xr argument (where they make no sense, but still); 578 does this affect other characters, other source macros...? 579 Jackson Pauls 29 Aug 2017 16:56:27 +0100 580 581- generate <img> tags in HTML 582 idea from florian@ Tue, 7 Apr 2015 00:26:28 +0000 583 may be possible to implement with .Lk img://something.png alt_text 584 585- check https://github.com/trentm/mdocml 586 587--- CSS issues --------------------------------------------------------- 588 589- use flexbox for .Bl-tag instead of the fragile float/clear mechanism 590 John Gardner 25 Mar 2022 04:44:27 +1100 591 592 593************************************************************************ 594* formatting issues: gratuitous differences 595************************************************************************ 596 597- .Fn reopens a new scope after punctuation in mandoc, 598 but closes its scope for good in groff. 599 Do we want to change mandoc or groff? 600 Steffen Nurpmeso Sat, 08 Nov 2014 13:34:59 +0100 601 loc * exist ** algo ** size * imp ** 602 603- Multiple issues with .In below SYNOPSIS; groff behaviour is: 604 text line + .In -> no line break before #include 605 called .In -> no line break before angle bracket 606 .In + .In -> second one gets #include, too 607 two arguments -> line break before second 608 child macro -> line break before child 609 .In + text line -> line break before the text line 610 Evan Silberman Fri, 20 Sep 2024 16:48:19 -0700 611 loc ** exist ** algo * size * imp * 612 613- In .Bl -enum -width 0n, groff continues on the same line after 614 the number, mandoc breaks the line. 615 mail to kristaps@ Mon, 20 Jul 2009 02:21:39 +0200 616 loc * exist ** algo ** size * imp ** 617 618- .Pp between two .It in .Bl -column should produce one, 619 not two blank lines, see e.g. login.conf(5). 620 reported by jmc@ Sun, 17 Apr 2011 14:04:58 +0059 621 reported again by sthen@ Wed, 18 Jan 2012 02:09:39 +0000 (UTC) 622 loc * exist *** algo ** size * imp ** 623 624- If the *first* line after .It is .Pp, break the line right after 625 the tag, do not pad with space characters before breaking. 626 See the description of the a, c, and i commands in sed(1). 627 loc * exist ** algo ** size * imp ** 628 629- If the first line after .It is .D1, do not assert a blank line 630 in between, see for example tmux(1). 631 reported by nicm@ 13 Jan 2011 00:18:57 +0000 632 loc * exist ** algo ** size * imp ** 633 634- Trailing punctuation after .It should trigger EOS spacing. 635 reported by Nicolas Joly Sat, 17 Nov 2012 11:49:54 +0100 636 Probably, this should be fixed somewhere in termp_it_pre(), not sure. 637 loc * exist ** algo ** size * imp ** 638 639- When the -width string contains macros, the macros must be rendered 640 before measuring the width, for example 641 .Bl -tag -width ".Dv message" 642 in magic(5), located in src/usr.bin/file, is the same 643 as -width 7n, not -width 11n. 644 The same applies to .Bl -column column widths; 645 reported again by Nicolas Joly Thu, 1 Mar 2012 13:41:26 +0100 via wiz@ 5 Mar 646 reported again by Franco Fichtner Fri, 27 Sep 2013 21:02:28 +0200 647 reported again by Bruce Evans Fri, 17 Feb 2017 21:22:44 +0100 via bapt@ 648 https://reviews.freebsd.org/D35245 649 even groff_mdoc(7) uses this: Nab Sun, 5 Jun 2022 22:16:37 +0200 650 When implementing this, try to avoid breaking existing manuals, 651 or at least fix them: Jan Stary Sun, 5 Jun 2022 22:48:05 +0200 652 loc *** exist *** algo *** size ** imp *** 653 An easy partial fix has been implemented as skip_leading_dot_word(). 654 655- The \& zero-width character counts as output. 656 That is, when it is alone on a line between two .Pp, 657 we want three blank lines, not two as in mandoc. 658 loc ** exist ** algo ** size * imp ** 659 660- Sequences of multiple man(7) paragraphs (.PP, .IP) interspersed 661 with .ps and .nf/.fi produce execessive blank lines, see libJudy 662 and graphics/dcmtk. The parser reorg may help with this. 663 664- The man(7) .UR macro produces UTF-8 angle brackets in -Tutf8 output mode 665 with groff, but ASCII <> with mandoc 666 Alejandro Colomar Mon, 7 Aug 2023 17:13:29 +0200 Subject: hostname 667 668- trailing whitespace must be ignored even when followed by a font escape, 669 see for example 670 makes 671 \fBdig \fR 672 operate in batch mode 673 in dig(1). 674 loc ** exist ** algo ** size * imp ** 675 676************************************************************************ 677* warning issues 678************************************************************************ 679 680- shorten/simplify error messages for usage errors 681 To: deraadt@ 25 Oct 2020 23:37:01 +0100 682 loc ** exist * algo * size ** imp *** 683 684- warn about \\ and \. in interpretation mode 685 gbranden@, groff issue #62776, 10 Nov 2023 01:57:32 -0500 686 687- warn about output lines exceeding 80 characters 688 Alejandro Colomar Aug 22, 2022 689 not trivial because -T lint does not call any formatter 690 loc *** exist * algo ** size ** imp ** 691 692- warn about duplicate .Sh/.Ss heads 693 gre(4): Rename duplicate sections 20 Apr 2018 15:27:33 +0200 694 loc * exist * algo * size * imp ** 695 696- style message about macros inside .Bd -literal and .Dl, in particular 697 font changing macros like .Cm, .Ar, .Fa (from the mdoclint TODO) 698 699- style message about mismatches between the section number in the 700 file name (if it is known) and the section number in .Dt 701 (from the mdoclint TODO) 702 703- style message about NULL without .Dv (from the mdoclint TODO) 704 705- style message about error constants without .Er (from the mdoclint TODO) 706 707- warn when .Sh or .Ss contain other macros 708 Steffen Nurpmeso, savannah.gnu.org/bugs/index.php?45034 709 loc * exist * algo * size * imp ** 710 711- style message about violations of the convention 712 .An name Aq Mt localpart@domain in AUTHORS (from the mdoclint TODO) 713 714- warn about attempts to call non-callable macros 715 Steffen Nurpmeso Tue, 11 Nov 2014 22:55:16 +0100 716 Note that formatting is inconsistent in groff. 717 .Fn Po prints "Po()", .Ar Sh prints "file ..." and no "Sh". 718 Relatively hard because the relevant code is scattered 719 all over mdoc_macro.c and all subtly different. 720 loc ** exist ** algo ** size ** imp ** 721 722- warn about punctuation - e.g. ',' and ';' - at the beginning 723 of a text line, if it is likely intended to follow the preceding 724 output without intervening whitespace, in particular after a 725 macro line (from the mdoclint TODO) 726 727- report double .TH in man(7) as an ERROR and let the first win 728 kristaps@ 28 Mar 2021 13:30:41 +0200 729 loc * exist * algo * size * imp * 730 731- makewhatis -p complains about language subdirectories: 732 /usr/local/man//ru: Unknown directory part 733 734 735************************************************************************ 736* documentation issues 737************************************************************************ 738 739- mark macros as: page structure domain, manual domain, general text domain 740 is this useful? 741 742- mention /usr/share/misc/mdoc.template in mdoc(7)? 743 744- Is all the content from http://www.std.com/obi/BSD/doc/usd/28.tbl/tbl 745 covered in tbl(7)? 746 747************************************************************************ 748* performance issues 749************************************************************************ 750 751- the PDF file is HUGE: this can be reduced by using relative offsets 752 753************************************************************************ 754* structural issues 755************************************************************************ 756 757- POSIX says in the documentation of sysconf(3) that PATH_MAX 758 is allowed to be so large that it is a bad idea to use it 759 for sizing static buffers. So use dynamic buffers throughout. 760 See the file test-PATH_MAX.c for details. 761 Found by Aaron M. Ucko in the GNU Hurd via Bdale Garbee, 762 https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=829624 763 764- Is it possible to further simplify ENDBODY_SPACE? 765 766- Find better ways to prevent endless loops 767 in roff(7) macro and string expansion. 768 769- make buffers for parsing functions const 770 christos@ via wiz@ Fri, 18 Dec 2015 17:10:01 +0100 771 772- struct mparse refactoring 773 Steffen Nurpmeso Thu, 04 Sep 2014 12:50:00 +0200 774 775************************************************************************ 776* CGI issues 777************************************************************************ 778 779 - Inspect httpd(8) logs on man.openbsd.org and consider 780 whether logging can be improved, where bad syntax comes from, 781 and what needs to be done to get rid of COMPAT_OLDURI. 782 - Enable HTTP compression by detecting gzip encoding and filtering 783 output through libz. 784 - Privilege separation (see OpenSSH). 785 - Enable caching support via HTTP 304 and If-Modified-Since. 786 787************************************************************************ 788* to improve in the groff_mdoc(7) macros 789************************************************************************ 790 791- delete OS release verification from .Dx, .Fx, .Nx, .Ox etc. 792 https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=629161 793 also Branden Robinson 18 Dec 2019 00:59:52 +1100 794 795- Can the distinction between .Vt and .Va be made stricter, 796 recommending .Vt extern char * Ns Va optarg ; ? 797 What about the block macro properties of .Vt in the SYNOPSIS? 798 zeurkous 25 Dec 2019 08:48:36 +0100 799 800- .Cd # arch1, arch2 in section 4 pages: 801 find better way to indicate multiple architectures, maybe: 802 allow .Dt vgafb 4 "macppc sparc64" 803 already shown as "Device Drivers Manual (macppc sparc64)" 804 for apropos, make that "vgafb(4) - macppc # sparc64" instead of "- all" 805 groff can be made to show multiple arches, too, but it is 806 tedious to do the string parsing in roff code... 807 jmc@ 23 Apr 2018 07:24:52 +0100 [man for vgafb(4)...] 808 loc ** exist ** algo * size * imp *** 809 810- use uname(1) to set doc-default-operating-system at install time 811 tobimensch Mon, 1 Dec 2014 00:25:07 +0100 812 813- apostrophe (39), circumflex (94), grave (96), tilde (126) 814 in manuals: \(aq, \(ha, \`, \(ti 815 Re: [Groff] ASCII Minus Sign in man Pages. 816 bentley@ 26 Apr 2017 10:02:06 -0600 817 Do we need to fix existing manuals? 818 Do we need to fix the definition of the mdoc(7) language? 819
