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

Diff for /mandoc/TODO between version 1.1 and 1.38

version 1.1, 2010/05/14 18:20:20 version 1.38, 2010/08/15 16:38:35
Line 1 
Line 1 
   ************************************************************************
   * Official mandoc TODO.
   * $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
     joerg@ has patches for this somewhere...
   
 - 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 48  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)
   
   - allow `Qq', `Dq', `Sq', `Aq', `Bq' to have 0 arguments
     noted by Alex Kozlov 08/06/10 23:05
   
 ************************************************************************  ************************************************************************
 * 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  - empty phrases in .Bl column produce too few blanks
   reminded by stsp in net/pptp pptp.8  Fri, 23 Apr 2010 20:32:39 +0200    try e.g. .Bl -column It Ta Ta
     reported by millert Fri, 02 Apr 2010 16:13:46 -0400
   
 - in .Bl -column .It, "\t" seems to be synonymous to " Ta ",  - %A doesn't put an "and" before the final author name.
   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?  * formatting issues: gratuitious differences
   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.  - .%T should be quoted, not underlined, when .%J is also present,
    SYNOPSIS    to better distinguish the contents of .%T and .%J,
         date [-ajnu] [-d dst] [-r seconds] [-t minutes_west] [+format]    see for example OpenBSD cat(1)
   -          [[[[[[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  - .It ${name Ns [ selector ] Ns }
   try e.g. .Bl -column It Ta Ta    should be "${name[selector]}" not "${name [selector]}"
   reported by millert Fri, 02 Apr 2010 16:13:46 -0400    This is parsed as
     text("${name") text("[") Ns() text(selector)...
     Opening punctuation should not fall out of .Ns.
     see for example OpenBSD csh(1)
   
   - .%A should append the last author with " and " (if there are two)
     or ", and " (if there are more), not ", "
     see for example OpenBSD csh(1)
   
 - FIXED on bsd.lv for mdoc, need to merge and test in OpenBSD  - In .Bl -bullet, the groff bullet is "+\b+\bo\bo", the mandoc bullet
     kristaps@  Mon, 10 May 2010 03:12:44 +0200    is just "o\bo".
     man fix still pending!    see for example OpenBSD ksh(1)
   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  - .No text No ) is "text )", not "text)"
     kristaps@  Mon, 10 May 2010 02:59:40 +0200    see the terrible example
   do not mark \*(Ba and | up      case word in [[(]  pattern [| pattern] ... ) list ;; ] ... esac
   e.g. .Op Fl c Ar string \*(Ba Fl s \*(Ba Ar file Op Ar argument ...    in OpenBSD ksh(1)
   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  
   
   - .Sm should *not* produce as a blank line in .Bd -literal
     see for example "Brace expansion" in 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).
   
 ************************************************************************  ************************************************************************
 * formatting issues: gratuitious differences  * performance issues
 ************************************************************************  ************************************************************************
   
 - in literal context, groff disables the right margin  Several areas can be cleaned up to make mandoc even faster.  These are
   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,  - improve hashing mechanism for macros (quite important: performance)
   in literal context (.Bd -literal):  
   groff outputs just blank lines "\n"  
   mandoc outputs blanks to the left margin,  
   then the number of balnks minus one  
   
   - improve hashing mechanism for characters (not as important)
   
 - FIXED bsd.lv mdoc_html.c 1.61 mdoc_term.c 1.117 kristaps@ 8.4.10  - the PDF file is HUGE: this can be reduced by using relative offsets
   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  
   
   
 ************************************************************************  ************************************************************************
 * parser errors without any effect on formatting  * structural issues
 ************************************************************************  ************************************************************************
   
 - OpenBSD::PackageName(3p) has "if (block) 90:1" in the parse tree  - rendering frontend code can calculate widths only for plain strings,
     not for strings containing escape sequences.  For example, this
     hinders calculation of the indent required for .Nm \&[ in text(1).
     comments from kristaps@  Wed, 21 Jul 2010 23:26:08 +0200
   
   - another example of the same problem:
     .Bl -tag -width "\eD{format}XX" -compact
     in OpenBSD ksh(1) gives the wrong width
     because "\e" is one character in groff, two in mandoc
   
Legend:
Removed from v.1.1  
changed lines
  Added in v.1.38
CVSweb