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

Diff for /mandoc/TODO between version 1.9 and 1.61

version 1.9, 2010/05/25 13:42:51 version 1.61, 2010/10/19 21:40:27
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
   
   ************************************************************************
 * missing features  * missing features
 ************************************************************************  ************************************************************************
   
   - deal with nested displays, e.g. D1 inside Bd
     schwarze has an old patch somewhere and would need to brush it up
   
 - explicit blocks with missing end macro should be implicitely closed  - explicit blocks with missing end macro should be implicitely closed
   at the end of the enclosing block, e.g. .Bl It (El) Sh    at the end of the enclosing block, e.g. .Bl It (El) Sh
   reminded by stsp@  in net/pptp pptp.8  Fri, 23 Apr 2010 20:32:39 +0200    reminded by stsp@  in net/pptp pptp.8  Fri, 23 Apr 2010 20:32:39 +0200
   
   - fix bad block nesting involving multiple identical explicit blocks
     see the OpenBSD mdoc_macro.c 1.47 commit message
   
 - .Bl -column .Xo support is missing  - .Bl -column .Xo support is missing
   ultimate goal:    ultimate goal:
   restore .Xr and .Dv to    restore .Xr and .Dv to
Line 13 
Line 34 
   lib/libc/gen/signal.3    lib/libc/gen/signal.3
   lib/libc/sys/sigaction.2    lib/libc/sys/sigaction.2
   
 - .Bk / .Ek is broken, e.g.  - edge case: decide how to deal with blk_full bad nesting, e.g.
   $ man ssh    .Sh .Nm .Bk .Nm .Ek .Sh found by jmc@ in ssh-keygen(1)
   [...]    from jmc@  Wed, 14 Jul 2010 18:10:32 +0100
   ssh [-1246AaCfgKkMNnqsTtVvXxYy] [-b bind_address] [-c cipher_spec] [-D  
   [bind_address:]port] [-e escape_char] [-F configfile] [-I pkcs11]  
   reminded by Ludo Smissaert  Mon, 10 May 2010 12:15:11 +0200  
   also reported by jmc@ earlier  
   
   - 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 28 
Line 49 
   \\ 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.
   
 - look at bsd.lv tbl(1)  - implement basic non-parametric .de to support e.g. sox(1)
   from kristaps@  Fri, 11 Sep 2009 17:10:53 +0200    .de SP
     .if t .sp .5
     .if n .sp
     ..
     .de EX
     .SP
     .nf
     .ft CW
     ..
     .de EE
     .ft R
     .SP
     .fi
     ..
     reported by naddy@ Sat, 16 Oct 2010 23:51:57 +0200
   
   - 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.
   noted by stsp@  Sat, 24 Apr 2010 09:17:55 +0200    noted by stsp@  Sat, 24 Apr 2010 09:17:55 +0200
   reminded by nicm@  Mon, 3 May 2010 09:52:41 +0100    reminded by nicm@  Mon, 3 May 2010 09:52:41 +0100
   
   - implement blank `Bl -column', such as
     .Bl -column
     .It foo Ta bar
     .El
   
 - FIXED OpenBSD term.h 1.16 term.c 1.30 mdoc_term.c 1.75 schwarze 23.4.10  - explicitly disallow nested `Bl -column', which would clobber internal
   handle tab characters outside literal context, e.g. usb(4)    flags defined for struct mdoc_macro
   reported by jmc@  Mon, 19 Apr 2010 07:42:12 +0100  
   NEEDS MERGING TO bsd.lv  
   
 - FIXED OpenBSD man.h 1.15 libman.h 1.16 man_hash.c 1.9  - inside `.Bl -column' phrases, punctuation is handled like normal
   man.c 1.25 man_macro.c 1.15 man_validate.c 1.19 man_action.c 1.15    text, e.g. `.Bl -column .It Fl x . Ta ...' should give "-x -."
   man_term.c 1.28 man_html.c 1.9 schwarze 25.4.  
   implement .if .ie .el  
   noticed by espie@  Fri, 23 Apr 2010 17:10:35 +0200  
   NEEDS MERGING TO bsd.lv  
   
   - 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
   
   - have a blank `It' head for `Bl -tag' not puke
   
   - prohibit `Nm' from having non-text HEAD children
     (e.g., NetBSD mDNSShared/dns-sd.1)
     (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.
   
 ************************************************************************  ************************************************************************
 * 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  
   
 - do not break the line after "--", it's probably a long option  - In .Bl -column,
   reminded by stsp in net/pptp pptp.8  Fri, 23 Apr 2010 20:32:39 +0200    .It Em Authentication<tab>Key Length
     ought to render "Key Length" with emphasis, too,
     see OpenBSD iked.conf(5).
   
 - URGENT, this is making many kernel manuals look bad:  
   .Ft/.Fn should MAYBE behave in custom section like in SYNOPSIS?  
   autoconf.9:  
     .Sh DIRECT CONFIGURATION  
     .nr nS 1  
     .Ft "struct device *"  
     .Fn config_found_sm "struct device *parent"  
   groff:  
     DIRECT CONFIGURATION  
       struct device *  
       config_found_sm(struct device *parent, ...  
   reported by sthen  Tue, 20 Apr 2010 13:42:51 +0100  
   
 - indentation got lost in SYNOPSIS, e.g.  
    SYNOPSIS  
         date [-ajnu] [-d dst] [-r seconds] [-t minutes_west] [+format]  
   -          [[[[[[cc]yy]mm]dd]HH]MM[.SS]]  
   +     [[[[[[cc]yy]mm]dd]HH]MM[.SS]]  
   reminded by Ludo Smissaert  Mon, 10 May 2010 12:15:11 +0200  
   
 - 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
   
 - nroff inserts a space before :, mandoc doesn't:  - in enclosures, mandoc sometimes fancies a bogus end of sentence
     .Dl expr "/$a" Li : '.*/\e(.*\e)'    reminded by jmc@  Thu, 23 Sep 2010 18:13:39 +0059
   
 ************************************************************************  ************************************************************************
 * formatting issues: gratuitious differences  * formatting issues: gratuitious differences
 ************************************************************************  ************************************************************************
   
 - FIXED OpenBSD mdoc.c 1.52 schwarze 16.5.10  - .%T should be quoted, not underlined, when .%J is also present,
   lines containing blank characters, and nothing else,    to better distinguish the contents of .%T and .%J,
   in literal context (.Bd -literal):    see for example OpenBSD cat(1)
   groff outputs just blank lines "\n"  
   mandoc outputs blanks to the left margin,  
   then the number of balnks minus one  
   NEEDS MERGING TO bsd.lv  
   
   - 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,
 * parser errors without any effect on formatting    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)
   
 - OpenBSD::PackageName(3p) has "if (block) 90:1" in the parse tree  - 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.
   
 ************************************************************************  ************************************************************************
 * performance issues  * performance issues
 ************************************************************************  ************************************************************************
   
 Several areas can be cleaned up to make mandoc even faster.  These are  Several areas can be cleaned up to make mandoc even faster.  These are
   
 - cache `Bd' display types as `Bl' types are cached (this primarily  
   improves code-size by removing the a2disp type functions)  
   
 - improve caching mechanism to handle other per-element arguments so  
   that they need not be recalculated between front- and back-ends (also  
   reduces code size and complexity)  
   
 - improve hashing mechanism for macros (quite important: performance)  - improve hashing mechanism for macros (quite important: performance)
   
 - 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
   ************************************************************************
Legend:
Removed from v.1.9  
changed lines
  Added in v.1.61
CVSweb