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

Diff for /mandoc/TODO between version 1.1 and 1.42

version 1.1, 2010/05/14 18:20:20 version 1.42, 2010/08/20 22:51:29
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  - 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  
   
 - FIXED bsd.lv libman.h 1.31 libmdoc.h 1.34 man.c 1.60 mdoc.c 1.123  - inside `.Bl -column' phrases, TERMP_IGNDELIM handling by `Pf'
         kristaps@ 8.4.10    is not safe, e.g. `.Bl -column .It Pf a b .' gives "ab."
   FIXED OpenBSD libman.h 1.17 libmdoc.h 1.28 man.c 1.26 mdoc.c 1.45    but should give "ab ."
         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  
   
   - 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
   
   - 'br\} doesn't correctly close scope.
     Noted by joerg@, 28/7/2010.
   
 ************************************************************************  ************************************************************************
 * 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).
   
 - 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
   
   - %A doesn't put an "and" before the final author name.
   
 - FIXED on bsd.lv for mdoc, need to merge and test in OpenBSD  ************************************************************************
     kristaps@  Mon, 10 May 2010 03:12:44 +0200  * formatting issues: gratuitious differences
     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  - .%T should be quoted, not underlined, when .%J is also present,
     kristaps@  Mon, 10 May 2010 02:59:40 +0200    to better distinguish the contents of .%T and .%J,
   do not mark \*(Ba and | up    see for example OpenBSD cat(1)
   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  
   
   - .It ${name Ns [ selector ] Ns }
     should be "${name[selector]}" not "${name [selector]}"
     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)
   
   - In .Bl -bullet, the groff bullet is "+\b+\bo\bo", the mandoc bullet
     is just "o\bo".
     see for example OpenBSD ksh(1)
   
   - .No text No ) is "text )", not "text)"
     see the terrible example
       case word in [[(]  pattern [| pattern] ... ) list ;; ] ... esac
     in OpenBSD ksh(1)
   
   - .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), 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).
   
   - In .Bd -unfilled, .Pp should produce one blank line, not two;
     see the ccd.conf 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).
   
   - When .%T is used outside an .Rs context and with a trailing comma,
     there is no point in rendering two commata,
     see the first paragraph of the DESCRIPTION in OpenBSD mount_nfs(8).
   
   - When .%T is used outside an .Rs context and without a trailing comma,
     no comma should be rendered at all,
     see the first paragraph of the DESCRIPTION in OpenBSD exports(5).
   
   - Bogus .Pp before .Bl should not cause a double blank line,
     see "The route utility provides the following simple commands:"
     in OpenBSD route(8).
   
 ************************************************************************  ************************************************************************
 * 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
   
   - Now that `ds' is minimally supported, we can get rid of some
     predefined strings.  \*(C+ has already been thrown out.  Track these
     down and whack them.  Look in e.g. gcc.1 for the top-level `ds'
     invocations.  These are reproduced across most crappy GNU manuals.
Legend:
Removed from v.1.1  
changed lines
  Added in v.1.42
CVSweb