=================================================================== RCS file: /cvs/mandoc/TODO,v retrieving revision 1.285 retrieving revision 1.333 diff -u -p -r1.285 -r1.333 --- mandoc/TODO 2019/03/01 10:57:17 1.285 +++ mandoc/TODO 2023/11/24 04:38:50 1.333 @@ -1,6 +1,6 @@ ************************************************************************ * Official mandoc TODO. -* $Id: TODO,v 1.285 2019/03/01 10:57:17 schwarze Exp $ +* $Id: TODO,v 1.333 2023/11/24 04:38:50 schwarze Exp $ ************************************************************************ Many issues are annotated for difficulty as follows: @@ -33,6 +33,56 @@ Obviously, as the issues have not been solved yet, the are mere guesses, and some may be wrong. ************************************************************************ +* assertion failures +************************************************************************ + +- .if n .ce in the middle of .TS data + afl case f1/id:000103,sig:06,src:009024+009105,op:splice,rep:2 (jes@) + While roff_parseln() prevents .ce and similar requests in the middle + of a tbl, the guard is no longer effective when the .ce is wrapped + in a roff block, for example a conditional. The resulting assertion + has never been seen in any real-world manual page. + This is too dangerous to fix before release because it requires + reorganizing the very delicate internals of roff_parseln(), + which risks causing more severe bugs. + loc * exist *** algo *** size * imp * + + +************************************************************************ +* bugs: invalid output +************************************************************************ + +- wrong number of layout columns in tbl(7) code generated by -T man + https://savannah.gnu.org/bugs/?57720 + The reason likely is that tbl(7) does not support the -Bl -column + feature of not explicitly specifying the last table column. + loc ** exist * algo ** size * imp *** + +- eqn(7) delimiters cause conditional lines to misbehave + nabijaczleweli 8 Sep 2021 15:24:48 +0200 + loc * exist *** algo *** size * imp * + +- roff.c, roff_expand() should not remove blanks before comments + to Oliver Corff, Sep 7, 2021 + loc * exist * algo * size * imp * + but watch out for regressions in the high-level parsers + maybe it should not even remove comments? - consider T{\" + +- In the body of conditional requests, escape sequence expansion + must not be performed if the condition is false. This implies + the first part of a request line must be expanded before + request parsing (like it is now), but expansion in the second + part must be delayed. + to Nab 8 Aug 2023 20:05:32 +0200 Subject: if/ie d condition always true + loc ** exist *** algo *** size ** imp * + +- tag.c, tag_put() should not put ASCII_HYPH into the tag file, + which happens when the tag contains "-" on the input side + weerd@ 28 Sep 2021 12:44:07 +0200 + loc * exist * algo * size * imp *** + + +************************************************************************ * missing features ************************************************************************ @@ -62,8 +112,65 @@ are mere guesses, and some may be wrong. needed for Tcl_NewStringObj(3) via wiz@ Wed, 5 Mar 2014 22:27:43 +0100 loc ** exist *** algo *** size * imp *** +- .als only works for macros in mandoc, not for user-defined strings. + Also, the "val" field in struct roffkv would have to be replaced + with a pointer to a reference-counted wrapper, and an alias + would have to point to the same wrapper as the original. + .als to undefined does nothing; the alias is not created. + .rm'ing the original leaves the alias to point to the old value. + .de .als .de changes both, but + .de .als .rm .de only changes the new value, not the alias. + Found in groffer(1) version 1.19 + Jan Stary 20 Apr 2019 20:16:54 +0200 + loc * exist ** algo ** size ** imp * + +- roff string condition comparisons fail when vars contain quotes: + .ds s ' + .if '\*s'' \&... + hard to fix because of the basic architecture (string replacement + happens before roff(7) syntax parsing) + Found in groffer(1) version 1.19 + Jan Stary 20 Apr 2019 20:16:54 +0200 + loc * exist *** algo *** size ** imp * + +- mandoc replaces all ASCII control characters except tab and line feed + with '?' during input. It would be better to replace them with + Unicode escapes in preconv_encode() or somewhere in the vicinity, + such that the already existing better replacement strings show + up in the output. Emulating groff is not desirable: groff replaces + 0x00, 0x0b, and 0x0d to 0x1f with the empty string (bad because + that's easy to overlook for the document author), 0x01 with '.' + (very confusing), and passes through 0x02 to 0x08, 0x0c, and 0x7f + raw (bad because that is insecure output). Remember that 0x07 may + need special handling because it is sometimes used for certain + delimiters, so it may need handling *after* roff.c rather than before. + reminded by John Gardner 16 Jun 2020 14:26:28 +1000 + Actually, more ASCII control characters than just 0x07 may need + later handling because they can for example be used in macro names. + So they may need handling after roff(7) processing. + pointed out by John Gardner 23 Jun 2020 18:28:08 +1000 + more info from John Gardner 29 Jun 2020 19:54:04 +1000 + loc ** exist ** algo ** size ** imp * + +- many missing features used in old groff_char(7), + some can possibly be supported + kamil at netbsd 12 Nov 2020 17:27:09 +0100 + reply + +- \s with arbitrary arg delimiters as already supported for other escapes + found following jmc@'s mail 28 Apr 2021 18:31:41 +0100 + loc * exist * algo * size * imp * + --- missing mdoc features ---------------------------------------------- +- support mixed case for section names + also, first section is not "NAME" should not appear more than once per page + Alejandro Colomar 28 Apr 2023 16:57:49 +0200 + loc * exist * algo * size * imp *** + +- .Sh and .Ss should be parsed and partially callable, see groff_mdoc(7) + reed at reedmedia dot net Sat, 21 Dec 2019 17:13:07 -0600 + loc ** exist ** algo ** size ** imp * + - .Bl -column .Xo support is missing ultimate goal: restore .Xr and .Dv to @@ -132,6 +239,13 @@ are mere guesses, and some may be wrong. --- missing man features ----------------------------------------------- +- MANWIDTH + Markus Waldeck 9 Jun 2015 05:49:56 +0200 + Laura Morales 26 Apr 2018 08:15:55 +0200 + Kamil Rytarowski 13 Nov 2020 00:19:36 +0100 + patch from Kamil 13 Nov 2020 22:37:07 +0100 + loc * exist * algo * size * imp * + - groff_www(7) .MTO and .URL These macros were used by the GNU grep(1) man page. The groff_www(7) manual page itself uses them, too. @@ -162,9 +276,15 @@ are mere guesses, and some may be wrong. --- missing eqn features ----------------------------------------------- - In a matrix, break the output line after each matrix line. - Found in the discussion at CDBUG 2015. - Suggested by Avi Weinstock. - loc * exist * algo * size * imp ** + Found in the discussion at CDBUG 2015. Suggested by Avi Weinstock. + This may not be the ideal solution after all: eqn(7) matrices + are lists of columns, so Avi's proposal would show each *column* + on its own *line*, which is likely to cause confusion. + A better solution, but much harder to implement, would be to + actually show the coordinates of column vectors on different + terminal output lines, using the clumnated output facilities + developed for .Bl -tag, .Bl -column, and also used for tbl(7). + loc * exist * algo ** size ** imp ** - The "size" keyword is parsed, but ignored by the formatter. loc * exist * algo * size * imp * @@ -190,6 +310,36 @@ are mere guesses, and some may be wrong. --- missing misc features ---------------------------------------------- +- use the default volume headers for sections with suffixes + certainly affects man(7); possibly mdoc(7)?; and also groff(1) + Alejandro Colomar 21 Aug 2022 + +- consider whether man(1) fallback code in main.c/fs_*() can find files + like man3c/fopen.3c (illumos, Solaris) and man3p/fopen.3p (POSIX) + discussed with Robert Mustacchi 21 Sep 2021 10:39:40 -0700 + loc * exist * algo ** size * imp ** + +- let makewhatis(8) follow symbolic links to dirs below READ_ALLOWED_PATH + this may be feasible using fts_set(FTS_FOLLOW) + mail to sternenseemann 19 Aug 2021 19:11:50 +0200 + loc * exist ** algo ** size * imp ** + +- tag.c, tag_put() and callers like man_validate.c, check_tag() + should not mistake "\-" as a word-ending escape sequence but + instead translate it to plain "-" in the tag name + weerd@ 28 Sep 2021 12:44:07 +0200 + loc ** exist * algo * size * imp *** + +- handle Unicode letters in tags in both HTML and terminal output + thread "section headers with diacritics" starting with + Mario Blaettermann 24 Mar 2022 18:13:23 +0100 + loc ** exist * algo * size * imp ** + +- -T man does not handle eqn(7) and tbl(7) + Stephen Gregoratto 16 Feb 2020 01:28:07 +1100 + also https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=901636 + loc ** exist ** algo ** size *** imp ** + - man -ks 1,8 route; kn@ Jul 13, 2018 orally - italic correction (\/) in PostScript mode @@ -208,6 +358,10 @@ are mere guesses, and some may be wrong. (3) undefined, just output the character -> perhaps WARNING loc *** exist ** algo ** size ** imp *** (parser reorg helps) +- man.conf(5) alias aliasname dirname or just -Mb -Mx -Mp + mail to jmc@ Mar 23, 2015 03:53:14PM +0100 + loc * exist * algo * size * imp ** + - kettenis wants base roff, ms, and me Fri, 1 Jan 2010 22:13:15 +0100 (CET) loc ** exist ** algo ** size *** imp * @@ -258,9 +412,16 @@ are mere guesses, and some may be wrong. https://github.com/schmonz/ikiwiki/compare/mandoc Amitai Schlair Mon, 19 May 2014 14:05:53 -0400 +- check compatibility with + https://git.sr.ht/~sircmpwn/scdoc + - check features of the Slackware man.conf(5) format Carsten Kunze Wed, 11 Mar 2015 17:57:24 +0100 +- look at http://www.snake.net/software/troffcvt/ (troff to HTML) + mentioned by Oliver Corff 22 Jan 2021 01:36:49 +0100 + + ************************************************************************ * formatting issues: ugly output ************************************************************************ @@ -319,8 +480,14 @@ are mere guesses, and some may be wrong. reminded by jmc@ Thu, 23 Sep 2010 18:13:39 +0059 loc * exist ** algo *** size * imp *** +- the man(7) single-font macros (e.g. .B) use .itc, + so ".B foo\c" followed by "bar" prints "bar" in bold + gbranden@ Sun, 5 Jun 2022 18:08:46 -0500 + - a line starting with "\fB something" counts as starting with whitespace and triggers a line break; found in audio/normalize-mp3(1) + This will become easier once escape sequences are represented + by syntax tree nodes. loc ** exist * algo ** size * imp ** - formatting /usr/local/man/man1/latex2man.1 with groff and mandoc @@ -338,15 +505,55 @@ are mere guesses, and some may be wrong. add a new <> block to the PDF files with /BaseFont /Courier and change the /Name from /F0 to the new font (/F5 (?)). re-reported by tb@ Mon, 16 Mar 2015 16:47:21 +0100 - loc * exist ** algo ** size * imp ** + loc ** exist ** algo ** size * imp ** --- HTML issues -------------------------------------------------------- -- format ".IP *" etc. as
    rather than
    - https://github.com/Debian/debiman/issues/67 - reminded by Pali Rohar 25 Nov 2018 14:34:26 +0100 - loc ** exist ** algo ** size * imp *** +- support the idiom .TP .IP .TP for multi-paragraph list item bodies + to: Alejandro Colomar Thu, 19 Oct 2023 16:45:21 +0200 + loc ** exist ** algo ** size ** imp ** +- .Nm without an argument and .Bx cause premature + Nab Sun, 5 Jun 2022 18:30:09 +0200 + +- .Aq Mt could set and reset "white-space: nowrap"; + Check whether other enclosure macros could profit from similar handling, + or whether that is covered by Unicode line-breaking classes WJ, ZW, GL, ZWJ. + John Gardner 25 Mar 2022 04:44:27 +1100 + +- make the HTML scaffolding customizable with -O skip=... + mail to Oliver Corff 3 Jun 2021 17:28:02 +0200 + more feedback from Oliver 3 Jun 2021 18:27:56 +0200 + more feedback from Oliver 3 Jun 2021 23:37:18 +0200 + would also be useful for + https://github.com/gbdev/rgbds-www/blob/master/ + maintainer/support/man_postproc.awk + +- .Bd -unfilled should not use monospaced font + anton@ 4 Mar 2021 08:19:35 +0100 + loc ** exist * algo * size * imp ** + +- HTML formatting of .nf should avoid
    , + even when input lines start with whitespace, + and not close and re-open 
     on .P
+  my mail to ports@ 27 Jun 2021 16:09:20 +0200
+  reported again by Mohamed Akram 25 Jun 2022 16:28:18 +0000
+  loc **  exist **  algo *  size *  imp **
+
+- tbl(7) HTML output does not implement column width specifications
+  reported by Ted Bullock 11 Jan 2022 16:00:44 -0700
+  loc *  exist *  algo ?  size ?  imp *
+
+- link from flags in the SYNOPSIS to their descriptions
+  https://github.com/gbdev/rgbds-www/blob/master/
+  maintainer/support/man_postproc.awk
+  loc *  exist *  algo **  size *  imp *
+
+- get rid of the last handful of style= attributes such that
+  Content-Security-Policy: can be enabled without unsafe-inline
+  suggested by bentley@  Nov 10, 2019 at 06:02:49AM -0700
+  loc *  exist *  algo *  size *  imp **
+
 - .Bf at the beginning of a paragraph inserts a bogus 1ex horizontal
   space, see for example random(3).  Introduced in
   http://mdocml.bsd.lv/cgi-bin/cvsweb/mdoc_html.c.diff?r1=1.91&r2=1.92
@@ -359,12 +566,10 @@ are mere guesses, and some may be wrong.
   https://github.com/Debian/debiman/issues/15
   loc *  exist *  algo **  size **  imp **
 
