TODO

   1 ************************************************************************
   2 * Official mandoc TODO.
   3 * $Id: TODO,v 1.304 2020/06/24 12:09:29 schwarze Exp $
   4 ************************************************************************
   5
   6 Many 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
  32 Obviously, as the issues have not been solved yet, these annotations
  33 are mere guesses, and some may be wrong.
  34
  35 ************************************************************************
  36 * missing features
  37 ************************************************************************
  38
  39 --- missing roff features ----------------------------------------------
  40
  41 - .ad (adjust margins)
  42   .ad l -- adjust left margin only (flush left)
  43   .ad r -- adjust right margin only (flush right)
  44   .ad c -- center text on line
  45   .ad b -- adjust both margins (alias: .ad n)
  46   .na   -- temporarily disable adjustment without changing the mode
  47   .ad   -- re-enable adjustment without changing the mode
  48   Adjustment mode is ignored while in no-fill mode (.nf).
  49   loc ***  exist ***  algo **  size **  imp **  (parser reorg would help)
  50
  51 - .fc (field control)
  52   found by naddy@ in xloadimage(1)
  53   loc **  exist ***  algo *  size *  imp *
  54
  55 - .ns (no-space mode) occurs in xine-config(1)
  56   when implementing this, also let .TH set it
  57   reported by brad@  Sat, 15 Jan 2011 15:45:23 -0500
  58   loc ***  exist ***  algo ***  size **  imp *
  59
  60 - \w'' improve width measurements
  61   would not be very useful without an expression parser, see below
  62   needed for Tcl_NewStringObj(3) via wiz@  Wed, 5 Mar 2014 22:27:43 +0100
  63   loc **  exist ***  algo ***  size *  imp ***
  64
  65 - .als only works for macros in mandoc, not for user-defined strings.
  66   Also, the "val" field in struct roffkv would have to be replaced
  67   with a pointer to a reference-counted wrapper, and an alias
  68   would have to point to the same wrapper as the original.
  69   .als to undefined does nothing; the alias is not created.
  70   .rm'ing the original leaves the alias to point to the old value.
  71   .de .als .de changes both, but
  72   .de .als .rm .de only changes the new value, not the alias.
  73   Found in groffer(1) version 1.19
  74   Jan Stary 20 Apr 2019 20:16:54 +0200
  75   loc *  exist **  algo **  size **  imp *
  76
  77 - roff string condition comparisons fail when vars contain quotes:
  78   .ds s '
  79   .if '\*s'' \&...
  80   hard to fix because of the basic architecture (string replacement
  81   happens before roff(7) syntax parsing)
  82   Found in groffer(1) version 1.19
  83   Jan Stary 20 Apr 2019 20:16:54 +0200
  84   loc *  exist ***  algo ***  size **  imp *
  85
  86 - mandoc replaces all ASCII control characters except tab and line feed
  87   with '?' during input.  It would be better to replace them with
  88   Unicode escapes in preconv_encode() or somewhere in the vicinity,
  89   such that the already existing better replacement strings show
  90   up in the output.  Emulating groff is not desirable: groff replaces
  91   0x00, 0x0b, and 0x0d to 0x1f with the empty string (bad because
  92   that's easy to overlook for the document author), 0x01 with '.'
  93   (very confusing), and passes through 0x02 to 0x08, 0x0c, and 0x7f
  94   raw (bad because that is insecure output).  Remember that 0x07 may
  95   need special handling because it is sometimes used for certain
  96   delimiters, so it may need handling *after* roff.c rather than before.
  97   reminded by John Gardner 16 Jun 2020 14:26:28 +1000
  98   Actually, more ASCII control characters than just 0x07 may need
  99   later handling because they can for example be used in macro names.
 100   So they may need handling after roff(7) processing.
 101   pointed out by John Gardner 23 Jun 2020 18:28:08 +1000
 102   loc **  exist **  algo **  size **  imp *
 103
 104 --- missing mdoc features ----------------------------------------------
 105
 106 - .Sh and .Ss should be parsed and partially callable, see groff_mdoc(7)
 107   reed at reedmedia dot net Sat, 21 Dec 2019 17:13:07 -0600
 108   loc **  exist **  algo **  size **  imp *
 109
 110 - .Bl -column .Xo support is missing
 111   ultimate goal:
 112   restore .Xr and .Dv to
 113   lib/libc/compat-43/sigvec.3
 114   lib/libc/gen/signal.3
 115   lib/libc/sys/sigaction.2
 116   loc *  exist ***  algo ***  size *  imp **
 117
 118 - edge case: decide how to deal with blk_full bad nesting, e.g.
 119   .Sh .Nm .Bk .Nm .Ek .Sh found by jmc@ in ssh-keygen(1)
 120   from jmc@  Wed, 14 Jul 2010 18:10:32 +0100
 121   loc *  exist ***  algo ***  size **  imp **
 122
 123 - .Bd -filled should not be the same as .Bd -ragged, but align both
 124   the left and right margin.  In groff, it is implemented in terms
 125   of .ad b, which we don't have either.  Found in cksum(1).
 126   loc ***  exist ***  algo **  size **  imp **  (parser reorg would help)
 127
 128 - implement blank `Bl -column', such as
 129   .Bl -column
 130   .It foo Ta bar
 131   .El
 132   loc *  exist ***  algo ***  size *  imp *
 133
 134 - explicitly disallow nested `Bl -column', which would clobber internal
 135   flags defined for struct mdoc_macro
 136   loc *  exist *  algo *  size *  imp **
 137
 138 - In .Bl -column .It, the end of the line probably has to be regarded
 139   as an implicit .Ta, if there could be one, see the following mildly
 140   ugly code from login.conf(5):
 141     .Bl -column minpasswordlen program xetcxmotd
 142     .It path Ta path Ta value of Dv _PATH_DEFPATH
 143     .br
 144     Default search path.
 145   reported by Michal Mazurek <akfaew at jasminek dot net>
 146   via jmc@ Thu, 7 Apr 2011 16:00:53 +0059
 147   loc *  exist ***  algo **  size *  imp **
 148
 149 - inside `.Bl -column' phrases, punctuation is handled like normal
 150   text, e.g. `.Bl -column .It Fl x . Ta ...' should give "-x -."
 151
 152 - inside `.Bl -column' phrases, TERMP_IGNDELIM handling by `Pf'
 153   is not safe, e.g. `.Bl -column .It Pf a b .' gives "ab."
 154   but should give "ab ."
 155
 156 - prohibit `Nm' from having non-text HEAD children
 157   (e.g., NetBSD mDNSShared/dns-sd.1)
 158   (mdoc_html.c and mdoc_term.c `Nm' handlers can be slightly simplified)
 159
 160 - support translated section names
 161   e.g. x11/scrotwm scrotwm_es.1:21:2: error: NAME section must be first
 162   that one uses NOMBRE because it is spanish...
 163   deraadt tends to think that section-dependent macro behaviour
 164   is a bad idea in the first place, so this may be irrelevant
 165   loc **  exist **  algo **  size *  imp **
 166
 167 - When there is free text in the SYNOPSIS and that free text contains
 168   the .Nm macro, groff somehow understands to treat the .Nm as an in-line
 169   macro, while mandoc treats it as a block macro and breaks the line.
 170   No idea how the logic for distinguishing in-line and block instances
 171   should be, needs investigation.
 172   uqs@  Thu, 2 Jun 2011 11:03:51 +0200
 173   uqs@  Thu, 2 Jun 2011 11:33:35 +0200
 174   loc *  exist **  algo ***  size *  imp **
 175
 176 --- missing man features -----------------------------------------------
 177
 178 - groff_www(7) .MTO and .URL
 179   These macros were used by the GNU grep(1) man page.
 180   The groff_www(7) manual page itself uses them, too.
 181   We should probably *not* add them to mandoc.
 182   Just mentioning this here to keep track of the abuse.
 183   Laura Morales <lauretas at mail dot com> 20 Apr 2018 07:33:02 +0200
 184   loc **  exist *  algo *  size **  imp *
 185
 186 --- missing tbl features -----------------------------------------------
 187
 188 - vertical centering in cells vertically spanned with ^
 189   pali dot rohar at gmail dot com 16 Jul 2018 13:03:35 +0200
 190   loc *  exist ***  algo ***  size **  imp *
 191
 192 - support mdoc(7) and man(7) macros inside tbl(7) code;
 193   probably requires the parser reorg and letting tbl(7)
 194   use roff_node such that macro sets can mix;
 195   informed by bapt@ that FreeBSD needs this: 3 Jan 2015 23:32:23 +0100
 196   loc ***  exist **  algo ***  size **  imp ***
 197
 198 - look at the POSIX manuals in the books/man-pages-posix port,
 199   they use some unsupported tbl(7) features, mostly macros in tbl(7).
 200   loc *  exist **  algo **  size **  imp ***
 201
 202 - look what Joerg Schilling manual pages use
 203   Thu, 19 Mar 2015 18:31:48 +0100
 204
 205 --- missing eqn features -----------------------------------------------
 206
 207 - In a matrix, break the output line after each matrix line.
 208   Found in the discussion at CDBUG 2015.  Suggested by Avi Weinstock.
 209   This may not be the ideal solution after all: eqn(7) matrices
 210   are lists of columns, so Avi's proposal would show each *column*
 211   on its own *line*, which is likely to cause confusion.
 212   A better solution, but much harder to implement, would be to
 213   actually show the coordinates of column vectors on different
 214   terminal output lines, using the clumnated output facilities
 215   developed for .Bl -tag, .Bl -column, and also used for tbl(7).
 216   loc *  exist *  algo **  size **  imp **
 217
 218 - The "size" keyword is parsed, but ignored by the formatter.
 219   loc *  exist *  algo *  size *  imp *
 220
 221 - The spacing characters `~', `^', and tab are currently ignored,
 222   see User's Guide (Second Edition) page 2 section 4.
 223   loc *  exist *  algo **  size *  imp **
 224
 225 - Mark and lineup are parsed and ignored,
 226   see User's Guide (Second Edition) page 5 section 15.
 227   loc **  exist **  algo **  size **  imp **
 228
 229 - GNU eqn converts some operators to special characters, for example,
 230   input HYPHEN-MINUS becomes output \(mi, unless it is part of a
 231   quoted word.  mandoc(1) only does this when the operator is
 232   surrounded by blanks, not when it is part of an unquoted word.
 233   Also, check whether there are more such cases (e.g., +?).
 234   reported by bentley@  20 Jun 2017 02:04:29 -0600
 235   loc *  exist **  algo **  size *  imp *
 236
 237 - Primes, opprime, and '
 238   bentley@  Thu, 13 Jul 2017 23:14:20 -0600
 239
 240 --- missing misc features ----------------------------------------------
 241
 242 - -T man does not handle eqn(7) and tbl(7)
 243   Stephen Gregoratto 16 Feb 2020 01:28:07 +1100
 244   loc **  exist **  algo **  size ***  imp **
 245
 246 - man -ks 1,8 route; kn@ Jul 13, 2018 orally
 247
 248 - italic correction (\/) in PostScript mode
 249   Werner LEMBERG on groff at gnu dot org  Sun, 10 Nov 2013 12:47:46
 250   loc **  exist **  algo *  size *  imp *
 251
 252 - change the default PAGER to more -Es and use the pager
 253   even for apropos title line output; req by bapt@
 254   loc *  exist *  algo *  size *  imp ***
 255
 256 - clean up escape sequence handling, creating three classes:
 257   (1) fully implemented, or parsed and ignored without loss of content
 258   (2) unimplemented, potentially causing loss of content
 259       or serious mangling of formatting (e.g. \n) -> ERROR
 260       see textproc/mgdiff(1) for nice examples
 261   (3) undefined, just output the character -> perhaps WARNING
 262   loc ***  exist **  algo **  size **  imp *** (parser reorg helps)
 263
 264 - kettenis wants base roff, ms, and me  Fri, 1 Jan 2010 22:13:15 +0100 (CET)
 265   loc **  exist **  algo **  size ***  imp *
 266
 267 --- compatibility checks -----------------------------------------------
 268
 269 - is .Bk implemented correctly in modern groff?
 270   sobrado@  Tue, 19 Apr 2011 22:12:55 +0200
 271
 272 - compare output to Heirloom roff, Solaris roff, and
 273   http://repo.or.cz/w/neatroff.git  http://litcave.rudi.ir/
 274
 275 - look at AT&T DWB http://www2.research.att.com/sw/download
 276   Carsten Kunze <carsten dot kunze at arcor dot de> has patches
 277   Mon, 4 Aug 2014 17:01:28 +0200
 278   ported version: https://github.com/n-t-roff/DWB3.3
 279   Carsten Kunze  Wed, 22 Apr 2015 11:21:43 +0200
 280
 281 - look at pages generated from reStructeredText, e.g. devel/mercurial hg(1)
 282   These are a weird mixture of man(7) and custom autogenerated low-level
 283   roff stuff.  Figure out to what extent we can cope.
 284   For details, see http://docutils.sourceforge.net/rst.html
 285   noted by stsp@  Sat, 24 Apr 2010 09:17:55 +0200
 286   reminded by nicm@  Mon, 3 May 2010 09:52:41 +0100
 287
 288 - look at pages generated from ronn(1) github.com/rtomayko/ronn
 289   (based on markdown)
 290
 291 - look at pages generated from Texinfo source by yat2m, e.g. security/gnupg
 292   First impression is not that bad.
 293
 294 - look at pages generated by pandoc; see
 295   https://github.com/jgm/pandoc/blob/master/src/Text/Pandoc/Writers/Man.hs
 296   porting planned by kili@  Thu, 19 Jun 2014 19:46:28 +0200
 297
 298 - check compatibility with Plan9:
 299   http://swtch.com/usr/local/plan9/tmac/tmac.an
 300   http://swtch.com/plan9port/man/man7/man.html
 301   "Anthony J. Bentley" <anthonyjbentley@gmail.com> 28 Dec 2010 21:58:40 -0700
 302
 303 - check compatibility with COHERENT troff:
 304   http://www.nesssoftware.com/home/mwc/source.php
 305
 306 - check compatibility with the man(7) formatter
 307   https://raw.githubusercontent.com/rofl0r/hardcore-utils/master/man.c
 308
 309 - check compatibility with
 310   http://ikiwiki.info/plugins/contrib/mandoc/
 311   https://github.com/schmonz/ikiwiki/compare/mandoc
 312   Amitai Schlair  Mon, 19 May 2014 14:05:53 -0400
 313
 314 - check compatibility with
 315   https://git.sr.ht/~sircmpwn/scdoc
 316
 317 - check features of the Slackware man.conf(5) format
 318   Carsten Kunze  Wed, 11 Mar 2015 17:57:24 +0100
 319
 320 ************************************************************************
 321 * formatting issues: ugly output
 322 ************************************************************************
 323
 324 - revisit empty in-line macros
 325   look at the difference between "Em x Em ." and "Sq x Em ."
 326   Carsten Kunze  Fri, 12 Dec 2014 00:15:41 +0100
 327   loc *** exist *** algo *** size * imp **
 328
 329 - a column list with blank `Ta' cells triggers a spurious
 330   start-with-whitespace printing of a newline
 331
 332 - In .Bl -column, .It a<tab>"b<tab>c"
 333   shows the quotes in groff, but not in mandoc
 334   loc * exist *** algo ** size * imp **
 335
 336 - In .Bl -column,
 337   .It Em Authentication<tab>Key Length
 338   ought to render "Key Length" with emphasis, too,
 339   see OpenBSD iked.conf(5).
 340   reported again Nicolas Joly via wiz@ Wed, 12 Oct 2011 00:20:00 +0200
 341   loc *  exist ***  algo ***  size **  imp ***
 342
 343 - empty phrases in .Bl column produce too few blanks
 344   try e.g. .Bl -column It Ta Ta
 345   reported by millert Fri, 02 Apr 2010 16:13:46 -0400
 346   loc *  exist ***  algo ***  size *  imp **
 347
 348 - .%T can have trailing punctuation.  Currently, it puts the trailing
 349   punctuation into a trailing MDOC_TEXT element inside its own scope.
 350   That element should rather be outside its scope, such that the
 351   punctuation does not get underlines.  This is not trivial to
 352   implement because .%T then needs some features of in_line_eoln() -
 353   slurp all arguments into one single text element - and one feature
 354   of in_line() - put trailing punctuation out of scope.
 355   Found in mount_nfs(8) and exports(5), search for "Appendix".
 356   loc **  exist **  algo ***  size *  imp **
 357
 358 - Trailing punctuation after .%T triggers EOS spacing, at least
 359   outside .Rs (eek!).  Simply setting ARGSFL_DELIM for .%T is not
 360   the right solution, it sends mandoc into an endless loop.
 361   reported by Nicolas Joly  Sat, 17 Nov 2012 11:49:54 +0100
 362   loc *  exist **  algo **  size *  imp **
 363
 364 - global variables in the SYNOPSIS of section 3 pages
 365   .Vt vs .Vt/.Va vs .Ft/.Va vs .Ft/.Fa ...
 366   from kristaps@  Tue, 08 Jun 2010 11:13:32 +0200
 367
 368 - implicit whitespace around inline equations
 369   example code:  where '$times$' denotes matrix multiplication
 370   must not have an HTML line break, nor a blank, before <math>
 371   partial solution: html.c {"math", HTML_NLINSIDE | HTML_INDENT},
 372   bentley@  Thu, 13 Jul 2017 19:00:59 -0600
 373
 374 - in enclosures, mandoc sometimes fancies a bogus end of sentence
 375   reminded by jmc@  Thu, 23 Sep 2010 18:13:39 +0059
 376   loc *  exist **  algo ***  size *  imp ***
 377
 378 - a line starting with "\fB something" counts as starting with whitespace
 379   and triggers a line break; found in audio/normalize-mp3(1)
 380   This will become easier once escape sequences are represented
 381   by syntax tree nodes.
 382   loc **  exist *  algo **  size *  imp **
 383
 384 - formatting /usr/local/man/man1/latex2man.1 with groff and mandoc
 385   reveals lots of bugs both in groff and mandoc...
 386   reported by bentley@  Wed, 22 May 2013 23:49:30 -0600
 387
 388 --- PostScript and PDF issues ------------------------------------------
 389
 390 - PDF output doesn't use a monospaced font for .Bd -literal
 391   Example: "mandoc -Tpdf afterboot.8 > output.pdf && pdfviewer output.pdf".
 392   Search the text "Routing tables".
 393   Also check what PostScript mode does when fixing this.
 394   reported by juanfra@ Wed, 04 Jun 2014 21:44:58 +0200
 395   instructions from juanfra@  Wed, 11 Jun 2014 02:21:01 +0200
 396     add a new <</Type /Font>> block to the PDF files with /BaseFont /Courier
 397     and change the /Name from /F0 to the new font (/F5 (?)).
 398   re-reported by tb@ Mon, 16 Mar 2015 16:47:21 +0100
 399   loc *  exist **  algo **  size *  imp **
 400
 401 --- HTML issues --------------------------------------------------------
 402
 403 - get rid of the last handful of style= attributes such that
 404   Content-Security-Policy: can be enabled without unsafe-inline
 405   suggested by bentley@  Nov 10, 2019 at 06:02:49AM -0700
 406   loc *  exist *  algo *  size *  imp **
 407
 408 - .Bf at the beginning of a paragraph inserts a bogus 1ex horizontal
 409   space, see for example random(3).  Introduced in
 410   http://mdocml.bsd.lv/cgi-bin/cvsweb/mdoc_html.c.diff?r1=1.91&r2=1.92
 411   reported by deraadt@ Mon, 28 Sep 2015 20:14:13 -0600 (MDT)
 412   loc **  exist **  algo **  size *  imp *
 413
 414 - jsg on icb, Nov 3, 2014:
 415   try to guess Xr in man(7) for hyperlinking
 416   and render them with <a class="Xr" href=...>
 417   https://github.com/Debian/debiman/issues/15
 418   loc *  exist *  algo **  size **  imp **
 419
 420 - space characters can end up in href= attributes, for example coming
 421   from the first .Xr argument (where they make no sense, but still);
 422   does this affect other characters, other source macros...?
 423   Jackson Pauls  29 Aug 2017 16:56:27 +0100
 424
 425 - The tables used to render the three-part page headers actually force
 426   the width of the <body> to the max-width given for <html>.
 427   Not yet sure how to fix that...
 428   Observed by an Anonymous Coward on undeadly.org:
 429   http://undeadly.org/cgi?action=article&sid=20140925064244&pid=1
 430   loc *  exist *  algo **  size *  imp ***
 431
 432 - generate <img> tags in HTML
 433   idea from florian@  Tue, 7 Apr 2015 00:26:28 +0000
 434   may be possible to implement with .Lk img://something.png alt_text
 435
 436 - check https://github.com/trentm/mdocml
 437
 438 ************************************************************************
 439 * formatting issues: gratuitous differences
 440 ************************************************************************
 441
 442 - .Fn reopens a new scope after punctuation in mandoc,
 443   but closes its scope for good in groff.
 444   Do we want to change mandoc or groff?
 445   Steffen Nurpmeso  Sat, 08 Nov 2014 13:34:59 +0100
 446   loc *  exist **  algo **  size *  imp **
 447
 448 - In .Bl -enum -width 0n, groff continues one the same line after
 449   the number, mandoc breaks the line.
 450   mail to kristaps@  Mon, 20 Jul 2009 02:21:39 +0200
 451   loc *  exist **  algo **  size *  imp **
 452
 453 - .Pp between two .It in .Bl -column should produce one,
 454   not two blank lines, see e.g. login.conf(5).
 455   reported by jmc@  Sun, 17 Apr 2011 14:04:58 +0059
 456   reported again by sthen@  Wed, 18 Jan 2012 02:09:39 +0000 (UTC)
 457   loc *  exist ***  algo **  size *  imp **
 458
 459 - If the *first* line after .It is .Pp, break the line right after
 460   the tag, do not pad with space characters before breaking.
 461   See the description of the a, c, and i commands in sed(1).
 462   loc *  exist **  algo **  size *  imp **
 463
 464 - If the first line after .It is .D1, do not assert a blank line
 465   in between, see for example tmux(1).
 466   reported by nicm@  13 Jan 2011 00:18:57 +0000
 467   loc *  exist **  algo **  size *  imp **
 468
 469 - Trailing punctuation after .It should trigger EOS spacing.
 470   reported by Nicolas Joly  Sat, 17 Nov 2012 11:49:54 +0100
 471   Probably, this should be fixed somewhere in termp_it_pre(), not sure.
 472   loc *  exist **  algo **  size *  imp **
 473
 474 - When the -width string contains macros, the macros must be rendered
 475   before measuring the width, for example
 476     .Bl -tag -width ".Dv message"
 477   in magic(5), located in src/usr.bin/file, is the same
 478   as -width 7n, not -width 11n.
 479   The same applies to .Bl -column column widths;
 480   reported again by Nicolas Joly Thu, 1 Mar 2012 13:41:26 +0100 via wiz@ 5 Mar
 481   reported again by Franco Fichtner Fri, 27 Sep 2013 21:02:28 +0200
 482   reported again by Bruce Evans Fri, 17 Feb 2017 21:22:44 +0100 via bapt@
 483   loc ***  exist ***  algo ***  size **  imp ***
 484   An easy partial fix would be to just skip the first word if it starts
 485   with a dot, including any following white space, when measuring.
 486   loc *  exist *  algo *  size *  imp ***
 487
 488 - The \& zero-width character counts as output.
 489   That is, when it is alone on a line between two .Pp,
 490   we want three blank lines, not two as in mandoc.
 491   loc **  exist **  algo **  size *  imp **
 492
 493 - Sequences of multiple man(7) paragraphs (.PP, .IP) interspersed
 494   with .ps and .nf/.fi produce execessive blank lines, see libJudy
 495   and graphics/dcmtk.  The parser reorg may help with this.
 496
 497 - trailing whitespace must be ignored even when followed by a font escape,
 498   see for example
 499     makes
 500     \fBdig \fR
 501     operate in batch mode
 502   in dig(1).
 503   loc **  exist **  algo **  size *  imp **
 504
 505 ************************************************************************
 506 * warning issues
 507 ************************************************************************
 508
 509 - warn about duplicate .Sh/.Ss heads
 510   gre(4): Rename duplicate sections 20 Apr 2018 15:27:33 +0200
 511   loc *  exist *  algo *  size *  imp **
 512
 513 - style message about macros inside .Bd -literal and .Dl, in particular
 514   font changing macros like .Cm, .Ar, .Fa (from the mdoclint TODO)
 515
 516 - style message about mismatches between the section number in the
 517   file name (if it is known) and the section number in .Dt
 518   (from the mdoclint TODO)
 519
 520 - style message about NULL without .Dv (from the mdoclint TODO)
 521
 522 - style message about error constants without .Er (from the mdoclint TODO)
 523
 524 - warn when .Sh or .Ss contain other macros
 525   Steffen Nurpmeso, savannah.gnu.org/bugs/index.php?45034
 526   loc *  exist *  algo *  size *  imp **
 527
 528 - style message about violations of the convention
 529   .An name Aq Mt localpart@domain in AUTHORS (from the mdoclint TODO)
 530
 531 - warn about attempts to call non-callable macros
 532   Steffen Nurpmeso  Tue, 11 Nov 2014 22:55:16 +0100
 533   Note that formatting is inconsistent in groff.
 534   .Fn Po prints "Po()", .Ar Sh prints "file ..." and no "Sh".
 535   Relatively hard because the relevant code is scattered
 536   all over mdoc_macro.c and all subtly different.
 537   loc **  exist **  algo **  size **  imp **
 538
 539 - warn about punctuation - e.g. ',' and ';' - at the beginning
 540   of a text line, if it is likely intended to follow the preceding
 541   output without intervening whitespace, in particular after a
 542   macro line (from the mdoclint TODO)
 543
 544 - makewhatis -p complains about language subdirectories:
 545   /usr/local/man//ru: Unknown directory part
 546
 547
 548 ************************************************************************
 549 * documentation issues
 550 ************************************************************************
 551
 552 - mark macros as: page structure domain, manual domain, general text domain
 553   is this useful?
 554
 555 - mention /usr/share/misc/mdoc.template in mdoc(7)?
 556
 557 - Is all the content from http://www.std.com/obi/BSD/doc/usd/28.tbl/tbl
 558   covered in tbl(7)?
 559
 560 ************************************************************************
 561 * performance issues
 562 ************************************************************************
 563
 564 - the PDF file is HUGE: this can be reduced by using relative offsets
 565
 566 ************************************************************************
 567 * structural issues
 568 ************************************************************************
 569
 570 - POSIX says in the documentation of sysconf(3) that PATH_MAX
 571   is allowed to be so large that it is a bad idea to use it
 572   for sizing static buffers.  So use dynamic buffers throughout.
 573   See the file test-PATH_MAX.c for details.
 574   Found by Aaron M. Ucko in the GNU Hurd via Bdale Garbee,
 575   https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=829624
 576
 577 - Is it possible to further simplify ENDBODY_SPACE?
 578
 579 - Find better ways to prevent endless loops
 580   in roff(7) macro and string expansion.
 581
 582 - make buffers for parsing functions const
 583   christos@ via wiz@  Fri, 18 Dec 2015 17:10:01 +0100
 584
 585 - struct mparse refactoring
 586   Steffen Nurpmeso  Thu, 04 Sep 2014 12:50:00 +0200
 587
 588 ************************************************************************
 589 * CGI issues
 590 ************************************************************************
 591
 592  - Inspect httpd(8) logs on man.openbsd.org and consider
 593    whether logging can be improved, where bad syntax comes from,
 594    and what needs to be done to get rid of COMPAT_OLDURI.
 595  - Enable HTTP compression by detecting gzip encoding and filtering
 596    output through libz.
 597  - Privilege separation (see OpenSSH).
 598  - Enable caching support via HTTP 304 and If-Modified-Since.
 599
 600 ************************************************************************
 601 * to improve in the groff_mdoc(7) macros
 602 ************************************************************************
 603
 604 - delete OS release verification from .Dx, .Fx, .Nx, .Ox etc.
 605   https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=629161
 606   also Branden Robinson 18 Dec 2019 00:59:52 +1100
 607
 608 - Can the distinction between .Vt and .Va be made stricter,
 609   recommending .Vt extern char * Ns Va optarg ; ?
 610   What about the block macro properties of .Vt in the SYNOPSIS?
 611   zeurkous 25 Dec 2019 08:48:36 +0100
 612
 613 - .Cd # arch1, arch2 in section 4 pages:
 614   find better way to indicate multiple architectures, maybe:
 615   allow .Dt vgafb 4 "macppc sparc64"
 616   already shown as "Device Drivers Manual (macppc sparc64)"
 617   for apropos, make that "vgafb(4) - macppc # sparc64" instead of "- all"
 618   groff can be made to show multiple arches, too, but it is
 619   tedious to do the string parsing in roff code...
 620   jmc@ 23 Apr 2018 07:24:52 +0100 [man for vgafb(4)...]
 621   loc **  exist **  algo *  size *  imp ***
 622
 623 - use uname(1) to set doc-default-operating-system at install time
 624   tobimensch  Mon, 1 Dec 2014 00:25:07 +0100
 625
 626 - apostrophe (39), circumflex (94), grave (96), tilde (126)
 627   in manuals: \(aq, \(ha, \`, \(ti
 628   Re: [Groff] ASCII Minus Sign in man Pages.
 629   bentley@ 26 Apr 2017 10:02:06 -0600
 630   Do we need to fix existing manuals?
 631   Do we need to fix the definition of the mdoc(7) language?