mandoc/TODO - diff

Return to TODO CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/TODO between version 1.64 and 1.145

-version 1.64, 2010/11/03 12:07:58
+version 1.145, 2012/11/04 18:58:15
 Line 4
 Line 4
 Line 4
  ************************************************************************
  ************************************************************************
- * parser bugs
+ * crashes
  ************************************************************************
- - the roff parser doesn't tolerate additional characters between
+ - $ echo ".Ta" >> ls.1
-   a macro and the \} terminating a conditional block, e.g.
+   $ mandoc ls.1
-   .if n \{
+   assertion "MDOC_BLOCK == p->parent->type" failed:
-   .br \}
+   file "/usr/src/usr.bin/mandoc/mdoc.c", line 399, function "node_append"
-   reported by ulrich spoerlein  Tue, 19 Oct 2010 20:39:50 +0200
+   from jmc@  Thu, 20 Sep 2012 21:35:58 +0059
- - .BI "string string " word punct in gettext(3)
-   add bogus line breaks (rep by naddy@)
-   committed; currently working on IP and TP?
-   and what about B and I?
  ************************************************************************
  * missing features
  ************************************************************************
- - explicit blocks with missing end macro should be implicitely closed
+ --- missing roff features ----------------------------------------------
-   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
+ - roff.c should treat \n(.H>23 and \n(.V>19 in the pod2man(1)
+   preamble as true, see for example AUTHORS in MooseX::Getopt.3p
+   reported by Andreas Voegele <mail at andreasvoegele dot com>
+   Tue, 22 Nov 2011 15:34:47 +0100 on ports@
+ - .ad (adjust margins)
+   .ad l -- adjust left margin only (flush left)
+   .ad r -- adjust right margin only (flush right)
+   .ad c -- center text on line
+   .ad b -- adjust both margins (alias: .ad n)
+   .na   -- temporarily disable adjustment without changing the mode
+   .ad   -- re-enable adjustment without changing the mode
+   Adjustment mode is ignored while in no-fill mode (.nf).
+ - .it (line traps) occur in mysql(1), yasm_arch(7)
+   generated by DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/>
+   reported by brad@  Sat, 15 Jan 2011 15:48:18 -0500
+ - .ns (no-space mode) occurs in xine-config(1)
+   reported by brad@  Sat, 15 Jan 2011 15:45:23 -0500
+ - xloadimage(1) wants .ti (temporary indent), rep by naddy@
+   reported again by bentley@ in nmh(1)  Mon, 23 Apr 2012 13:38:28 -0600
+   also uses .ce (center N lines) and .fc (field control)
+ - .ta (tab settings) occurs in ircbug(1) and probably gnats(1)
+   reported by brad@  Sat, 15 Jan 2011 15:50:51 -0500
+ - \c (interrupted text) should prevent the line break
+   even inside .Bd literal; that occurs in chat(8)
+ - using undefined strings or macros defines them to be empty
+   wl@  Mon, 14 Nov 2011 14:37:01 +0000
+ --- missing mdoc features ----------------------------------------------
  - fix bad block nesting involving multiple identical explicit blocks
    see the OpenBSD mdoc_macro.c 1.47 commit message
-Line 40
+Line 69
 Line 40
 Line 69
    .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
+ - \\ 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 \\
+ - .Bd -filled should not be the same as .Bd -ragged, but align both
-   in plain text, identical to \e
+   the left and right margin.  In groff, it is implemented in terms
-   as a macro argument, identical to \ i.e. escaping the next character
+   of .ad b, which we don't have either.  Found in cksum(1).
-   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.
- - implement basic non-parametric .de to support e.g. sox(1)
-   .de SP
-   .if t .sp .5
-   .if n .sp
-   ..
-   .de EX
-   .SP
-   .nf
-   .ft CW
-   ..
-   .de EE
-   .ft R
-   .SP
-   .fi
-   ..
-   reported by naddy@ Sat, 16 Oct 2010 23:51:57 +0200
- - implement parametric .de to support e.g.
-   /usr/xenocara/lib/libXxf86vm/manXF86VM.man
-   .de ZN
-   .ie t \fB\^\\$1\^\fR\\$2
-   .el \fI\^\\$1\^\fP\\$2
-   ..
-   .ZN -lXxf86vm
- - clean up escape sequence handling, creating three classes:
-   (1) fully implemented, or parsed and ignored without loss of content
-   (2) unimplemented, potentially causing loss of content
-       or serious mangling of formatting (e.g. \n) -> ERROR
-       see textproc/mgdiff(1) for nice examples
-   (3) undefined, just output the character -> perhaps WARNING
- - port OpenBSD tbl integration bsd.lv, probably cleaning it up
- - 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
-   roff stuff.  Figure out to what extent we can cope.
-   noted by stsp@  Sat, 24 Apr 2010 09:17:55 +0200
-   reminded by nicm@  Mon, 3 May 2010 09:52:41 +0100
  - implement blank `Bl -column', such as
    .Bl -column
    .It foo Ta bar
-Line 99
+Line 88
 Line 99
 Line 88
  - explicitly disallow nested `Bl -column', which would clobber internal
    flags defined for struct mdoc_macro
+ - In .Bl -column .It, the end of the line probably has to be regarded
+   as an implicit .Ta, if there could be one, see the following mildly
+   ugly code from login.conf(5):
+     .Bl -column minpasswordlen program xetcxmotd
+     .It path Ta path Ta value of Dv _PATH_DEFPATH
+     .br
+     Default search path.
+   reported by Michal Mazurek <akfaew at jasminek dot net>
+   via jmc@ Thu, 7 Apr 2011 16:00:53 +0059
  - inside `.Bl -column' phrases, punctuation is handled like normal
    text, e.g. `.Bl -column .It Fl x . Ta ...' should give "-x -."
-Line 114
+Line 113
 Line 114
 Line 113
    (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
+ - When there is free text in the SYNOPSIS and that free text contains
-   noted by Alex Kozlov 08/06/10 23:05
+   the .Nm macro, groff somehow understands to treat the .Nm as an in-line
+   macro, while mandoc treats it as a block macro and breaks the line.
+   No idea how the logic for distinguishing in-line and block instances
+   should be, needs investigation.
+   uqs@  Thu, 2 Jun 2011 11:03:51 +0200
+   uqs@  Thu, 2 Jun 2011 11:33:35 +0200
- - Have `Sh', `It', `Ss' and others complain if `Pp' is invoked prior to
+ --- missing man features -----------------------------------------------
-   close (in the post validation) or prior to open (pre).  This noted by
-   jmc@ a thousand years ago.
- - xloadimage(1) wants .ti (temporary indent), rep by naddy@
+ - groff an-ext.tmac macros (.UR, .UE) occur in xine(5)
+   reported by brad@  Sat, 15 Jan 2011 15:45:23 -0500
+   also occur in freeciv-client(6) freeciv-server(6) freeciv-modpack(6)
+   reported by bentley@  Tue, 30 Oct 2012 01:05:57 -0600
- - bashbug(1) complains "line scope broken" after
+ - -T[x]html doesn't stipulate non-collapsing spaces in literal mode
-   .SM
-   .B something
-   should either just work or be a warning
-   reported by naddy@
+ --- missing tbl features -----------------------------------------------
+ - implement basic non-parametric .de to support e.g. sox(1)
+   reported by naddy@ Sat, 16 Oct 2010 23:51:57 +0200
+   *** sox(1) still doesn't work, tbl(1) errors need investigation
+ - allow standalone `.' to be interpreted as an end-of-layout
+   delimiter instead of being thrown away as a no-op roff line
+   reported by Yuri Pankov, Wed 18 May 2011 11:34:59 CEST
+ --- missing misc features ----------------------------------------------
+ - clean up escape sequence handling, creating three classes:
+   (1) fully implemented, or parsed and ignored without loss of content
+   (2) unimplemented, potentially causing loss of content
+       or serious mangling of formatting (e.g. \n) -> ERROR
+       see textproc/mgdiff(1) for nice examples
+   (3) undefined, just output the character -> perhaps WARNING
+ - The \t escape sequence is the same as a literal tab, see for example
+   the ASCII table in hexdump(1) where
+     .Bl -column \&000_nu \&001_so \&002_st \&003_et \&004_eo
+     .It \&000\ nul\t001\ soh\t002\ stx\t003\ etx\t004\ eot\t005\ enq
+   produces
+nul  001 soh  002 stx  003 etx  004 eot  005 enq
+   and the example in oldrdist(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
+   roff stuff.  Figure out to what extent we can cope.
+   For details, see http://docutils.sourceforge.net/rst.html
+   noted by stsp@  Sat, 24 Apr 2010 09:17:55 +0200
+   reminded by nicm@  Mon, 3 May 2010 09:52:41 +0100
+ - 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
  ************************************************************************
- - perl(1) SYNOPSIS looks bad; reported by deraadt@
+ - a column list with blank `Ta' cells triggers a spurrious
-) man(7) seems to need SYNOPSIS .Nm blocks, too
+   start-with-whitespace printing of a newline
+ - 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
  - In .Bl -column,
    .It Em Authentication<tab>Key Length
    ought to render "Key Length" with emphasis, too,
    see OpenBSD iked.conf(5).
+   reported again Nicolas Joly via wiz@ Wed, 12 Oct 2011 00:20:00 +0200
  - 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
+ - .%T can have trailing punctuation.  Currently, it puts the trailing
+   punctuation into a trailing MDOC_TEXT element inside its own scope.
+   That element should rather be outside its scope, such that the
+   punctuation does not get underlines.  This is not trivial to
+   implement because .%T then needs some features of in_line_eoln() -
+   slurp all arguments into one single text element - and one feature
+   of in_line() - put trailing punctuation out of scope.
+   Found in mount_nfs(8) and exports(5), search for "Appendix".
  - in enclosures, mandoc sometimes fancies a bogus end of sentence
    reminded by jmc@  Thu, 23 Sep 2010 18:13:39 +0059
+ - Trailing isolated dots lack EOS for some macros.
+   This cannot use mandoc_eos() because groff only does EOS
+   for isolated dots at least in some of these cases.
+   Affected macros included those using in_line_eoln().
+   Make sure to fix open(2)
+   without breaking fstat(1), ksh(1), tzset(3) and UKC(8).
+   reported by Nicolas Joly  Fri, 12 Oct 2012 17:00:36 +0200
  ************************************************************************
- * formatting issues: gratuitious differences
+ * formatting issues: gratuitous 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.
  - In .Bl -bullet, the groff bullet is "+\b+\bo\bo", the mandoc bullet
    is just "o\bo".
    see for example OpenBSD ksh(1)
- - The characters "|" and "\*(Ba" should never be bold,
+ - .Pp between two .It in .Bl -column should produce one,
-   not even in the middle of a word, e.g. ".Cm b\*(Bac" in
+   not two blank lines, see e.g. login.conf(5).
-   "mknod [-m mode] name b|c major minor"
+   reported by jmc@  Sun, 17 Apr 2011 14:04:58 +0059
-   in OpenBSD ksh(1)
+   reported again by sthen@  Wed, 18 Jan 2012 02:09:39 +0000 (UTC)
- - A bogus .Pp between two .It must not produce a double blank line,
+ - If the *first* line after .It is .Pp, break the line right after
-   see between -R and -r in OpenBSD rm(1), before "update" in mount(8),
+   the tag, do not pad with space characters before breaking.
-   or in DIAGNOSTICS in init(8).
+   See the description of the a, c, and i commands in sed(1).
- - .Bd -literal and .Bd -unfilled are *not* identical.
+ - If the first line after .It is .D1, do not assert a blank line
-   In -literal, tabs are 8 spaces.
+   in between, see for example tmux(1).
-   In -unfilled, tabs are 5 spaces, just like in -filled and -ragged.
+   reported by nicm@  13 Jan 2011 00:18:57 +0000
-   See the CCDF_* display in OpenBSD ccdconfig(8).
  - .Nx 1.0a
    should be "NetBSD 1.0A", not "NetBSD 1.0a",
-Line 182
+Line 244
 Line 182
 Line 244
    on the next line, it must be indented by -width, not width+1;
    see "rule block|pass" in OpenBSD ifconfig(8).
+ - When the -width string contains macros, the macros must be rendered
+   before measuring the width, for example
+     .Bl -tag -width ".Dv message"
+   in magic(5), located in src/usr.bin/file, is the same
+   as -width 7n, not -width 11n.
+   The same applies to .Bl -column column widths;
+   reported again by Nicolas Joly Thu, 1 Mar 2012 13:41:26 +0100 via wiz@ 5 Mar
  - The \& zero-width character counts as output.
    That is, when it is alone on a line between two .Pp,
    we want three blank lines, not two as in mandoc.
-Line 189
+Line 259
 Line 189
 Line 259
  - When .Fn arguments exceed one output line, all but the first
    should be indented, see e.g. rpc(3);
    reported by jmc@ on discuss@  Fri, 29 Oct 2010 13:48:33 +0100
+   reported again by Nicolas Joly via wiz@  Sun, 18 Sep 2011 18:24:40 +0200
+   Also, we don't want to break the line within the argument of:
+   .Fa "chtype tl"
- - It seems that .TP does not want TWOSPACE after the tag;
-   see bashbug(1); reported by naddy@
  - Header lines of excessive length:
    Port OpenBSD man_term.c rev. 1.25 to mdoc_term.c
    and document it in mdoc(7) and man(7) COMPATIBILITY
    found while talking to Chris Bennett
+ - trailing whitespace must be ignored even when followed by a font escape,
+   see for example
+     makes
+     \fBdig \fR
+     operate in batch mode
+   in dig(1).
  ************************************************************************
  * performance issues
  ************************************************************************
-Line 210  Several areas can be cleaned up to make mandoc even fa
+Line 287  Several areas can be cleaned up to make mandoc even fa
 Line 210  Several areas can be cleaned up to make mandoc even fa
 Line 287  Several areas can be cleaned up to make mandoc even fa
  - the PDF file is HUGE: this can be reduced by using relative offsets
+ - instead of re-initialising the roff predefined-strings set before each
+   parse, create a read-only version the first time and copy it
  ************************************************************************
  * structural issues
  ************************************************************************
+ - We use the input line number at several places to distinguish
+   same-line from different-line input.  That plainly doesn't work
+   with user-defined macros, leading to random breakage.
+ - Find better ways to prevent endless loops
+   in roff(7) macro and string expansion.
+ - Finish cleanup of date handling.
+   Decide which formats should be recognized where.
+   Update both mdoc(7) and man(7) documentation.
+   Triggered by  Tim van der Molen  Tue, 22 Feb 2011 20:30:45 +0100

CVSweb