TODO

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