.Bl -tag -width ".mdoc macro" not recognised sometimes(?)

.Bl -tag -width ".mdoc macro" not recognised sometimes(?)

[наб]

[-- Attachment #1.1: Type: text/plain, Size: 2369 bytes --]

Hi!

I'm attaching a manual that reproduces this; in short:
  .Bl -tag -compact -offset 4n -width ".Sy \e\e , \ea , \eb , \et"
works, but
  .Bl -tag -offset 4n -width ".Sy [\& Ns Ar c Ns Sy *] , [\& Ns Ar c Ns Sy * Ns Ar len Ns Sy \&]"
doesn't.

Wherein "doesn't" is defined as "I think it's just taking the literal
width of the string", which means mandoc really struggles to set this:
-- >8 --
O\bOP\bPT\bTI\bIO\bON\bNS\bS
   S\bSE\bET\bT E\bEX\bXP\bPA\bAN\bNS\bSI\bIO\bON\bN
     In all places where an arbitrary character is allowed, it can instead be
     one of the following escapes:
         \\b\\\b\, \\b\a\ba, \\b\b\bb, \\b\t\bt
         \\b\n\bn, \\b\v\bv, \\b\f\bf, \\b\r\br         The backslash, bell, backspace, tab, line
                                feed, vertical tab, form feed, and carriage
                                return characters, respectively.
         \\b\_\bO[_\bO[_\bO]]               Octal byte of value.
         \\b\_\bc                     Literal _\bc, without considering any other
                                sequences.

     Additionally, the following expansions are recognised:

         _\bf-\b-_\bt                                                           Inclusive
                                                                       range
                                                                       of all
                                                                       &c.

         [\b[:\b:_\bc_\bl_\ba_\bs_\bs:\b:]\b]                                                     Where
                                                                       _\bc_\bl_\ba_\bs_\bs
                                                                       may be
                                                                       any of
                                                                         a\bal\bln\bnu\bum\bm       alphanumeric
                                                                                     characters
                                                                         a\bal\blp\bph\bha\ba       letters
                                                                         b\bbl\bla\ban\bnk\bk       blanks
-- >8 --

This is on a fresh (like, 20 minutes old) CVS checkout,
and also affects 1.14.5-1 off Debian.

groff processes this fine in both [nt]roff modes.

Best,
наб

[-- Attachment #1.2: Type: text/plain, Size: 2315 bytes --]

.\" SPDX-License-Identifier: 0BSD
.\"
.Dd
.Dt TR 1
.Os
.
.Sh NAME
.Nm tr
.Nd transliterate bytes
.
.Sh OPTIONS
.Ss SET EXPANSION
In all places where an arbitrary character is allowed, it can instead be one of the following escapes:
.Bl -tag -compact -offset 4n -width ".Sy \e\e , \ea , \eb , \et"
.It Sy \e\e , \ea , \eb , \et
.It Sy \en , \ev , \ef , \er
The backslash, bell, backspace, tab, line feed, vertical tab, form feed, and carriage return characters, respectively.
.
.It Sy \e Ns Ar O Ns Op Ar O Ns Op Ar O
Octal byte of value.
.
.It Sy \e Ns Ar c
Literal
.Ar c ,
without considering any other sequences.
.El
.Pp
Additionally, the following expansions are recognised:
.
.Bl -tag -offset 4n -width ".Sy [\& Ns Ar c Ns Sy *] , [\& Ns Ar c Ns Sy * Ns Ar len Ns Sy \&]"
.It Ar f Ns Sy - Ns Ar t
Inclusive range of all characters between
.Ar f
and
.Ar t ,
in ascending order.
Recognised only if
.Ar t
is at least
.Ar f .
.
.It Sy [: Ns Ar class Ns Sy :]
Where
.Ar class
may be any of
.Bl -tag -compact -offset 2n -width ".Sy xdigit"
.It Sy alnum
alphanumeric characters
.It Sy alpha
letters
.It Sy blank
blanks
.It Sy cntrl
control characters
.It Sy digit
digits
.It Sy graph
graphic characters \(em printable except space
.It Sy lower
lower-case letters
.It Sy print
printable characters
.It Sy punct
punctuation characters
.It Sy space
whitespace
.It Sy upper
upper-case letters
.It Sy xdigit
hexadecimal digits
.El
These correspond directly to respective
.Pp
.St -p1003.1-2008
only guarantees equivalent relative ordering for
.Sy [:lower:]
and
.Sy [:upper:] ,
so reliance upon any given ordering of characters generated by character classes may not be portable.
.
.It Sy [= Ns Ar e Ns Sy =]
Just
.Ar e .
.St -p1003.1-2008
specifies this to be characters with the same equivalence (collation) class as
.Ar e
according to the current locale, but this is scarcely supported and most implementations just do
.Ar e .
.
.It Sy [\& Ns Ar c Ns Sy *] , [\& Ns Ar c Ns Sy * Ns Ar len Ns Sy \&]
If
.Ar len
is
.Em 0
or missing, repeat
.Ar c
until length of set matches length of the first set (not available when expanding the first set), otherwise repeat
.Ar c len
times.
.Ar len
is a decimal integer
.Pq octal if it starts with Sy 0 .
.El
.Pp
If enabled,
.Fl c
occurs directly after processing these transformations.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: .Bl -tag -width ".mdoc macro" not recognised sometimes(?)

[Jan Stary]

On Jun 05 18:16:35, nabijaczleweli@nabijaczleweli.xyz wrote:
> Hi!
> 
> I'm attaching a manual that reproduces this; in short:
>   .Bl -tag -compact -offset 4n -width ".Sy \e\e , \ea , \eb , \et"
> works, but
>   .Bl -tag -offset 4n -width ".Sy [\& Ns Ar c Ns Sy *] , [\& Ns Ar c Ns Sy * Ns Ar len Ns Sy \&]"
> doesn't.
> 
> Wherein "doesn't" is defined as "I think it's just taking the literal
> width of the string", which means mandoc really struggles to set this:

Quoting mdoc(7):

	The -width and -offset arguments accept
	macro names as described for Bd -offset,
	scaling widths as described in roff(7),
	or use the length of the given string.

Is your -width a macro name (such as Ds) as descibed for -offset? No.
Is it a scalinbg width as described in roff(7)? No.
Apparently, mandoc uses the length of the given string then.
AFAICT, that's what you told it to do.

Jan

--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: .Bl -tag -width ".mdoc macro" not recognised sometimes(?)

[наб]

[-- Attachment #1: Type: text/plain, Size: 950 bytes --]

On Sun, Jun 05, 2022 at 07:55:39PM +0200, Jan Stary wrote:
> On Jun 05 18:16:35, nabijaczleweli@nabijaczleweli.xyz wrote:
> Quoting mdoc(7):
> 
> 	The -width and -offset arguments accept
> 	macro names as described for Bd -offset,
> 	scaling widths as described in roff(7),
> 	or use the length of the given string.
> 
> Is your -width a macro name (such as Ds) as descibed for -offset? No.
> Is it a scalinbg width as described in roff(7)? No.
> Apparently, mandoc uses the length of the given string then.
> AFAICT, that's what you told it to do.

Ah, yeah, that's fair; this is, apparently, a groffism:
  If ⟨string⟩ starts with a ‘.’ (dot) immediately followed by a valid
  -mdoc macro name, interpret ⟨string⟩ and use the width of the result.
  Almost all lists in this document use this option.

My b.

> Also, mandoc -Tlint please.

-Tlint is clean, save for the empty date and long lines.

Best,
наб

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: .Bl -tag -width ".mdoc macro" not recognised sometimes(?)

[Ingo Schwarze]

Hi Nab,

Nab wrote on Sun, Jun 05, 2022 at 08:28:24PM +0200:
> On Sun, Jun 05, 2022 at 07:55:39PM +0200, Jan Stary wrote:

>> On Jun 05 18:16:35, nabijaczleweli@nabijaczleweli.xyz wrote:
>> Quoting mdoc(7):
>> 
>> 	The -width and -offset arguments accept
>> 	macro names as described for Bd -offset,
>> 	scaling widths as described in roff(7),
>> 	or use the length of the given string.
>> 
>> Is your -width a macro name (such as Ds) as descibed for -offset? No.
>> Is it a scalinbg width as described in roff(7)? No.
>> Apparently, mandoc uses the length of the given string then.
>> AFAICT, that's what you told it to do.

> Ah, yeah, that's fair; this is, apparently, a groffism:
>   If ⟨string⟩ starts with a ‘.’ (dot) immediately followed by a valid
>   -mdoc macro name, interpret ⟨string⟩ and use the width of the result.

I think you are right that this is a groff extension.
I did quick testing with Cynthia's final version of the 4.4BSD mdoc(7)
macros and they don't appear to support a full macro line (including
the leading dot) as a -width argument, or rather, they just take the
string length of the line, like mandoc(1) does.

Then again, Cynthia's version of the macros is very old and mandoc(1)
mostly aims for groff compatibility.  So supporting this feature is
desirable.  But it looks seriously complicated given the existing
mandoc code structure.  So it's certainly not a short-term task and
maybe not even feasible in the medium term but rather a long-term
goal.  Besides, the priority is moderate at best because i don't
recall having seen this often in practice.

>   Almost all lists in this document use this option.

I must admit i share Jan's curiosity in which real-world document
this feature is used.

In general, if a feature is used in important, widely used manual
pages, that raises the priority of supporting it - even though in
this case, admittedly, even a very high priority would help little
to overcome the significant difficulty of implementing it.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: .Bl -tag -width ".mdoc macro" not recognised sometimes(?)

[наб]

[-- Attachment #1: Type: text/plain, Size: 4126 bytes --]

Hi!

On Sun, Jun 05, 2022 at 09:43:13PM +0200, Ingo Schwarze wrote:
> Nab wrote on Sun, Jun 05, 2022 at 08:28:24PM +0200:
> > On Sun, Jun 05, 2022 at 07:55:39PM +0200, Jan Stary wrote:
> 
> >> On Jun 05 18:16:35, nabijaczleweli@nabijaczleweli.xyz wrote:
> >> Quoting mdoc(7):
> >> 
> >> 	The -width and -offset arguments accept
> >> 	macro names as described for Bd -offset,
> >> 	scaling widths as described in roff(7),
> >> 	or use the length of the given string.
> >> 
> >> Is your -width a macro name (such as Ds) as descibed for -offset? No.
> >> Is it a scalinbg width as described in roff(7)? No.
> >> Apparently, mandoc uses the length of the given string then.
> >> AFAICT, that's what you told it to do.
> 
> > Ah, yeah, that's fair; this is, apparently, a groffism:
> >   If ⟨string⟩ starts with a ‘.’ (dot) immediately followed by a valid
> >   -mdoc macro name, interpret ⟨string⟩ and use the width of the result.
> 
> I think you are right that this is a groff extension.
> I did quick testing with Cynthia's final version of the 4.4BSD mdoc(7)
> macros and they don't appear to support a full macro line (including
> the leading dot) as a -width argument, or rather, they just take the
> string length of the line, like mandoc(1) does.

My quick skim of 4.4BSD-Lite2 mdoc aligns with this, yeah.

> Then again, Cynthia's version of the macros is very old and mandoc(1)
> mostly aims for groff compatibility.  So supporting this feature is
> desirable.  But it looks seriously complicated given the existing
> mandoc code structure.  So it's certainly not a short-term task and
> maybe not even feasible in the medium term but rather a long-term
> goal.  Besides, the priority is moderate at best because i don't
> recall having seen this often in practice.

It's /incredibly/ useful for printing to PDF (and replaces banging out
the fonts and funny spaces manually in the -width argument),
but the value add for nroff is little (since every character in every
font is the same size; still pretty nice to not have to manually render
the macros though).

> >   Almost all lists in this document use this option.
> I must admit i share Jan's curiosity in which real-world document
> this feature is used.

This whole segment is taken directly from groff_mdoc(7) off Bullseye,
and I use it for my manuals (although that usually matches the natural
text width well enough; this tr example is an edge-case).

> In general, if a feature is used in important, widely used manual
> pages, that raises the priority of supporting it - even though in
> this case, admittedly, even a very high priority would help little
> to overcome the significant difficulty of implementing it.

Not that it's the be-all end-all, but DCS[1] says:
  116 files grepped (95 results)
(if you filter by src:groff, that accounts for
 65 files grepped (65 results))
this includes mandoc:
-- >8 --
mdocml_1.14.6-1/TODO

- 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.
-- >8 --
continuing from CVS:
-- >8 --
  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
  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@
  loc ***  exist ***  algo ***  size **  imp ***
-- >8 --

There's also one result for
  -column ".
from manpages-l10n.

Most of them are relatively simple:
  .Cm restrict_loggedin_tty Ns = Ns Ar ttyglob*
  .Ev DNSDB_API_KEY , APIKEY
  .Fl bullet
this affects them, but, well, not much (45/30, 26/21, 10/7, respectively),
my 59/13 is, decidedly, a 3.26-fold edge-case.

I'd say that the shorthand assessment from the TODO and yours, above,
are unfortunately accurate.

[1]: https://codesearch.debian.net/search?q=-width+%22.&literal=1

> Yours,
>   Ingo

Best,
наб

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: .Bl -tag -width ".mdoc macro" not recognised sometimes(?)

[Jan Stary]

> > In general, if a feature is used in important, widely used manual
> > pages, that raises the priority of supporting it - even though in
> > this case, admittedly, even a very high priority would help little
> > to overcome the significant difficulty of implementing it.
> 
> Not that it's the be-all end-all, but DCS[1] says:
>   116 files grepped (95 results)
> (if you filter by src:groff, that accounts for
>  65 files grepped (65 results))
> this includes mandoc:
> -- >8 --
> mdocml_1.14.6-1/TODO
> 
> - 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.
> -- >8 --
> continuing from CVS:
> -- >8 --
>   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
>   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@
>   loc ***  exist ***  algo ***  size **  imp ***
> -- >8 --
> 
> There's also one result for
>   -column ".
> from manpages-l10n.
> 
> Most of them are relatively simple:
>   .Cm restrict_loggedin_tty Ns = Ns Ar ttyglob*
>   .Ev DNSDB_API_KEY , APIKEY
>   .Fl bullet
> this affects them, but, well, not much (45/30, 26/21, 10/7, respectively),
> my 59/13 is, decidedly, a 3.26-fold edge-case.
> 
> I'd say that the shorthand assessment from the TODO and yours, above,
> are unfortunately accurate.
> 
> [1]: https://codesearch.debian.net/search?q=-width+%22.&literal=1

For comparison, in OpenBSD's /usr/share/man,
the only use is the self-referencing roff(7).

/usr/share/man/man1/indent.1:.Bl -tag -width "./.indent.pro" -compact
/usr/share/man/man1/make.1:.Bl -tag -width ".ARCHIVE"
/usr/share/man/man1/make.1:.Bl -tag -width ".ARCHIVE"
/usr/share/man/man1/make.1:.Bl -tag -width ".NOTPARALLEL"
/usr/share/man/man1/make.1:.Bl -tag -width ".NOTPARALLEL"
/usr/share/man/man1/make.1:.Bl -tag -width ".PRECIOUS"
/usr/share/man/man5/elf.5:.Bl -tag -width ".shstrtab"
/usr/share/man/man7/roff.7:.Bl -tag -width ".Bl -tag -width 2i" -offset indent -compact
/usr/share/man/man8/restore.8:.Bl -tag -width "./restoresymtable" -compact
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: .Bl -tag -width ".mdoc macro" not recognised sometimes(?)

[Ingo Schwarze]

Hi Nab,

Nab wrote on Sun, Jun 05, 2022 at 10:16:37PM +0200:

> It's /incredibly/ useful for printing to PDF (and replaces banging out
> the fonts and funny spaces manually in the -width argument),
> but the value add for nroff is little (since every character in every
> font is the same size; still pretty nice to not have to manually render
> the macros though).

Sure, i understand why you want to maintain a single mdoc(7) source
that yields good results with all of the following processors:

 * groff -T pdf
 * groff -T utf8
 * mandoc -T utf8
 * mandoc -T html

After all, that's the point of output-device-independent markup, isn't it?

> This whole segment is taken directly from groff_mdoc(7) off Bullseye,

Ouch.  People *will* see it there and imitate it, which does rise
the priority even more, quite apart from FreeBSD also needing it.

I'm already planning to fix the simple case of having a *single* macro
at the beginning in the not-to-distant future (which i classified as
"loc *  exist *  algo *  size *  imp ***").  Maybe there is also some
way to discard child macros in the middle without implementing
a full diversion style solution (which i classified as "loc ***
exist ***  algo ***  size **  imp ***").  We shall see...

[...]
> this includes mandoc:
> -- >8 --
> mdocml_1.14.6-1/TODO

My memory was never particularly good, but it looks like it is getting
worse...  :-/
Which only makes keeping the TODO file well-maintained more important.

> [1]: https://codesearch.debian.net/search?q=-width+%22.&literal=1

I regularly use CDN when working on library code written in C,
but it didn't so far occur to me that it's just as useful to look
for documentation markup in mdoc(7) and man(7).  Thanks for
that idea!

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv