[BACK]Return to TODO CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/TODO between version 1.25 and 1.65

version 1.25, 2010/07/11 22:39:32 version 1.65, 2010/11/29 13:04:31
Line 1 
Line 1 
 ************************************************************************  ************************************************************************
   * Official mandoc TODO.
   * $Id$
   ************************************************************************
   
   ************************************************************************
   * parser bugs
   ************************************************************************
   
   - the roff parser doesn't tolerate additional characters between
     a macro and the \} terminating a conditional block, e.g.
     .if n \{
     .br \}
     reported by ulrich spoerlein  Tue, 19 Oct 2010 20:39:50 +0200
   
   - .BI "string string " word punct in gettext(3)
     add bogus line breaks (rep by naddy@)
     committed; currently working on IP and TP?
     and what about B and I?
   
   ************************************************************************
 * missing features  * missing features
 ************************************************************************  ************************************************************************
   
Line 16 
Line 36 
   lib/libc/gen/signal.3    lib/libc/gen/signal.3
   lib/libc/sys/sigaction.2    lib/libc/sys/sigaction.2
   
   - edge case: decide how to deal with blk_full bad nesting, e.g.
     .Sh .Nm .Bk .Nm .Ek .Sh found by jmc@ in ssh-keygen(1)
     from jmc@  Wed, 14 Jul 2010 18:10:32 +0100
   
   - auto-Bk in the SYNOPSIS
     patch from kristaps@  Fri, 16 Jul 2010 14:51:24 +0200
     to be revisited after OpenBSD 4.8 tree unlock
   
 - implement \\  - implement \\
   in plain text, identical to \e    in plain text, identical to \e
   as a macro argument, identical to \ i.e. escaping the next character    as a macro argument, identical to \ i.e. escaping the next character
