contrib/mandoc/TODO

   1 ************************************************************************
   2 * Official mandoc TODO.
   3 * $Id: TODO,v 1.295 2019/06/11 16:04:36 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 - man -ks 1,8 route; kn@ Jul 13, 2018 orally
 221
 222 - italic correction (\/) in PostScript mode
 223   Werner LEMBERG on groff at gnu dot org  Sun, 10 Nov 2013 12:47:46
 224   loc **  exist **  algo *  size *  imp *
 225
 226 - change the default PAGER to more -Es and use the pager
 227   even for apropos title line output; req by bapt@
 228   loc *  exist *  algo *  size *  imp ***
 229
 230 - clean up escape sequence handling, creating three classes:
 231   (1) fully implemented, or parsed and ignored without loss of content
 232   (2) unimplemented, potentially causing loss of content
 233       or serious mangling of formatting (e.g. \n) -> ERROR
 234       see textproc/mgdiff(1) for nice examples
 235   (3) undefined, just output the character -> perhaps WARNING
 236   loc ***  exist **  algo **  size **  imp *** (parser reorg helps)
 237
 238 - kettenis wants base roff, ms, and me  Fri, 1 Jan 2010 22:13:15 +0100 (CET)
 239   loc **  exist **  algo **  size ***  imp *
 240
 241 --- compatibility checks -----------------------------------------------
 242
 243 - is .Bk implemented correctly in modern groff?
 244   sobrado@  Tue, 19 Apr 2011 22:12:55 +0200
 245
 246 - compare output to Heirloom roff, Solaris roff, and
 247   http://repo.or.cz/w/neatroff.git  http://litcave.rudi.ir/
 248
 249 - look at AT&T DWB http://www2.research.att.com/sw/download
 250   Carsten Kunze <carsten dot kunze at arcor dot de> has patches
 251   Mon, 4 Aug 2014 17:01:28 +0200
 252   ported version: https://github.com/n-t-roff/DWB3.3
 253   Carsten Kunze  Wed, 22 Apr 2015 11:21:43 +0200
 254
 255 - look at pages generated from reStructeredText, e.g. devel/mercurial hg(1)
 256   These are a weird mixture of man(7) and custom autogenerated low-level
 257   roff stuff.  Figure out to what extent we can cope.
 258   For details, see http://docutils.sourceforge.net/rst.html
 259   noted by stsp@  Sat, 24 Apr 2010 09:17:55 +0200
 260   reminded by nicm@  Mon, 3 May 2010 09:52:41 +0100
 261
 262 - look at pages generated from ronn(1) github.com/rtomayko/ronn
 263   (based on markdown)
 264
 265 - look at pages generated from Texinfo source by yat2m, e.g. security/gnupg
 266   First impression is not that bad.
 267
 268 - look at pages generated by pandoc; see
 269   https://github.com/jgm/pandoc/blob/master/src/Text/Pandoc/Writers/Man.hs
 270   porting planned by kili@  Thu, 19 Jun 2014 19:46:28 +0200
 271
 272 - check compatibility with Plan9:
 273   http://swtch.com/usr/local/plan9/tmac/tmac.an
 274   http://swtch.com/plan9port/man/man7/man.html
 275   "Anthony J. Bentley" <anthonyjbentley@gmail.com> 28 Dec 2010 21:58:40 -0700
 276
 277 - check compatibility with COHERENT troff:
 278   http://www.nesssoftware.com/home/mwc/source.php
 279
 280 - check compatibility with the man(7) formatter
 281   https://raw.githubusercontent.com/rofl0r/hardcore-utils/master/man.c
 282
 283 - check compatibility with
 284   http://ikiwiki.info/plugins/contrib/mandoc/
 285   https://github.com/schmonz/ikiwiki/compare/mandoc
 286   Amitai Schlair  Mon, 19 May 2014 14:05:53 -0400
 287
 288 - check compatibility with
 289   https://git.sr.ht/~sircmpwn/scdoc
 290
 291 - check features of the Slackware man.conf(5) format
 292   Carsten Kunze  Wed, 11 Mar 2015 17:57:24 +0100
 293
 294 ************************************************************************
 295 * formatting issues: ugly output
 296 ************************************************************************
 297
 298 - revisit empty in-line macros
 299   look at the difference between "Em x Em ." and "Sq x Em ."
 300   Carsten Kunze  Fri, 12 Dec 2014 00:15:41 +0100
 301   loc *** exist *** algo *** size * imp **
 302
 303 - a column list with blank `Ta' cells triggers a spurious
 304   start-with-whitespace printing of a newline
 305
 306 - In .Bl -column, .It a<tab>"b<tab>c"
 307   shows the quotes in groff, but not in mandoc
 308   loc * exist *** algo ** size * imp **
 309
 310 - In .Bl -column,
 311   .It Em Authentication<tab>Key Length
 312   ought to render "Key Length" with emphasis, too,
 313   see OpenBSD iked.conf(5).
 314   reported again Nicolas Joly via wiz@ Wed, 12 Oct 2011 00:20:00 +0200
 315   loc *  exist ***  algo ***  size **  imp ***
 316
 317 - empty phrases in .Bl column produce too few blanks
 318   try e.g. .Bl -column It Ta Ta
 319   reported by millert Fri, 02 Apr 2010 16:13:46 -0400
 320   loc *  exist ***  algo ***  size *  imp **
 321
 322 - .%T can have trailing punctuation.  Currently, it puts the trailing
 323   punctuation into a trailing MDOC_TEXT element inside its own scope.
 324   That element should rather be outside its scope, such that the
 325   punctuation does not get underlines.  This is not trivial to
 326   implement because .%T then needs some features of in_line_eoln() -
 327   slurp all arguments into one single text element - and one feature
 328   of in_line() - put trailing punctuation out of scope.
 329   Found in mount_nfs(8) and exports(5), search for "Appendix".
 330   loc **  exist **  algo ***  size *  imp **
 331
 332 - Trailing punctuation after .%T triggers EOS spacing, at least
 333   outside .Rs (eek!).  Simply setting ARGSFL_DELIM for .%T is not
 334   the right solution, it sends mandoc into an endless loop.
 335   reported by Nicolas Joly  Sat, 17 Nov 2012 11:49:54 +0100
 336   loc *  exist **  algo **  size *  imp **
 337
 338 - global variables in the SYNOPSIS of section 3 pages
 339   .Vt vs .Vt/.Va vs .Ft/.Va vs .Ft/.Fa ...
 340   from kristaps@  Tue, 08 Jun 2010 11:13:32 +0200
 341
 342 - implicit whitespace around inline equations
 343   example code:  where '$times$' denotes matrix multiplication
 344   must not have an HTML line break, nor a blank, before <math>
 345   partial solution: html.c {"math", HTML_NLINSIDE | HTML_INDENT},
 346   bentley@  Thu, 13 Jul 2017 19:00:59 -0600
 347
 348 - in enclosures, mandoc sometimes fancies a bogus end of sentence
 349   reminded by jmc@  Thu, 23 Sep 2010 18:13:39 +0059
 350   loc *  exist **  algo ***  size *  imp ***
 351
 352 - a line starting with "\fB something" counts as starting with whitespace
 353   and triggers a line break; found in audio/normalize-mp3(1)
 354   This will become easier once escape sequences are represented
 355   by syntax tree nodes.
 356   loc **  exist *  algo **  size *  imp **
 357
 358 - formatting /usr/local/man/man1/latex2man.1 with groff and mandoc
 359   reveals lots of bugs both in groff and mandoc...
 360   reported by bentley@  Wed, 22 May 2013 23:49:30 -0600
 361
 362 --- PostScript and PDF issues ------------------------------------------
 363
 364 - PDF output doesn't use a monospaced font for .Bd -literal
 365   Example: "mandoc -Tpdf afterboot.8 > output.pdf && pdfviewer output.pdf".
 366   Search the text "Routing tables".
 367   Also check what PostScript mode does when fixing this.
 368   reported by juanfra@ Wed, 04 Jun 2014 21:44:58 +0200
 369   instructions from juanfra@  Wed, 11 Jun 2014 02:21:01 +0200
 370     add a new <</Type /Font>> block to the PDF files with /BaseFont /Courier
 371     and change the /Name from /F0 to the new font (/F5 (?)).
 372   re-reported by tb@ Mon, 16 Mar 2015 16:47:21 +0100
 373   loc *  exist **  algo **  size *  imp **
 374
 375 --- HTML issues --------------------------------------------------------
 376
 377 - .Bf at the beginning of a paragraph inserts a bogus 1ex horizontal
 378   space, see for example random(3).  Introduced in
 379   http://mdocml.bsd.lv/cgi-bin/cvsweb/mdoc_html.c.diff?r1=1.91&r2=1.92
 380   reported by deraadt@ Mon, 28 Sep 2015 20:14:13 -0600 (MDT)
 381   loc **  exist **  algo **  size *  imp *
 382
 383 - jsg on icb, Nov 3, 2014:
 384   try to guess Xr in man(7) for hyperlinking
 385   and render them with <a class="Xr" href=...>
 386   https://github.com/Debian/debiman/issues/15
 387   loc *  exist *  algo **  size **  imp **
 388
 389 - The tables used to render the three-part page headers actually force
 390   the width of the <body> to the max-width given for <html>.
 391   Not yet sure how to fix that...
 392   Observed by an Anonymous Coward on undeadly.org:
 393   http://undeadly.org/cgi?action=article&sid=20140925064244&pid=1
 394   loc *  exist *  algo **  size *  imp ***
 395
 396 - generate <img> tags in HTML
 397   idea from florian@  Tue, 7 Apr 2015 00:26:28 +0000
 398   may be possible to implement with .Lk img://something.png alt_text
 399
 400 - check https://github.com/trentm/mdocml
 401
 402 ************************************************************************
 403 * formatting issues: gratuitous differences
 404 ************************************************************************
 405
 406 - .Fn reopens a new scope after punctuation in mandoc,
 407   but closes its scope for good in groff.
 408   Do we want to change mandoc or groff?
 409   Steffen Nurpmeso  Sat, 08 Nov 2014 13:34:59 +0100
 410   loc *  exist **  algo **  size *  imp **
 411
 412 - In .Bl -enum -width 0n, groff continues one the same line after
 413   the number, mandoc breaks the line.
 414   mail to kristaps@  Mon, 20 Jul 2009 02:21:39 +0200
 415   loc *  exist **  algo **  size *  imp **
 416
 417 - .Pp between two .It in .Bl -column should produce one,
 418   not two blank lines, see e.g. login.conf(5).
 419   reported by jmc@  Sun, 17 Apr 2011 14:04:58 +0059
 420   reported again by sthen@  Wed, 18 Jan 2012 02:09:39 +0000 (UTC)
 421   loc *  exist ***  algo **  size *  imp **
 422
 423 - If the *first* line after .It is .Pp, break the line right after
 424   the tag, do not pad with space characters before breaking.
 425   See the description of the a, c, and i commands in sed(1).
 426   loc *  exist **  algo **  size *  imp **
 427
 428 - If the first line after .It is .D1, do not assert a blank line
 429   in between, see for example tmux(1).
 430   reported by nicm@  13 Jan 2011 00:18:57 +0000
 431   loc *  exist **  algo **  size *  imp **
 432
 433 - Trailing punctuation after .It should trigger EOS spacing.
 434   reported by Nicolas Joly  Sat, 17 Nov 2012 11:49:54 +0100
 435   Probably, this should be fixed somewhere in termp_it_pre(), not sure.
 436   loc *  exist **  algo **  size *  imp **
 437
 438 - When the -width string contains macros, the macros must be rendered
 439   before measuring the width, for example
 440     .Bl -tag -width ".Dv message"
 441   in magic(5), located in src/usr.bin/file, is the same
 442   as -width 7n, not -width 11n.
 443   The same applies to .Bl -column column widths;
 444   reported again by Nicolas Joly Thu, 1 Mar 2012 13:41:26 +0100 via wiz@ 5 Mar
 445   reported again by Franco Fichtner Fri, 27 Sep 2013 21:02:28 +0200
 446   reported again by Bruce Evans Fri, 17 Feb 2017 21:22:44 +0100 via bapt@
 447   loc ***  exist ***  algo ***  size **  imp ***
 448   An easy partial fix would be to just skip the first word if it starts
 449   with a dot, including any following white space, when measuring.
 450   loc *  exist *  algo *  size *  imp ***
 451
 452 - The \& zero-width character counts as output.
 453   That is, when it is alone on a line between two .Pp,
 454   we want three blank lines, not two as in mandoc.
 455   loc **  exist **  algo **  size *  imp **
 456
 457 - Sequences of multiple man(7) paragraphs (.PP, .IP) interspersed
 458   with .ps and .nf/.fi produce execessive blank lines, see libJudy
 459   and graphics/dcmtk.  The parser reorg may help with this.
 460
 461 - trailing whitespace must be ignored even when followed by a font escape,
 462   see for example
 463     makes
 464     \fBdig \fR
 465     operate in batch mode
 466   in dig(1).
 467   loc **  exist **  algo **  size *  imp **
 468
 469 ************************************************************************
 470 * warning issues
 471 ************************************************************************
 472
 473 - warn about duplicate .Sh/.Ss heads
 474   gre(4): Rename duplicate sections 20 Apr 2018 15:27:33 +0200
 475   loc *  exist *  algo *  size *  imp **
 476
 477 - style message about macros inside .Bd -literal and .Dl, in particular
 478   font changing macros like .Cm, .Ar, .Fa (from the mdoclint TODO)
 479
 480 - style message about mismatches between the section number in the
 481   file name (if it is known) and the section number in .Dt
 482   (from the mdoclint TODO)
 483
 484 - style message about NULL without .Dv (from the mdoclint TODO)
 485
 486 - style message about error constants without .Er (from the mdoclint TODO)
 487
 488 - warn when .Sh or .Ss contain other macros
 489   Steffen Nurpmeso, savannah.gnu.org/bugs/index.php?45034
 490   loc *  exist *  algo *  size *  imp **
 491
 492 - style message about violations of the convention
 493   .An name Aq Mt localpart@domain in AUTHORS (from the mdoclint TODO)
 494
 495 - warn about attempts to call non-callable macros
 496   Steffen Nurpmeso  Tue, 11 Nov 2014 22:55:16 +0100
 497   Note that formatting is inconsistent in groff.
 498   .Fn Po prints "Po()", .Ar Sh prints "file ..." and no "Sh".
 499   Relatively hard because the relevant code is scattered
 500   all over mdoc_macro.c and all subtly different.
 501   loc **  exist **  algo **  size **  imp **
 502
 503 - warn about punctuation - e.g. ',' and ';' - at the beginning
 504   of a text line, if it is likely intended to follow the preceding
 505   output without intervening whitespace, in particular after a
 506   macro line (from the mdoclint TODO)
 507
 508 - makewhatis -p complains about language subdirectories:
 509   /usr/local/man//ru: Unknown directory part
 510
 511
 512 ************************************************************************
 513 * documentation issues
 514 ************************************************************************
 515
 516 - mark macros as: page structure domain, manual domain, general text domain
 517   is this useful?
 518
 519 - mention /usr/share/misc/mdoc.template in mdoc(7)?
 520
 521 - Is all the content from http://www.std.com/obi/BSD/doc/usd/28.tbl/tbl
 522   covered in tbl(7)?
 523
 524 ************************************************************************
 525 * performance issues
 526 ************************************************************************
 527
 528 - the PDF file is HUGE: this can be reduced by using relative offsets
 529
 530 ************************************************************************
 531 * structural issues
 532 ************************************************************************
 533
 534 - POSIX says in the documentation of sysconf(3) that PATH_MAX
 535   is allowed to be so large that it is a bad idea to use it
 536   for sizing static buffers.  So use dynamic buffers throughout.
 537   See the file test-PATH_MAX.c for details.
 538   Found by Aaron M. Ucko in the GNU Hurd via Bdale Garbee,
 539   https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=829624
 540
 541 - Is it possible to further simplify ENDBODY_SPACE?
 542
 543 - Find better ways to prevent endless loops
 544   in roff(7) macro and string expansion.
 545
 546 - make buffers for parsing functions const
 547   christos@ via wiz@  Fri, 18 Dec 2015 17:10:01 +0100
 548
 549 - struct mparse refactoring
 550   Steffen Nurpmeso  Thu, 04 Sep 2014 12:50:00 +0200
 551
 552 ************************************************************************
 553 * CGI issues
 554 ************************************************************************
 555
 556  - Enable HTTP compression by detecting gzip encoding and filtering
 557    output through libz.
 558  - Privilege separation (see OpenSSH).
 559  - Enable caching support via HTTP 304 and If-Modified-Since.
 560
 561 ************************************************************************
 562 * to improve in the groff_mdoc(7) macros
 563 ************************************************************************
 564
 565 - .Cd # arch1, arch2 in section 4 pages:
 566   find better way to indicate multiple architectures, maybe:
 567   allow .Dt vgafb 4 "macppc sparc64"
 568   already shown as "Device Drivers Manual (macppc sparc64)"
 569   for apropos, make that "vgafb(4) - macppc # sparc64" instead of "- all"
 570   groff can be made to show multiple arches, too, but it is
 571   tedious to do the string parsing in roff code...
 572   jmc@ 23 Apr 2018 07:24:52 +0100 [man for vgafb(4)...]
 573   loc **  exist **  algo *  size *  imp ***
 574
 575 - use uname(1) to set doc-default-operating-system at install time
 576   tobimensch  Mon, 1 Dec 2014 00:25:07 +0100
 577
 578 - apostrophe (39), circumflex (94), grave (96), tilde (126)
 579   in manuals: \(aq, \(ha, \`, \(ti
 580   Re: [Groff] ASCII Minus Sign in man Pages.
 581   bentley@ 26 Apr 2017 10:02:06 -0600
 582   Do we need to fix existing manuals?
 583   Do we need to fix the definition of the mdoc(7) language?