TODO

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