Hello Sebastien,

Sebastien Marie wrote on Sat, Jan 25, 2025 at 08:59:11AM +0100:

> the following diff adds "inf" as alias for "infinity" for
> login_getcaptime() and login_getcapnum() as it is more forward
> compatible than removing "inf" from login_getcapsize().

I did not check the code, but i certainly agree with the goal to make
the user interface more uniform and thus easier to understand and use.

> it also adds documentation for "infinity" (but not for "inf", I am
> unsure how to write it) for num, time and size argument type
> description.

Well, adding two keywords for the same feature was clearly a
historical mistake (i did not bother to check who was responsible).
The top reason why doing something like that is usually a mistake
is precisely what you observed: documenting it is awkward at best
and makes the documentation unnecessarily hard to read.

I agree with the sentiment voiced by landry@ and jmc@ that this is
a case where leaving one of the syntaxes, specifically the one that
did not yet work everywhere, undocumented, but deleting the
undocumented one from the code would cause pain for little benefit.

> I removed Va usage in size for "number" as it isn't a variable name
> (and others argument type doesn't use Va).

That removal is correct, from a markup standpoint, .Va was abused
here.

I'm inlining one additional comment regarding markup below;
feel free to use it or disregard it as you see fit.
Assuming the content of your documentation change is accurate,
the documentation change is OK schwarze@ either way.

Yours,
  Ingo


[...]
> diff --git a/share/man/man5/login.conf.5 b/share/man/man5/login.conf.5
> index 3d6d92a14c..b62b977aec 100644
> --- a/share/man/man5/login.conf.5
> +++ b/share/man/man5/login.conf.5
> @@ -379,7 +379,9 @@
>  A comma-separated list of values.
>  .\"
>  .It number
> -A number.
> +A number, or
> +.Ql infinity

While not completely wrong, .Ql is not ideal here.
The best use cases for .Ql are in-line displays of example code
or example commands.
In my opinion, the best markup use here is
  .Cm infinity
because .Cm is intended for keywords and for arguments that have
to be provided verbatim, for example on command lines or in
configuration files.

> +for no limit.
>  A leading
>  .Li 0x
>  implies the number is expressed in hexadecimal.
> @@ -400,9 +402,9 @@
>  A path name to program.
>  .\"
>  .It size
> -A
> -.Va number
> -which expresses a size.
> +A number which expresses a size, or
> +.Ql infinity
> +for no limit.
>  By default, the size is specified in bytes.
>  It may have a trailing
>  .Li b ,
> @@ -415,7 +417,9 @@
>  kilobytes, megabytes, gigabytes, or terabytes, respectively.
>  .\"
>  .It time
> -A time in seconds.
> +A time in seconds, or
> +.Ql infinity
> +for no limit.
>  A time may be expressed as a series of numbers which are added together.
>  Each number may have a trailing character to represent time units:
>  .Bl -tag -width xxx