mandoc/TODO - diff

Return to TODO CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/TODO between version 1.26 and 1.42

-version 1.26, 2010/07/16 22:10:04
+version 1.42, 2010/08/20 22:51:29
 Line 1
 Line 1
 Line 1
  ************************************************************************
+ * Official mandoc TODO.
+ * $Id$
+ ************************************************************************
+ ************************************************************************
  * missing features
  ************************************************************************
-Line 16
+Line 21
 Line 16
 Line 21
    lib/libc/gen/signal.3
    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 \\
    in plain text, identical to \e
    as a macro argument, identical to \ i.e. escaping the next character
-Line 23
+Line 36
 Line 23
 Line 36
    \\ must behave in a macro def like in a macro argument,
    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)
    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)
    These are a weird mixture of man(7) and custom autogenerated low-level
-Line 51
+Line 56
 Line 51
 Line 56
  - explicitly disallow nested `Bl -column', which would clobber internal
    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
  - 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
    (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
  ************************************************************************
- - 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.
+) 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
+ - In .Bl -column,
+   .It Em Authentication<tab>Key Length
+   ought to render "Key Length" with emphasis, too,
+   see OpenBSD iked.conf(5).
  - empty phrases in .Bl column produce too few blanks
    try e.g. .Bl -column It Ta Ta
    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
  ************************************************************************
- - 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
  ************************************************************************
-Line 97  Several areas can be cleaned up to make mandoc even fa
+Line 173  Several areas can be cleaned up to make mandoc even fa
 Line 97  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)
+ - the PDF file is HUGE: this can be reduced by using relative offsets
  ************************************************************************
  * structural issues
  ************************************************************************
+ - 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.

CVSweb