Line 23 
Line 51 
   \\ must behave in a macro def like in a macro argument,    \\ must behave in a macro def like in a macro argument,
   and when using the macro, it must expand yet again.    and when using the macro, it must expand yet again.
   
 - implement \s (physical font size)  - implement basic non-parametric .de to support e.g. sox(1)
   \sN - set to N    .de SP
   \s+N - increment by N, 1 <= N <= 8    .if t .sp .5
   \s-N - decrement by N, 1 <= N <= 8    .if n .sp
   \s0 - restore previous size    ..
   \s(nn \s+-(nn \s'+-nn' \s+-'nn' \s[+-nn] \s+-[nn] - disambiguate    .de EX
   registers: .s .ps .sr .psr    .SP
   used by e.g. cu(1), tip(1)    .nf
     .ft CW
     ..
     .de EE
     .ft R
     .SP
     .fi
     ..
     reported by naddy@ Sat, 16 Oct 2010 23:51:57 +0200
   
 - look at bsd.lv tbl(1)  - implement parametric .de to support e.g.
   from kristaps@  Fri, 11 Sep 2009 17:10:53 +0200    /usr/xenocara/lib/libXxf86vm/manXF86VM.man
   also look at the mail from Thomas Klausner wiz at NetBSD    .de ZN
     on Wed, 2 Jun 2010 11:01:29 +0200    .ie t \fB\^\\$1\^\fR\\$2
     .el \fI\^\\$1\^\fP\\$2
     ..
     .ZN -lXxf86vm
   
   - clean up escape sequence handling, creating three classes:
     (1) fully implemented, or parsed and ignored without loss of content
     (2) unimplemented, potentially causing loss of content
         or serious mangling of formatting (e.g. \n) -> ERROR
         see textproc/mgdiff(1) for nice examples
     (3) undefined, just output the character -> perhaps WARNING
   
   - port OpenBSD tbl integration bsd.lv, probably cleaning it up
   
 - look at pages generated from reStructeredText, e.g. devel/mercurial hg(1)  - look at pages generated from reStructeredText, e.g. devel/mercurial hg(1)
   These are a weird mixture of man(7) and custom autogenerated low-level    These are a weird mixture of man(7) and custom autogenerated low-level
   roff stuff.  Figure out to what extent we can cope.    roff stuff.  Figure out to what extent we can cope.
Line 51 
Line 99 
 - explicitly disallow nested `Bl -column', which would clobber internal  - explicitly disallow nested `Bl -column', which would clobber internal
   flags defined for struct mdoc_macro    flags defined for struct mdoc_macro
   
   - inside `.Bl -column' phrases, punctuation is handled like normal
     text, e.g. `.Bl -column .It Fl x . Ta ...' should give "-x -."
   
   - inside `.Bl -column' phrases, TERMP_IGNDELIM handling by `Pf'
     is not safe, e.g. `.Bl -column .It Pf a b .' gives "ab."
     but should give "ab ."
   
 - set a meaningful default if no `Bl' list type is assigned  - set a meaningful default if no `Bl' list type is assigned
   
 - have a blank `It' head for `Bl -tag' not puke  - have a blank `It' head for `Bl -tag' not puke
   
 - ignore horrendous m[] font colouring  
   reported by J.C. Roberts  
   
 - prohibit `Nm' from having non-text HEAD children  - prohibit `Nm' from having non-text HEAD children
   (e.g., NetBSD mDNSShared/dns-sd.1)    (e.g., NetBSD mDNSShared/dns-sd.1)
   (mdoc_html.c and mdoc_term.c `Nm' handlers can be slightly simplified)    (mdoc_html.c and mdoc_term.c `Nm' handlers can be slightly simplified)
   
   - allow `Qq', `Dq', `Sq', `Aq', `Bq' to have 0 arguments
     noted by Alex Kozlov 08/06/10 23:05
   
   - Have `Sh', `It', `Ss' and others complain if `Pp' is invoked prior to
     close (in the post validation) or prior to open (pre).  This noted by
     jmc@ a thousand years ago.
   
   - xloadimage(1) wants .ti (temporary indent), rep by naddy@
   
   - bashbug(1) complains "line scope broken" after
     .SM
     .B something
     should either just work or be a warning
     reported by naddy@
   
 ************************************************************************  ************************************************************************
 * formatting issues: ugly output  * formatting issues: ugly output
 ************************************************************************  ************************************************************************
   
 - outside list context, text following .Sm off  - perl(1) SYNOPSIS looks bad; reported by deraadt@
   seems to follow without a blank (TERM_NOBLANK reset late?) e.g.    1) man(7) seems to need SYNOPSIS .Nm blocks, too
         .Sm off  
         .Xo  
         .Op Ar bind_address No /  
         .Ar port  
         .Xc  
         .Sm on  
         or by enclosing  
   reported by jmc Tue, 13 Apr 2010 08:48:14 +0100  
   
   - In .Bl -column,
     .It Em Authentication<tab>Key Length
     ought to render "Key Length" with emphasis, too,
     see OpenBSD iked.conf(5).
   
 - empty phrases in .Bl column produce too few blanks  - empty phrases in .Bl column produce too few blanks
   try e.g. .Bl -column It Ta Ta    try e.g. .Bl -column It Ta Ta
   reported by millert Fri, 02 Apr 2010 16:13:46 -0400    reported by millert Fri, 02 Apr 2010 16:13:46 -0400
   
   - in enclosures, mandoc sometimes fancies a bogus end of sentence
     reminded by jmc@  Thu, 23 Sep 2010 18:13:39 +0059
   
 ************************************************************************  ************************************************************************
 * formatting issues: gratuitious differences  * formatting issues: gratuitious differences
 ************************************************************************  ************************************************************************
   
 - none reported right now (yet schwarze@ knows of some)  - .Rv (and probably .Ex) print different text if an `Nm' has been named
     or not (run a manual without `Nm blah' to see this).  I'm not sure
     that this exists in the wild, but it's still an error.
   
   - .%T should be quoted, not underlined, when .%J is also present,
     to better distinguish the contents of .%T and .%J,
     see for example OpenBSD cat(1)
   
   - In .Bl -bullet, the groff bullet is "+\b+\bo\bo", the mandoc bullet
     is just "o\bo".
     see for example OpenBSD ksh(1)
   
   - The characters "|" and "\*(Ba" should never be bold,
     not even in the middle of a word, e.g. ".Cm b\*(Bac" in
     "mknod [-m mode] name b|c major minor"
     in OpenBSD ksh(1)
   
   - A bogus .Pp between two .It must not produce a double blank line,
     see between -R and -r in OpenBSD rm(1), before "update" in mount(8),
     or in DIAGNOSTICS in init(8).
   
   - .Bd -literal and .Bd -unfilled are *not* identical.
     In -literal, tabs are 8 spaces.
     In -unfilled, tabs are 5 spaces, just like in -filled and -ragged.
     See the CCDF_* display in OpenBSD ccdconfig(8).
   
   - .Nx 1.0a
     should be "NetBSD 1.0A", not "NetBSD 1.0a",
     see OpenBSD ccdconfig(8).
   
   - In .Bl -tag, if a tag exceeds the right margin and must be continued
     on the next line, it must be indented by -width, not width+1;
     see "rule block|pass" in OpenBSD ifconfig(8).
   
   - The \& zero-width character counts as output.
     That is, when it is alone on a line between two .Pp,
     we want three blank lines, not two as in mandoc.
   
   - When .Fn arguments exceed one output line, all but the first
     should be indented, see e.g. rpc(3);
     reported by jmc@ on discuss@  Fri, 29 Oct 2010 13:48:33 +0100
   
   - It seems that .TP does not want TWOSPACE after the tag;
     see bashbug(1); reported by naddy@
   
   - Header lines of excessive length:
     Port OpenBSD man_term.c rev. 1.25 to mdoc_term.c
     and document it in mdoc(7) and man(7) COMPATIBILITY
     found while talking to Chris Bennett
   
 ************************************************************************  ************************************************************************
 * performance issues  * performance issues
 ************************************************************************  ************************************************************************
Line 97  Several areas can be cleaned up to make mandoc even fa
Line 212  Several areas can be cleaned up to make mandoc even fa
   
 - improve hashing mechanism for characters (not as important)  - improve hashing mechanism for characters (not as important)
   
   - the PDF file is HUGE: this can be reduced by using relative offsets
   
 ************************************************************************  ************************************************************************
 * structural issues  * structural issues
 ************************************************************************  ************************************************************************
   
 - The regs.h functionality and the roff_getstrn() family should be moved  
   into mandoc.c, which should be accessable by libroff, libmdoc, and  
   libman.  Right now there's pollution between these libraries.  
   
Legend:
Removed from v.1.25  
changed lines
  Added in v.1.65
CVSweb