TODO

   1 ************************************************************************
   2 * Official mandoc TODO.
   3 * $Id: TODO,v 1.260 2018/08/10 20:40:45 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 - \*(.T prints the device being used,
  42   see groff_char(7) for an example
  43
  44 - \[charNN], \[charNNN] prints a single-byte codepoint
  45   see groff_char(7) for examples
  46
  47 - .ad (adjust margins)
  48   .ad l -- adjust left margin only (flush left)
  49   .ad r -- adjust right margin only (flush right)
  50   .ad c -- center text on line
  51   .ad b -- adjust both margins (alias: .ad n)
  52   .na   -- temporarily disable adjustment without changing the mode
  53   .ad   -- re-enable adjustment without changing the mode
  54   Adjustment mode is ignored while in no-fill mode (.nf).
  55   loc ***  exist ***  algo **  size **  imp **  (parser reorg would help)
  56
  57 - .fc (field control)
  58   found by naddy@ in xloadimage(1)
  59   loc **  exist ***  algo *  size *  imp *
  60
  61 - .ns (no-space mode) occurs in xine-config(1)
  62   when implementing this, also let .TH set it
  63   reported by brad@  Sat, 15 Jan 2011 15:45:23 -0500
  64   loc ***  exist ***  algo ***  size **  imp *
  65
  66 - .while and .shift
  67   found by jca@ in ratpoison(1)  Sun, 30 Jun 2013 12:01:09 +0200
  68   loc *  exist **  algo **  size **  imp **
  69
  70 - \w'' improve width measurements
  71   would not be very useful without an expression parser, see below
  72   needed for Tcl_NewStringObj(3) via wiz@  Wed, 5 Mar 2014 22:27:43 +0100
  73   loc **  exist ***  algo ***  size *  imp ***
  74
  75 - \\ in high-level macro arguments
  76   Currently, \\ is expanded in two situations:
  77   1) macro and string definition (roff.c setstrn())
  78   2) macro argument parsing (mandoc.c mandoc_getarg())
  79   For user defined macros, the second happens in time because of ROFF_REPARSE.
  80   But for standard high-level macros, it only happens after entering the
  81   high level parsers, which is too late because the code doesn't get
  82   back to roff.c roff_res() from that point.  Because this requires
  83   distinguishing requests, user-defined macros and standard macros
  84   on the roff_res() level, it is hard to solve without the parser reorg.
  85   Found by naddy@ in devel/cutils cobfusc(1)  Mon, 16 Feb 2015 19:10:52 +0100
  86   loc ***  exist ***  algo ***  size **  imp *
  87
  88 - check for missing roff escape sequences, implement those that are
  89   trivial even if not usually appearing in manual pages, gracefully
  90   ignore the non-trivial ones, document what they are supposed to do
  91   and what mandoc does instead
  92   loc *  exist **  algo *  size *  imp *
  93
  94 --- missing mdoc features ----------------------------------------------
  95
  96 - .Bl -column .Xo support is missing
  97   ultimate goal:
  98   restore .Xr and .Dv to
  99   lib/libc/compat-43/sigvec.3
 100   lib/libc/gen/signal.3
 101   lib/libc/sys/sigaction.2
 102   loc *  exist ***  algo ***  size *  imp **
 103
 104 - edge case: decide how to deal with blk_full bad nesting, e.g.
 105   .Sh .Nm .Bk .Nm .Ek .Sh found by jmc@ in ssh-keygen(1)
 106   from jmc@  Wed, 14 Jul 2010 18:10:32 +0100
 107   loc *  exist ***  algo ***  size **  imp **
 108
 109 - .Bd -centered implies -filled, not -unfilled, which is not
 110   easy to implement; it requires code similar to .ce, which
 111   we don't have either.
 112   Besides, groff has bug causing text right *before* .Bd -centered
 113   to be centered as well.
 114   loc ***  exist ***  algo **  size **  imp **  (parser reorg would help)
 115
 116 - .Bd -filled should not be the same as .Bd -ragged, but align both
 117   the left and right margin.  In groff, it is implemented in terms
 118   of .ad b, which we don't have either.  Found in cksum(1).
 119   loc ***  exist ***  algo **  size **  imp **  (parser reorg would help)
 120
 121 - implement blank `Bl -column', such as
 122   .Bl -column
 123   .It foo Ta bar
 124   .El
 125   loc *  exist ***  algo ***  size *  imp *
 126
 127 - explicitly disallow nested `Bl -column', which would clobber internal
 128   flags defined for struct mdoc_macro
 129   loc *  exist *  algo *  size *  imp **
 130
 131 - In .Bl -column .It, the end of the line probably has to be regarded
 132   as an implicit .Ta, if there could be one, see the following mildly
 133   ugly code from login.conf(5):
 134     .Bl -column minpasswordlen program xetcxmotd
 135     .It path Ta path Ta value of Dv _PATH_DEFPATH
 136     .br
 137     Default search path.
 138   reported by Michal Mazurek <akfaew at jasminek dot net>
 139   via jmc@ Thu, 7 Apr 2011 16:00:53 +0059
 140   loc *  exist ***  algo **  size *  imp **
 141
 142 - inside `.Bl -column' phrases, punctuation is handled like normal
 143   text, e.g. `.Bl -column .It Fl x . Ta ...' should give "-x -."
 144
 145 - inside `.Bl -column' phrases, TERMP_IGNDELIM handling by `Pf'
 146   is not safe, e.g. `.Bl -column .It Pf a b .' gives "ab."
 147   but should give "ab ."
 148
 149 - prohibit `Nm' from having non-text HEAD children
 150   (e.g., NetBSD mDNSShared/dns-sd.1)
 151   (mdoc_html.c and mdoc_term.c `Nm' handlers can be slightly simplified)
 152
 153 - support translated section names
 154   e.g. x11/scrotwm scrotwm_es.1:21:2: error: NAME section must be first
 155   that one uses NOMBRE because it is spanish...
 156   deraadt tends to think that section-dependent macro behaviour
 157   is a bad idea in the first place, so this may be irrelevant
 158   loc **  exist **  algo **  size *  imp **
 159
 160 - When there is free text in the SYNOPSIS and that free text contains
 161   the .Nm macro, groff somehow understands to treat the .Nm as an in-line
 162   macro, while mandoc treats it as a block macro and breaks the line.
 163   No idea how the logic for distinguishing in-line and block instances
 164   should be, needs investigation.
 165   uqs@  Thu, 2 Jun 2011 11:03:51 +0200
 166   uqs@  Thu, 2 Jun 2011 11:33:35 +0200
 167   loc *  exist **  algo ***  size *  imp **
 168
 169 --- missing man features -----------------------------------------------
 170
 171 - .SY and .YS,
 172   used by many groff manual pages
 173
 174 - preserve punctuation following .ME,
 175   see ditroff(7) for an example
 176
 177 - .TQ tagged paragraph continuation,
 178   see groff_diff(7) for examples
 179
 180 - groff_www(7) .MTO and .URL
 181   These macros were used by the GNU grep(1) man page.
 182   The groff_www(7) manual page itself uses them, too.
 183   We should probably *not* add them to mandoc.
 184   Just mentioning this here to keep track of the abuse.
 185   Laura Morales <lauretas at mail dot com> 20 Apr 2018 07:33:02 +0200
 186   loc **  exist *  algo *  size **  imp *
 187
 188 --- missing tbl features -----------------------------------------------
 189
 190 - the "s" layout column specifier is used for placement of data
 191   into columns, but ignored during column width calculations
 192   synaptics(4) found by tedu@  Mon, 17 Aug 2015 21:17:42 -0400
 193   loc *  exist **  algo ***  size *  imp **
 194
 195 - vertical centering in cells vertically spanned with ^
 196   pali dot rohar at gmail dot com 16 Jul 2018 13:03:35 +0200
 197   loc *  exist ***  algo ***  size **  imp *
 198
 199 - support .ds requests inside tbl(7) code,
 200   see tbl(1) for an example
 201
 202 - support mdoc(7) and man(7) macros inside tbl(7) code;
 203   probably requires the parser reorg and letting tbl(7)
 204   use roff_node such that macro sets can mix;
 205   informed by bapt@ that FreeBSD needs this: 3 Jan 2015 23:32:23 +0100
 206   loc ***  exist **  algo ***  size **  imp ***
 207
 208 - look at the POSIX manuals in the books/man-pages-posix port,
 209   they use some unsupported tbl(7) features.
 210   loc *  exist **  algo **  size **  imp ***
 211
 212 - look what Joerg Schilling manual pages use
 213   Thu, 19 Mar 2015 18:31:48 +0100
 214
 215 - use Unicode U+2500 to U+256C for table borders
 216   in tbl(7) -Tutf-8 output
 217   suggested by bentley@  Tue, 14 Oct 2014 04:10:55 -0600
 218   loc *  exist **  algo *  size *  imp **
 219
 220 - implement horizontal and vertical alignment in HTML output
 221   pali dot rohar at gmail dot com 16 Jul 2018 13:03:35 +0200
 222   loc *  exist *  algo *  size *  imp ***
 223
 224 - implement cell spanning in HTML output
 225   pali dot rohar at gmail dot com 16 Jul 2018 13:03:35 +0200
 226   loc *  exist *  algo **  size **  imp **
 227
 228 - implement table borders in HTML output
 229   pali dot rohar at gmail dot com 16 Jul 2018 13:03:35 +0200
 230   loc *  exist *  algo **  size **  imp **
 231
 232 --- missing eqn features -----------------------------------------------
 233
 234 - In a matrix, break the output line after each matrix line.
 235   Found in the discussion at CDBUG 2015.
 236   Suggested by Avi Weinstock.
 237   loc *  exist *  algo *  size *  imp **
 238
 239 - The "size" keyword is parsed, but ignored by the formatter.
 240   loc *  exist *  algo *  size *  imp *
 241
 242 - The spacing characters `~', `^', and tab are currently ignored,
 243   see User's Guide (Second Edition) page 2 section 4.
 244   loc *  exist *  algo **  size *  imp **
 245
 246 - Mark and lineup are parsed and ignored,
 247   see User's Guide (Second Edition) page 5 section 15.
 248   loc **  exist **  algo **  size **  imp **
 249
 250 - GNU eqn converts some operators to special characters, for example,
 251   input HYPHEN-MINUS becomes output \(mi, unless it is part of a
 252   quoted word.  mandoc(1) only does this when the operator is
 253   surrounded by blanks, not when it is part of an unquoted word.
 254   Also, check whether there are more such cases (e.g., +?).
 255   reported by bentley@  20 Jun 2017 02:04:29 -0600
 256   loc *  exist **  algo **  size *  imp *
 257
 258 - Primes, opprime, and '
 259   bentley@  Thu, 13 Jul 2017 23:14:20 -0600
 260
 261 --- missing misc features ----------------------------------------------
 262
 263 - man -ks 1,8 route; kn@ Jul 13, 2018 orally
 264
 265 - italic correction (\/) in PostScript mode
 266   Werner LEMBERG on groff at gnu dot org  Sun, 10 Nov 2013 12:47:46
 267   loc **  exist **  algo *  size *  imp *
 268
 269 - change the default PAGER to more -Es and use the pager
 270   even for apropos title line output; req by bapt@
 271   loc *  exist *  algo *  size *  imp ***
 272
 273 - clean up escape sequence handling, creating three classes:
 274   (1) fully implemented, or parsed and ignored without loss of content
 275   (2) unimplemented, potentially causing loss of content
 276       or serious mangling of formatting (e.g. \n) -> ERROR
 277       see textproc/mgdiff(1) for nice examples
 278   (3) undefined, just output the character -> perhaps WARNING
 279   loc ***  exist **  algo **  size **  imp *** (parser reorg helps)
 280
 281 - kettenis wants base roff, ms, and me  Fri, 1 Jan 2010 22:13:15 +0100 (CET)
 282   loc **  exist **  algo **  size ***  imp *
 283
 284 --- compatibility checks -----------------------------------------------
 285
 286 - is .Bk implemented correctly in modern groff?
 287   sobrado@  Tue, 19 Apr 2011 22:12:55 +0200
 288
 289 - compare output to Heirloom roff, Solaris roff, and
 290   http://repo.or.cz/w/neatroff.git  http://litcave.rudi.ir/
 291
 292 - look at AT&T DWB http://www2.research.att.com/sw/download
 293   Carsten Kunze <carsten dot kunze at arcor dot de> has patches
 294   Mon, 4 Aug 2014 17:01:28 +0200
 295   ported version: https://github.com/n-t-roff/DWB3.3
 296   Carsten Kunze  Wed, 22 Apr 2015 11:21:43 +0200
 297
 298 - look at pages generated from reStructeredText, e.g. devel/mercurial hg(1)
 299   These are a weird mixture of man(7) and custom autogenerated low-level
 300   roff stuff.  Figure out to what extent we can cope.
 301   For details, see http://docutils.sourceforge.net/rst.html
 302   noted by stsp@  Sat, 24 Apr 2010 09:17:55 +0200
 303   reminded by nicm@  Mon, 3 May 2010 09:52:41 +0100
 304
 305 - look at pages generated from ronn(1) github.com/rtomayko/ronn
 306   (based on markdown)
 307
 308 - look at pages generated from Texinfo source by yat2m, e.g. security/gnupg
 309   First impression is not that bad.
 310
 311 - look at pages generated by pandoc; see
 312   https://github.com/jgm/pandoc/blob/master/src/Text/Pandoc/Writers/Man.hs
 313   porting planned by kili@  Thu, 19 Jun 2014 19:46:28 +0200
 314
 315 - check compatibility with Plan9:
 316   http://swtch.com/usr/local/plan9/tmac/tmac.an
 317   http://swtch.com/plan9port/man/man7/man.html
 318   "Anthony J. Bentley" <anthonyjbentley@gmail.com> 28 Dec 2010 21:58:40 -0700
 319
 320 - check compatibility with COHERENT troff:
 321   http://www.nesssoftware.com/home/mwc/source.php
 322
 323 - check compatibility with the man(7) formatter
 324   https://raw.githubusercontent.com/rofl0r/hardcore-utils/master/man.c
 325
 326 - check compatibility with
 327   http://ikiwiki.info/plugins/contrib/mandoc/
 328   https://github.com/schmonz/ikiwiki/compare/mandoc
 329   Amitai Schlair  Mon, 19 May 2014 14:05:53 -0400
 330
 331 - check features of the Slackware man.conf(5) format
 332   Carsten Kunze  Wed, 11 Mar 2015 17:57:24 +0100
 333
 334 ************************************************************************
 335 * formatting issues: ugly output
 336 ************************************************************************
 337
 338 - .UR can nest inside .TP,
 339   see roff(7) for examples
 340
 341 - revisit empty in-line macros
 342   look at the difference between "Em x Em ." and "Sq x Em ."
 343   Carsten Kunze  Fri, 12 Dec 2014 00:15:41 +0100
 344   loc *** exist *** algo *** size * imp **
 345
 346 - a column list with blank `Ta' cells triggers a spurious
 347   start-with-whitespace printing of a newline
 348
 349 - In .Bl -column, .It a<tab>"b<tab>c"
 350   shows the quotes in groff, but not in mandoc
 351   loc * exist *** algo ** size * imp **
 352
 353 - In .Bl -column,
 354   .It Em Authentication<tab>Key Length
 355   ought to render "Key Length" with emphasis, too,
 356   see OpenBSD iked.conf(5).
 357   reported again Nicolas Joly via wiz@ Wed, 12 Oct 2011 00:20:00 +0200
 358   loc *  exist ***  algo ***  size **  imp ***
 359
 360 - empty phrases in .Bl column produce too few blanks
 361   try e.g. .Bl -column It Ta Ta
 362   reported by millert Fri, 02 Apr 2010 16:13:46 -0400
 363   loc *  exist ***  algo ***  size *  imp **
 364
 365 - .%T can have trailing punctuation.  Currently, it puts the trailing
 366   punctuation into a trailing MDOC_TEXT element inside its own scope.
 367   That element should rather be outside its scope, such that the
 368   punctuation does not get underlines.  This is not trivial to
 369   implement because .%T then needs some features of in_line_eoln() -
 370   slurp all arguments into one single text element - and one feature
 371   of in_line() - put trailing punctuation out of scope.
 372   Found in mount_nfs(8) and exports(5), search for "Appendix".
 373   loc **  exist **  algo ***  size *  imp **
 374
 375 - Trailing punctuation after .%T triggers EOS spacing, at least
 376   outside .Rs (eek!).  Simply setting ARGSFL_DELIM for .%T is not
 377   the right solution, it sends mandoc into an endless loop.
 378   reported by Nicolas Joly  Sat, 17 Nov 2012 11:49:54 +0100
 379   loc *  exist **  algo **  size *  imp **
 380
 381 - global variables in the SYNOPSIS of section 3 pages
 382   .Vt vs .Vt/.Va vs .Ft/.Va vs .Ft/.Fa ...
 383   from kristaps@  Tue, 08 Jun 2010 11:13:32 +0200
 384
 385 - implicit whitespace around inline equations
 386   example code:  where '$times$' denotes matrix multiplication
 387   must not have an HTML line break, nor a blank, before <math>
 388   partial solution: html.c {"math", HTML_NLINSIDE | HTML_INDENT},
 389   bentley@  Thu, 13 Jul 2017 19:00:59 -0600
 390
 391 - in enclosures, mandoc sometimes fancies a bogus end of sentence
 392   reminded by jmc@  Thu, 23 Sep 2010 18:13:39 +0059
 393   loc *  exist **  algo ***  size *  imp ***
 394
 395 - a line starting with "\fB something" counts as starting with whitespace
 396   and triggers a line break; found in audio/normalize-mp3(1)
 397   loc **  exist *  algo **  size *  imp **
 398
 399 - formatting /usr/local/man/man1/latex2man.1 with groff and mandoc
 400   reveals lots of bugs both in groff and mandoc...
 401   reported by bentley@  Wed, 22 May 2013 23:49:30 -0600
 402
 403 --- PostScript and PDF issues ------------------------------------------
 404
 405 - PDF output doesn't use a monospaced font for .Bd -literal
 406   Example: "mandoc -Tpdf afterboot.8 > output.pdf && pdfviewer output.pdf".
 407   Search the text "Routing tables".
 408   Also check what PostScript mode does when fixing this.
 409   reported by juanfra@ Wed, 04 Jun 2014 21:44:58 +0200
 410   instructions from juanfra@  Wed, 11 Jun 2014 02:21:01 +0200
 411     add a new <</Type /Font>> block to the PDF files with /BaseFont /Courier
 412     and change the /Name from /F0 to the new font (/F5 (?)).
 413   re-reported by tb@ Mon, 16 Mar 2015 16:47:21 +0100
 414   loc *  exist **  algo **  size *  imp **
 415
 416 --- HTML issues --------------------------------------------------------
 417
 418 - wrap Sh and Ss content into <div>
 419   Laura Morales <lauretas at mail dot com> 21 Apr 2018 18:10:48 +0200
 420   (Evaluate whether this is really useful and has no adverse
 421    side effects before implementing; if it is possible,
 422    it does seem cleaner.)
 423   loc **  exist **  algo *  size *  imp ***
 424
 425 - format ".IP *" etc. as <ul> rather than <dl>
 426   https://github.com/Debian/debiman/issues/67
 427   loc ** exist ** algo ** size * imp ***
 428
 429 - .Bf at the beginning of a paragraph inserts a bogus 1ex horizontal
 430   space, see for example random(3).  Introduced in
 431   http://mdocml.bsd.lv/cgi-bin/cvsweb/mdoc_html.c.diff?r1=1.91&r2=1.92
 432   reported by deraadt@ Mon, 28 Sep 2015 20:14:13 -0600 (MDT)
 433   loc **  exist **  algo **  size *  imp *
 434
 435 - jsg on icb, Nov 3, 2014:
 436   try to guess Xr in man(7) for hyperlinking
 437   and render them with <a class="Xr" href=...>
 438   https://github.com/Debian/debiman/issues/15
 439   loc *  exist *  algo **  size **  imp **
 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 - warn about duplicate .Sh/.Ss heads
 526   gre(4): Rename duplicate sections 20 Apr 2018 15:27:33 +0200
 527   loc *  exist *  algo *  size *  imp **
 528
 529 - style message about macros inside .Bd -literal and .Dl, in particular
 530   font changing macros like .Cm, .Ar, .Fa (from the mdoclint TODO)
 531
 532 - style message about mismatches between the section number in the
 533   file name (if it is known) and the section number in .Dt
 534   (from the mdoclint TODO)
 535
 536 - style message about NULL without .Dv (from the mdoclint TODO)
 537
 538 - style message about error constants without .Er (from the mdoclint TODO)
 539
 540 - warn when .Sh or .Ss contain other macros
 541   Steffen Nurpmeso, savannah.gnu.org/bugs/index.php?45034
 542   loc *  exist *  algo *  size *  imp **
 543
 544 - style message about violations of the convention
 545   .An name Aq Mt localpart@domain in AUTHORS (from the mdoclint TODO)
 546
 547 - warn about attempts to call non-callable macros
 548   Steffen Nurpmeso  Tue, 11 Nov 2014 22:55:16 +0100
 549   Note that formatting is inconsistent in groff.
 550   .Fn Po prints "Po()", .Ar Sh prints "file ..." and no "Sh".
 551   Relatively hard because the relevant code is scattered
 552   all over mdoc_macro.c and all subtly different.
 553   loc **  exist **  algo **  size **  imp **
 554
 555 - style message about suspicious uses of - vs. \- vs. \(mi
 556   e.g. -1 is likely wrong (from the mdoclint TODO)
 557
 558 - warn about punctuation - e.g. ',' and ';' - at the beginning
 559   of a text line, if it is likely intended to follow the preceding
 560   output without intervening whitespace, in particular after a
 561   macro line (from the mdoclint TODO)
 562
 563 - mandoc_special does not really check the escape sequence,
 564   but just the overall format
 565   loc **  exist **  algo ***  size **  imp **
 566
 567 - makewhatis -p complains about language subdirectories:
 568   /usr/local/man//ru: Unknown directory part
 569
 570
 571 ************************************************************************
 572 * documentation issues
 573 ************************************************************************
 574
 575 - dashes, hyphens, and minus signs in manual pages
 576   jmc@ Fri, 28 Mar 2014 07:19:27 +0000
 577
 578 - mark macros as: page structure domain, manual domain, general text domain
 579   is this useful?
 580
 581 - mention /usr/share/misc/mdoc.template in mdoc(7)?
 582
 583 - Is all the content from http://www.std.com/obi/BSD/doc/usd/28.tbl/tbl
 584   covered in tbl(7)?
 585
 586 ************************************************************************
 587 * performance issues
 588 ************************************************************************
 589
 590 - the PDF file is HUGE: this can be reduced by using relative offsets
 591
 592 ************************************************************************
 593 * structural issues
 594 ************************************************************************
 595
 596 - POSIX says in the documentation of sysconf(3) that PATH_MAX
 597   is allowed to be so large that it is a bad idea to use it
 598   for sizing static buffers.  So use dynamic buffers throughout.
 599   See the file test-PATH_MAX.c for details.
 600   Found by Aaron M. Ucko in the GNU Hurd via Bdale Garbee,
 601   https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=829624
 602
 603 - We use the input line number at several places to distinguish
 604   same-line from different-line input.  That plainly doesn't work
 605   with user-defined macros, leading to random breakage.
 606
 607 - Is it possible to further simplify ENDBODY_SPACE?
 608
 609 - Find better ways to prevent endless loops
 610   in roff(7) macro and string expansion.
 611
 612 - make buffers for parsing functions const
 613   christos@ via wiz@  Fri, 18 Dec 2015 17:10:01 +0100
 614
 615 - struct mparse refactoring
 616   Steffen Nurpmeso  Thu, 04 Sep 2014 12:50:00 +0200
 617
 618 ************************************************************************
 619 * CGI issues
 620 ************************************************************************
 621
 622  - Enable HTTP compression by detecting gzip encoding and filtering
 623    output through libz.
 624  - Privilege separation (see OpenSSH).
 625  - Enable caching support via HTTP 304 and If-Modified-Since.
 626  - Have Mac OSX systems automatically disable -static compilation of the
 627    CGI: -static isn't supported.
 628
 629 ************************************************************************
 630 * to improve in the groff_mdoc(7) macros
 631 ************************************************************************
 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?