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

Diff for /mandoc/TODO between version 1.1 and 1.31

version 1.1, 2010/05/14 18:20:20 version 1.31, 2010/07/19 09:21:58
Line 1 
Line 1 
   ************************************************************************
   * Official mandoc TODO.  May not be quite up to date.
   * $Id$
   ************************************************************************
   
 Before trying to fix anything from this list,  
 check against -current mandoc from OpenBSD CVS.  
 Sometimes, i'm a bit behind marking entries FIXED.  
   
 In general, i keep FIXED entries for some time  
 and remove them when they turn into old news.  
   
 ************************************************************************  ************************************************************************
 * missing features  * missing features
 ************************************************************************  ************************************************************************
Line 14  and remove them when they turn into old news.
Line 11  and remove them when they turn into old news.
   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 21  and remove them when they turn into old news.
Line 21  and remove them when they turn into old news.
   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  
   
 - man(7) .TH should recognize "3p" as a section number  - auto-Bk in the SYNOPSIS
   found in usr.bin/pkg_add OpenBSD::Getopt    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
Line 41  and remove them when they turn into old news.
Line 38  and remove them when they turn into old news.
   
 - look at bsd.lv tbl(1)  - look at bsd.lv tbl(1)
   from kristaps@  Fri, 11 Sep 2009 17:10:53 +0200    from kristaps@  Fri, 11 Sep 2009 17:10:53 +0200
     also look at the mail from Thomas Klausner wiz at NetBSD
       on Wed, 2 Jun 2010 11:01:29 +0200
   
 - 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
Line 48  and remove them when they turn into old news.
Line 47  and remove them when they turn into old news.
   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  
   
 - FIXED OpenBSD man.h 1.15 libman.h 1.16 man_hash.c 1.9  - set a meaningful default if no `Bl' list type is assigned
   man.c 1.25 man_macro.c 1.15 man_validate.c 1.19 man_action.c 1.15  
   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  
   
 - FIXED bsd.lv libman.h 1.31 libmdoc.h 1.34 man.c 1.60 mdoc.c 1.123  - have a blank `It' head for `Bl -tag' not puke
         kristaps@ 8.4.10  
   FIXED OpenBSD libman.h 1.17 libmdoc.h 1.28 man.c 1.26 mdoc.c 1.45  
         schwarze@ 8.5.10  
   groff handles \." just like .\"  
   Thus, mandoc must also ignore such lines.  
   For an example, see tr(1).  
   reported by Claus Assmann Mon, 5 Apr 2010 08:46:30 -0700  
   
   - 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)
   
 ************************************************************************  ************************************************************************
 * 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  
   reminded by stsp in net/pptp pptp.8  Fri, 23 Apr 2010 20:32:39 +0200  
   
 - in .Bl -column .It, "\t" seems to be synonymous to " Ta ",  
   see sysctl(3) for many examples;  
   mishandling this results in spurious quotes at EOL  
   reminded by guenther@  Mon, 26 Apr 2010 01:16:52 -0700  
   
 - 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
   
   - .Pp before and after .Sh (and .Ss) produces a spurious blank line;
     reported by jmc@  Thu, 15 Jul 2010 23:00:28 +0100
   
 - FIXED on bsd.lv for mdoc, need to merge and test in OpenBSD  
     kristaps@  Mon, 10 May 2010 03:12:44 +0200  
     man fix still pending!  
   in literal displays, ignore the right margin  
   reminded by stsp in net/pptp pptp.8  Fri, 23 Apr 2010 20:32:39 +0200  
   
 - FIXED on bsd.lv, need to merge and test in OpenBSD  
     kristaps@  Mon, 10 May 2010 02:59:40 +0200  
   do not mark \*(Ba and | up  
   e.g. .Op Fl c Ar string \*(Ba Fl s \*(Ba Ar file Op Ar argument ...  
   The first should not be in an .Ar font.  
   The second must not end up as -|.  
   When fixing, check whether this is a specific problem with this  
   character, or whether other characters are affected, too.  
   reminded by jmc@  Sat, 24 Apr 2010 06:54:26 +0100  
   
   
 ************************************************************************  ************************************************************************
 * formatting issues: gratuitious differences  * formatting issues: gratuitious differences
 ************************************************************************  ************************************************************************
   
 - in literal context, groff disables the right margin  - none reported right now (yet schwarze@ knows of some)
   an example: syslog.conf.5 EXAMPLES section  
   reported by jmc Tue, 13 Apr 2010 10:12:15 +0100  
   solution: raise termp->maxrmargin in literal context  
   
 - lines containing blank characters, and nothing else,  ************************************************************************
   in literal context (.Bd -literal):  * performance issues
   groff outputs just blank lines "\n"  ************************************************************************
   mandoc outputs blanks to the left margin,  
   then the number of balnks minus one  
   
   Several areas can be cleaned up to make mandoc even faster.  These are
   
 - FIXED bsd.lv mdoc_html.c 1.61 mdoc_term.c 1.117 kristaps@ 8.4.10  - improve hashing mechanism for macros (quite important: performance)
   FIXED OpenBSD mdoc_html.c 1.12 mdoc_term.c 1.76 schwarze@ 8.5.10  
   mandoc .%T changed from quoted to underlined  
   reported by jmc Mon, 10 Aug 2009 05:50:21 +0100  
   
   - improve hashing mechanism for characters (not as important)
   
 ************************************************************************  ************************************************************************
 * parser errors without any effect on formatting  * structural issues
 ************************************************************************  ************************************************************************
   
 - OpenBSD::PackageName(3p) has "if (block) 90:1" in the parse tree  
   
Legend:
Removed from v.1.1  
changed lines
  Added in v.1.31
CVSweb