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

Diff for /mandoc/TODO between version 1.42 and 1.75

version 1.42, 2010/08/20 22:51:29 version 1.75, 2011/01/10 03:43:47
Line 4 
Line 4 
 ************************************************************************  ************************************************************************
   
 ************************************************************************  ************************************************************************
   * 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
   
   ************************************************************************
   * formatter bugs
   ************************************************************************
   
   - in literal mode, the man(7) -Tascii formatter
     breaks the line between macro arguments,
     e.g. ".B #include <libintl.h>" in gettext(3)
   
   ************************************************************************
 * missing features  * missing features
 ************************************************************************  ************************************************************************
   
 - explicit blocks with missing end macro should be implicitely closed  - pod2man expects `tr' to be implemented for \*(-- to work
   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  
   
   - implement `rm' - it is easy to do and used in the pod2man preamble
     reminded by brad@  Sun, Jan 09, 2011 at 09:45:58PM -0500
   
 - 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
   
Line 25 
Line 44 
   .Sh .Nm .Bk .Nm .Ek .Sh found by jmc@ in ssh-keygen(1)    .Sh .Nm .Bk .Nm .Ek .Sh found by jmc@ in ssh-keygen(1)
   from jmc@  Wed, 14 Jul 2010 18:10:32 +0100    from jmc@  Wed, 14 Jul 2010 18:10:32 +0100
   
 - auto-Bk in the SYNOPSIS  - \\ is now implemented correctly
   patch from kristaps@  Fri, 16 Jul 2010 14:51:24 +0200    * when defining strings and macros using .ds and .de
   to be revisited after OpenBSD 4.8 tree unlock    * when parsing roff(7) and man(7) macro arguments
     It does not yet work in mdoc(7) macro arguments
     because libmdoc does not yet use mandoc_getarg().
     Also check what happens in plain text, it must be identical to \e.
   
 - implement \\  - implement basic non-parametric .de to support e.g. sox(1)
   in plain text, identical to \e    reported by naddy@ Sat, 16 Oct 2010 23:51:57 +0200
   as a macro argument, identical to \ i.e. escaping the next character    *** sox(1) still doesn't work, tbl(1) errors need investigation
   We do not have macro definitions yet; if we implement them,  
   \\ must behave in a macro def like in a macro argument,  
   and when using the macro, it must expand yet again.  
   
 - look at bsd.lv tbl(1)  - clean up escape sequence handling, creating three classes:
   from kristaps@  Fri, 11 Sep 2009 17:10:53 +0200    (1) fully implemented, or parsed and ignored without loss of content
   also look at the mail from Thomas Klausner wiz at NetBSD    (2) unimplemented, potentially causing loss of content
     on Wed, 2 Jun 2010 11:01:29 +0200        or serious mangling of formatting (e.g. \n) -> ERROR
   joerg@ has patches for this somewhere...        see textproc/mgdiff(1) for nice examples
     (3) undefined, just output the character -> perhaps WARNING
   
 - 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 71 
Line 91 
   (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  - xloadimage(1) wants .ti (temporary indent), rep by naddy@
   noted by Alex Kozlov 08/06/10 23:05  
   
 - 'br\} doesn't correctly close scope.  - bashbug(1) complains "line scope broken" after
   Noted by joerg@, 28/7/2010.    .SM
     .B something
     should either just work or be a warning
     reported by naddy@
   
   - check compatibility with Plan9:
     http://swtch.com/usr/local/plan9/tmac/tmac.an
     http://swtch.com/plan9port/man/man7/man.html
     "Anthony J. Bentley" <anthonyjbentley@gmail.com> 28 Dec 2010 21:58:40 -0700
   
 ************************************************************************  ************************************************************************
 * formatting issues: ugly output  * formatting issues: ugly output
 ************************************************************************  ************************************************************************
   
   - double quotes inside double quotes are escaped by doubling them
     implement this in mdoc(7), too
     so far, we only have it in roff(7) and man(7)
     reminded by millert@  Thu, 09 Dec 2010 17:29:52 -0500
   
 - perl(1) SYNOPSIS looks bad; reported by deraadt@  - perl(1) SYNOPSIS looks bad; reported by deraadt@
   1) man(7) seems to need SYNOPSIS .Nm blocks, too    1) man(7) seems to need SYNOPSIS .Nm blocks, too
   
