TODO

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