TODO

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