TODO

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