-- The tables used to render the three-part page headers actually force
-  the width of the  to the max-width given for .
-  Not yet sure how to fix that...
-  Observed by an Anonymous Coward on undeadly.org:
-  http://undeadly.org/cgi?action=article&sid=20140925064244&pid=1
-  loc *  exist *  algo **  size *  imp ***
+- space characters can end up in href= attributes, for example coming
+  from the first .Xr argument (where they make no sense, but still);
+  does this affect other characters, other source macros...?
+  Jackson Pauls  29 Aug 2017 16:56:27 +0100
 
 - generate  tags in HTML
   idea from florian@  Tue, 7 Apr 2015 00:26:28 +0000
@@ -372,6 +577,12 @@ are mere guesses, and some may be wrong.
 
 - check https://github.com/trentm/mdocml
 
+--- CSS issues ---------------------------------------------------------
+
+- use flexbox for .Bl-tag instead of the fragile float/clear mechanism
+  John Gardner 25 Mar 2022 04:44:27 +1100
+
+
 ************************************************************************
 * formatting issues: gratuitous differences
 ************************************************************************
@@ -417,6 +628,10 @@ are mere guesses, and some may be wrong.
   reported again by Nicolas Joly Thu, 1 Mar 2012 13:41:26 +0100 via wiz@ 5 Mar
   reported again by Franco Fichtner Fri, 27 Sep 2013 21:02:28 +0200
   reported again by Bruce Evans Fri, 17 Feb 2017 21:22:44 +0100 via bapt@
