TODO

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