Hello, Jinwook Jeong wrote on Sun, Oct 12, 2025 at 04:00:08AM +0900:
> The "Callable" property is described in > https://man.freebsd.org/cgi/man.cgi?mdoc#MACRO_SYNTAX > > Let's get straight to an example. > > > example.roff: > > .Dd September 1, 2025 > .Dt EXAMPLE 1 > .Os > .Sh NAME > .Nm Example > .Nd does absolutely nothing, but has a man page > .Sh DESCRIPTION > %N > .Pp > .Ql %N > > > The `%N` is _not_ a callable macro. > > > mandoc lint: > > $ mandoc -Tlint example.roff > mandoc: example.roff:10:5: WARNING: macro neither callable nor escaped: %N I can confirm this behaviour with mandoc-current on OpenBSD-current - which is hardly surprising because FreeBSD ships a very recent mandoc in the newest FreeBSD version and since .Rs submacro parsing has been stable in mandoc for a long time. > mandoc output: > > $ mandoc -Tutf8 example.roff > ... > DESCRIPTION > %N > > ‘%N’ I get the same output with mandoc-current on OpenBSD-current, and this output seems reasonable to me since it clearly indicates to the page author during proof-reading of the formatted text that something is likely not working as they intended. > groff output: > > $ groff -mdoc -Tutf8 example.roff > ... > DESCRIPTION > %N > > ‘ I can confirm that output with groff-1.23.0 on OpenBSD-current; i did not test with groff-current. This output certainly does not look desirable to me, for two reasons: omitting the terminating quote seems quite wrong whatever may be done with %N, and silently printing nothing whatsoever for %N feels unhelpful, too: silent loss of information, silently not printing anything where the author likely intended something, is usually not a good idea. > Both appears to detect that the usage of `%N` is outside the mdoc spec. Not so sure about that part. Definitely, mandoc does detect and report the syntax error. However, groff does not report the problem, and from black-box testing, i see no indication that it even detects the problem. It looks more like the groff code maybe gets internally confused and barrels on without even noticing its own confusion. I did not look at the groff_mdoc(7) implementation yet to understand the issue better. > The difference is that `mandoc` prints `%N` verbatim whereas `groff` > swallows `%N` and prints incomplete result. Confirmed. > Is `groff` working intended? or should it work like `mandoc` does? My opinion is: No, Yes. I cannot say yet whether fixing groff might be easy or hard. > I encountered the issue when fiddling with man-db `man` and `date` > command manual. Thanks for reporting. I added your test file in the directory /usr/src/regress/usr.bin/mandoc/mdoc/Rs/Todo in my private copy of the mandoc test suite. It seems unlikely that i will come around to fix this in a timely manner since i'm woefully behind on significantly more important tasks. > The example is a minimized version of `date.1`. > https://github.com/apple-oss-distributions/shell_cmds/blob/shell_cmds-326/date/date.1 In that file, %N has nothing to do with .Rs, but is a strftime(3)-like conversion specifier, so it should be written as \&%N. It appears Apple (legally) pilfered that file from FreeBSD, as is their habit. The same problem is present in the FreeBSD main branch. Feel free to submit the macro cleanup patch appended below to FreeBSD. If you do that, than the bugfix will probably also get merged to macOS one or two decades later. If you know about any way to submit patches to Apple, i'd like to learn about that. So far, i never had any luck getting any bugfix patch into any Apple product, nor even to get any answer from them whatsoever. Thank you, Ingo > Testing enviornment: > macOS 15.7 > groff 1.23.0 (Homebrew) > mandoc 1.14.6_1 (Homebrew) commit dd8001ff4309ecee90b4ea79e98600619a5b7e89 Author: Ingo Schwarze <[email protected]> Date: Tue Oct 21 18:15:41 2025 +0200 Minor macro cleanup, no text change. * The string "%N" is the name of a non-callable mdoc(7) macro, so it needs to be escaped, or (at least some versions of) groff fail to print it. * No before Pq has no effect. * Tn is deprecated and has no effect with mandoc. The &N escaping minibug was reported by Jinwook Jeong <[email protected]> on <[email protected]>. diff --git a/bin/date/date.1 b/bin/date/date.1 index b86a660a924d..ec2591e1eee4 100644 --- a/bin/date/date.1 +++ b/bin/date/date.1 @@ -143,7 +143,7 @@ values are .Cm minutes , .Cm seconds , and -.Cm ns No Pq for nanoseconds . +.Cm ns Pq for nanoseconds . The date and time is formatted to the specified precision. When .Ar FMT @@ -194,9 +194,7 @@ and can be specified in decimal, octal, or hex. Print the date and time of the last modification of .Ar filename . .It Fl u -Display or set the date in -.Tn UTC -(Coordinated Universal) time. +Display or set the date in UTC (Coordinated Universal) time. By default .Nm displays the time in the time zone described by @@ -328,7 +326,7 @@ The format string may contain any of the conversion specifications described in the .Xr strftime 3 manual page and -.Ql %N +.Ql \&%N for nanoseconds, as well as any arbitrary text. A newline .Pq Ql \en @@ -507,8 +505,7 @@ sets the date to may be used on one machine to print out the date suitable for setting on another. .Qq ( Li "+%m%d%H%M%Y.%S" -for use on -.Tn Linux . ) +for use on Linux.) .Pp The command: .Pp @@ -591,10 +588,10 @@ flag is compatible with .St -iso8601 . .Pp The -.Ql %N +.Ql \&%N conversion specification for nanoseconds is a non-standard extension. It is compatible with GNU date's -.Ql %N . +.Ql \&%N . .Sh HISTORY A .Nm @@ -615,6 +612,6 @@ flag was added in .Fx 12.0 . .Pp The -.Ql %N +.Ql \&%N conversion specification was added in .Fx 14.1 .