+  https://reviews.freebsd.org/D35245
+  even groff_mdoc(7) uses this: Nab Sun, 5 Jun 2022 22:16:37 +0200
+  When implementing this, try to avoid breaking existing manuals,
+  or at least fix them: Jan Stary Sun, 5 Jun 2022 22:48:05 +0200
   loc ***  exist ***  algo ***  size **  imp ***
   An easy partial fix would be to just skip the first word if it starts
   with a dot, including any following white space, when measuring.
@@ -431,6 +646,10 @@ are mere guesses, and some may be wrong.
   with .ps and .nf/.fi produce execessive blank lines, see libJudy
   and graphics/dcmtk.  The parser reorg may help with this.
 
+- The man(7) .UR macro produces UTF-8 angle brackets in -Tutf8 output mode
+  with groff, but ASCII <> with mandoc
+  Alejandro Colomar Mon, 7 Aug 2023 17:13:29 +0200 Subject: hostname
+
 - trailing whitespace must be ignored even when followed by a font escape,
   see for example
     makes
@@ -443,15 +662,18 @@ are mere guesses, and some may be wrong.
 * warning issues
 ************************************************************************
 
-- When a man(1) command returns no result and there was an -S
-  argument, check the -S argument against the list of valid
-  architectures and say "Unknown architecture AAA" rather than
-  "No entry for NNN in the manual" if there is no match.
-  Requires moving the lists of valid architectures out of
-  mdoc_validate.c such that they can be used by main.c.
-  Discussed with jmc@ 10 Aug 2018 19:20:12 +0100.
-  loc **  exist *  algo *  size *  imp **
+- shorten/simplify error messages for usage errors
+  To: deraadt@ 25 Oct 2020 23:37:01 +0100
+  loc **  exist *  algo *  size **  imp ***
 