Line 93 
Line 125 
   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.  - in enclosures, mandoc sometimes fancies a bogus end of sentence
     reminded by jmc@  Thu, 23 Sep 2010 18:13:39 +0059
   
 ************************************************************************  ************************************************************************
 * formatting issues: gratuitious differences  * formatting issues: gratuitious differences
 ************************************************************************  ************************************************************************
   
 - .%T should be quoted, not underlined, when .%J is also present,  - .Rv (and probably .Ex) print different text if an `Nm' has been named
   to better distinguish the contents of .%T and .%J,    or not (run a manual without `Nm blah' to see this).  I'm not sure
   see for example OpenBSD cat(1)    that this exists in the wild, but it's still an error.
   
 - .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  - In .Bl -bullet, the groff bullet is "+\b+\bo\bo", the mandoc bullet
   is just "o\bo".    is just "o\bo".
   see for example OpenBSD ksh(1)    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,  - The characters "|" and "\*(Ba" should never be bold,
   not even in the middle of a word, e.g. ".Cm b\*(Bac" in    not even in the middle of a word, e.g. ".Cm b\*(Bac" in
   "mknod [-m mode] name b|c major minor"    "mknod [-m mode] name b|c major minor"
Line 134 
Line 148 
 - A bogus .Pp between two .It must not produce a double blank line,  - 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),    see between -R and -r in OpenBSD rm(1), before "update" in mount(8),
   or in DIAGNOSTICS in init(8).    or in DIAGNOSTICS in init(8).
     Also have `It' complain if `Pp' is invoked at certain times (not
     -compact?).
   
 - .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  - .Nx 1.0a
   should be "NetBSD 1.0A", not "NetBSD 1.0a",    should be "NetBSD 1.0A", not "NetBSD 1.0a",
   see OpenBSD ccdconfig(8).    see OpenBSD ccdconfig(8).
Line 151 
Line 159 
   on the next line, it must be indented by -width, not width+1;    on the next line, it must be indented by -width, not width+1;
   see "rule block|pass" in OpenBSD ifconfig(8).    see "rule block|pass" in OpenBSD ifconfig(8).
   
 - When .%T is used outside an .Rs context and with a trailing comma,  - The \& zero-width character counts as output.
   there is no point in rendering two commata,    That is, when it is alone on a line between two .Pp,
   see the first paragraph of the DESCRIPTION in OpenBSD mount_nfs(8).    we want three blank lines, not two as in mandoc.
   
 - When .%T is used outside an .Rs context and without a trailing comma,  - When .Fn arguments exceed one output line, all but the first
   no comma should be rendered at all,    should be indented, see e.g. rpc(3);
   see the first paragraph of the DESCRIPTION in OpenBSD exports(5).    reported by jmc@ on discuss@  Fri, 29 Oct 2010 13:48:33 +0100
   
 - Bogus .Pp before .Bl should not cause a double blank line,  - Header lines of excessive length:
   see "The route utility provides the following simple commands:"    Port OpenBSD man_term.c rev. 1.25 to mdoc_term.c
   in OpenBSD route(8).    and document it in mdoc(7) and man(7) COMPATIBILITY
     found while talking to Chris Bennett
   
 ************************************************************************  ************************************************************************
   * error reporting issues
   ************************************************************************
   
   - .fi without preceding .nf need not be an ERROR,
     a warning is sufficient; occurs in all postfix manuals
     reported by brad@  Sun, Jan 09, 2011 at 09:45:58PM -0500
   
   - downgrade "ERROR: macro requires body argument(s)" to WARNING
     for the typical man(7) cases, it keeps confusing people
     reminded by brad@  Sun, Jan 09, 2011 at 09:45:58PM -0500
   
   ************************************************************************
 * performance issues  * performance issues
 ************************************************************************  ************************************************************************
   
Line 179  Several areas can be cleaned up to make mandoc even fa
Line 200  Several areas can be cleaned up to make mandoc even fa
 * structural issues  * structural issues
 ************************************************************************  ************************************************************************
   
 - rendering frontend code can calculate widths only for plain strings,  - Find better ways to prevent endless loops
   not for strings containing escape sequences.  For example, this    in roff(7) macro and string expansion.
   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.42  
changed lines
  Added in v.1.75
CVSweb