TODO

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