+- warn about \\ and \. in interpretation mode
+  gbranden@, groff issue #62776, 10 Nov 2023 01:57:32 -0500
+
+- warn about output lines exceeding 80 characters
+  Alejandro Colomar Aug 22, 2022
+  not trivial because -T lint does not call any formatter
+  loc ***  exist *  algo **  size **  imp **
+
 - warn about duplicate .Sh/.Ss heads
   gre(4): Rename duplicate sections 20 Apr 2018 15:27:33 +0200
   loc *  exist *  algo *  size *  imp **
@@ -487,6 +709,10 @@ are mere guesses, and some may be wrong.
   output without intervening whitespace, in particular after a
   macro line (from the mdoclint TODO)
 
+- report double .TH in man(7) as an ERROR and let the first win
+  kristaps@  28 Mar 2021 13:30:41 +0200
+  loc *  exist *  algo *  size *  imp *
+
 - makewhatis -p complains about language subdirectories:
   /usr/local/man//ru: Unknown directory part
 
@@ -520,10 +746,6 @@ are mere guesses, and some may be wrong.
   Found by Aaron M. Ucko in the GNU Hurd via Bdale Garbee,
   https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=829624
 
-- 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.
-
 - Is it possible to further simplify ENDBODY_SPACE?
 
 - Find better ways to prevent endless loops
@@ -539,6 +761,9 @@ are mere guesses, and some may be wrong.
 * CGI issues
 ************************************************************************
 
+ - Inspect httpd(8) logs on man.openbsd.org and consider
+   whether logging can be improved, where bad syntax comes from,
+   and what needs to be done to get rid of COMPAT_OLDURI.
  - Enable HTTP compression by detecting gzip encoding and filtering
    output through libz.
  - Privilege separation (see OpenSSH).
@@ -547,6 +772,15 @@ are mere guesses, and some may be wrong.
 ************************************************************************
 * to improve in the groff_mdoc(7) macros
 ************************************************************************
+
+- delete OS release verification from .Dx, .Fx, .Nx, .Ox etc.
+  https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=629161
+  also Branden Robinson 18 Dec 2019 00:59:52 +1100
+
+- Can the distinction between .Vt and .Va be made stricter,
+  recommending .Vt extern char * Ns Va optarg ; ?
+  What about the block macro properties of .Vt in the SYNOPSIS?
+  zeurkous 25 Dec 2019 08:48:36 +0100
 
 - .Cd # arch1, arch2 in section 4 pages:
   find better way to indicate multiple architectures, maybe: