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

Diff for /mandoc/TODO between version 1.24 and 1.42

version 1.24, 2010/07/05 10:45:14 version 1.42, 2010/08/20 22:51:29
Line 1 
Line 1 
 ************************************************************************  ************************************************************************
   * Official mandoc TODO.
   * $Id$
   ************************************************************************
   
   ************************************************************************
 * missing features  * missing features
 ************************************************************************  ************************************************************************
   
Line 9 
Line 14 
 - fix bad block nesting involving multiple identical explicit blocks  - fix bad block nesting involving multiple identical explicit blocks
   see the OpenBSD mdoc_macro.c 1.47 commit message    see the OpenBSD mdoc_macro.c 1.47 commit message
   
 - we need real .ds; for example, terminfo.3 has  
   .ds n 5  
   and then later  
   \fBterminfo\fR(\*n)  
   reported orally by halex@ during c2k10  
   
 - \*(Pu is not implemented, but used in mdoc.samples  
   implementing .ds would solve this as well  
   reminded by jmc@, last on Sun, 27 Jun 2010 15:29:18 +0100  
   
 - .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 26 
Line 21 
   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 33 
Line 36 
   \\ 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)  
   \sN - set to N  
   \s+N - increment by N, 1 <= N <= 8  
   \s-N - decrement by N, 1 <= N <= 8  
   \s0 - restore previous size  
   \s(nn \s+-(nn \s'+-nn' \s+-'nn' \s[+-nn] \s+-[nn] - disambiguate  
   registers: .s .ps .sr .psr  
   used by e.g. cu(1), tip(1)  
   
 - 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    also look at the mail from Thomas Klausner wiz at NetBSD
     on Wed, 2 Jun 2010 11:01:29 +0200      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 61 
Line 56 
 - 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
   
   - '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  
   
 - indentation got lost in SYNOPSIS, e.g.  - In .Bl -column,
    SYNOPSIS    .It Em Authentication<tab>Key Length
         date [-ajnu] [-d dst] [-r seconds] [-t minutes_west] [+format]    ought to render "Key Length" with emphasis, too,
   -          [[[[[[cc]yy]mm]dd]HH]MM[.SS]]    see OpenBSD iked.conf(5).
   +     [[[[[[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.
   
 ************************************************************************  ************************************************************************
 * formatting issues: gratuitious differences  * formatting issues: gratuitious differences
 ************************************************************************  ************************************************************************
   
 - none reported right now (yet schwarze@ knows of some)  - .%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)
   
   - .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).
   
 ************************************************************************  ************************************************************************
 * performance issues  * performance issues
 ************************************************************************  ************************************************************************
Line 114  Several areas can be cleaned up to make mandoc even fa
Line 173  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  - rendering frontend code can calculate widths only for plain strings,
   into mandoc.c, which should be accessable by libroff, libmdoc, and    not for strings containing escape sequences.  For example, this
   libman.  Right now there's pollution between these libraries.    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.24  
changed lines
  Added in v.1.42
CVSweb