TODO

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