TODO

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