TODO

   1 ************************************************************************
   2 * Official mandoc TODO.
   3 * $Id: TODO,v 1.74 2011/01/09 18:45:46 schwarze Exp $
   4 ************************************************************************
   5
   6 ************************************************************************
   7 * parser bugs
   8 ************************************************************************
   9
  10 - the roff parser doesn't tolerate additional characters between
  11   a macro and the \} terminating a conditional block, e.g.
  12   .if n \{
  13   .br \}
  14   reported by ulrich spoerlein  Tue, 19 Oct 2010 20:39:50 +0200
  15
  16 ************************************************************************
  17 * formatter bugs
  18 ************************************************************************
  19
  20 - in literal mode, the man(7) -Tascii formatter
  21   breaks the line between macro arguments,
  22   e.g. ".B #include <libintl.h>" in gettext(3)
  23
  24 ************************************************************************
  25 * missing features
  26 ************************************************************************
  27
  28 - pod2man expects `tr' to be implemented for \*(-- to work
  29
  30 - fix bad block nesting involving multiple identical explicit blocks
  31   see the OpenBSD mdoc_macro.c 1.47 commit message
  32
  33 - .Bl -column .Xo support is missing
  34   ultimate goal:
  35   restore .Xr and .Dv to
  36   lib/libc/compat-43/sigvec.3
  37   lib/libc/gen/signal.3
  38   lib/libc/sys/sigaction.2
  39
  40 - edge case: decide how to deal with blk_full bad nesting, e.g.
  41   .Sh .Nm .Bk .Nm .Ek .Sh found by jmc@ in ssh-keygen(1)
  42   from jmc@  Wed, 14 Jul 2010 18:10:32 +0100
  43
  44 - \\ is now implemented correctly
  45   * when defining strings and macros using .ds and .de
  46   * when parsing roff(7) and man(7) macro arguments
  47   It does not yet work in mdoc(7) macro arguments
  48   because libmdoc does not yet use mandoc_getarg().
  49   Also check what happens in plain text, it must be identical to \e.
  50
  51 - implement basic non-parametric .de to support e.g. sox(1)
  52   reported by naddy@ Sat, 16 Oct 2010 23:51:57 +0200
  53   *** sox(1) still doesn't work, tbl(1) errors need investigation
  54
  55 - clean up escape sequence handling, creating three classes:
  56   (1) fully implemented, or parsed and ignored without loss of content
  57   (2) unimplemented, potentially causing loss of content
  58       or serious mangling of formatting (e.g. \n) -> ERROR
  59       see textproc/mgdiff(1) for nice examples
  60   (3) undefined, just output the character -> perhaps WARNING
  61
  62 - look at pages generated from reStructeredText, e.g. devel/mercurial hg(1)
  63   These are a weird mixture of man(7) and custom autogenerated low-level
  64   roff stuff.  Figure out to what extent we can cope.
  65   noted by stsp@  Sat, 24 Apr 2010 09:17:55 +0200
  66   reminded by nicm@  Mon, 3 May 2010 09:52:41 +0100
  67
  68 - implement blank `Bl -column', such as
  69   .Bl -column
  70   .It foo Ta bar
  71   .El
  72
  73 - explicitly disallow nested `Bl -column', which would clobber internal
  74   flags defined for struct mdoc_macro
  75
  76 - inside `.Bl -column' phrases, punctuation is handled like normal
  77   text, e.g. `.Bl -column .It Fl x . Ta ...' should give "-x -."
  78
  79 - inside `.Bl -column' phrases, TERMP_IGNDELIM handling by `Pf'
  80   is not safe, e.g. `.Bl -column .It Pf a b .' gives "ab."
  81   but should give "ab ."
  82
  83 - set a meaningful default if no `Bl' list type is assigned
  84
  85 - have a blank `It' head for `Bl -tag' not puke
  86
  87 - prohibit `Nm' from having non-text HEAD children
  88   (e.g., NetBSD mDNSShared/dns-sd.1)
  89   (mdoc_html.c and mdoc_term.c `Nm' handlers can be slightly simplified)
  90
  91 - xloadimage(1) wants .ti (temporary indent), rep by naddy@
  92
  93 - bashbug(1) complains "line scope broken" after
  94   .SM
  95   .B something
  96   should either just work or be a warning
  97   reported by naddy@
  98
  99 - check compatibility with Plan9:
 100   http://swtch.com/usr/local/plan9/tmac/tmac.an
 101   http://swtch.com/plan9port/man/man7/man.html
 102   "Anthony J. Bentley" <anthonyjbentley@gmail.com> 28 Dec 2010 21:58:40 -0700
 103
 104 ************************************************************************
 105 * formatting issues: ugly output
 106 ************************************************************************
 107
 108 - double quotes inside double quotes are escaped by doubling them
 109   implement this in mdoc(7), too
 110   so far, we only have it in roff(7) and man(7)
 111   reminded by millert@  Thu, 09 Dec 2010 17:29:52 -0500
 112
 113 - perl(1) SYNOPSIS looks bad; reported by deraadt@
 114   1) man(7) seems to need SYNOPSIS .Nm blocks, too
 115
 116 - In .Bl -column,
 117   .It Em Authentication<tab>Key Length
 118   ought to render "Key Length" with emphasis, too,
 119   see OpenBSD iked.conf(5).
 120
 121 - empty phrases in .Bl column produce too few blanks
 122   try e.g. .Bl -column It Ta Ta
 123   reported by millert Fri, 02 Apr 2010 16:13:46 -0400
 124
 125 - in enclosures, mandoc sometimes fancies a bogus end of sentence
 126   reminded by jmc@  Thu, 23 Sep 2010 18:13:39 +0059
 127
 128 ************************************************************************
 129 * formatting issues: gratuitious differences
 130 ************************************************************************
 131
 132 - .Rv (and probably .Ex) print different text if an `Nm' has been named
 133   or not (run a manual without `Nm blah' to see this).  I'm not sure
 134   that this exists in the wild, but it's still an error.
 135
 136 - In .Bl -bullet, the groff bullet is "+\b+\bo\bo", the mandoc bullet
 137   is just "o\bo".
 138   see for example OpenBSD ksh(1)
 139
 140 - The characters "|" and "\*(Ba" should never be bold,
 141   not even in the middle of a word, e.g. ".Cm b\*(Bac" in
 142   "mknod [-m mode] name b|c major minor"
 143   in OpenBSD ksh(1)
 144
 145 - A bogus .Pp between two .It must not produce a double blank line,
 146   see between -R and -r in OpenBSD rm(1), before "update" in mount(8),
 147   or in DIAGNOSTICS in init(8).
 148   Also have `It' complain if `Pp' is invoked at certain times (not
 149   -compact?).
 150
 151 - .Nx 1.0a
 152   should be "NetBSD 1.0A", not "NetBSD 1.0a",
 153   see OpenBSD ccdconfig(8).
 154
 155 - In .Bl -tag, if a tag exceeds the right margin and must be continued
 156   on the next line, it must be indented by -width, not width+1;
 157   see "rule block|pass" in OpenBSD ifconfig(8).
 158
 159 - The \& zero-width character counts as output.
 160   That is, when it is alone on a line between two .Pp,
 161   we want three blank lines, not two as in mandoc.
 162
 163 - When .Fn arguments exceed one output line, all but the first
 164   should be indented, see e.g. rpc(3);
 165   reported by jmc@ on discuss@  Fri, 29 Oct 2010 13:48:33 +0100
 166
 167 - Header lines of excessive length:
 168   Port OpenBSD man_term.c rev. 1.25 to mdoc_term.c
 169   and document it in mdoc(7) and man(7) COMPATIBILITY
 170   found while talking to Chris Bennett
 171
 172 ************************************************************************
 173 * performance issues
 174 ************************************************************************
 175
 176 Several areas can be cleaned up to make mandoc even faster.  These are
 177
 178 - improve hashing mechanism for macros (quite important: performance)
 179
 180 - improve hashing mechanism for characters (not as important)
 181
 182 - the PDF file is HUGE: this can be reduced by using relative offsets
 183
 184 ************************************************************************
 185 * structural issues
 186 ************************************************************************
 187
 188 - Find better ways to prevent endless loops
 189   in roff(7) macro and string expansion.
 190