using the TQ macro

using the TQ macro

[G. Branden Robinson]

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

Hi Alex,

I pulled man-pages Git and saw this.

commit 6fdb1c03075b31364968bcccf472a4d4a86952a6 (origin/master, origin/HEAD)
Author: Alejandro Colomar <alx@kernel.org>
Date:   Sun Oct 22 14:57:46 2023 +0200

    man*/: ffix (Use '.TQ' where appropriate)

    When there are multiple tags for a paragraph, using a single TP and
    separating the tags with commas makes the man(7) source more complex.
    It also has a disadvantage: when searching through a manual page,
    heuristics such as "   --option" don't work so well.

    By using GNU's TQ, we simplify the source of the pages, and improve the
    ability to search them.

    Signed-off-by: Alejandro Colomar <alx@kernel.org>

I wanted to offer my support for it, in part since Ingo was so critical
over on the groff list.[1]

Your use of `TQ` seems entirely idiomatic here.  You're right that it
makes the man(7) source less complex, but it also emphasizes even to the
casual reader the parallel syntax of `TP` and `TQ`, which inexpert man
page authors will surely appreciate.

Another advantage is that if people get carried away with the former
approach, creating a lengthy paragraph tag, they might overrun the line
length, which would be really ugly.

I don't share Ingo's concern that this style of stacking paragraphing
tags is inherently wasteful of screen real estate.  Man pages are, and
have always been--going back to the 1971 First Edition Unix
manual--pretty sparse in their use of text on the page.[2]  In part,
this helps the eye of the reader to navigate the content.

Ingo would have more of a point if someone had a dozen tags stacked up
for one paragraph, but doing so would suggest other problems; either
your interface doesn't need that many ways to say the same thing and you
should retire and de-document some forms of expression; something should
be parameterized (i.e., turned into a hyphenated noun phrase in
italics); or you're packing too many different things into one item's
presentation.  Not everything can be solved with markup: sometimes we
have to do the dirty work of writing clearly in natural language.

But I don't see any problem like that in the Linux man-pages, so I think
his criticism was not entirely apropos.  Also, as I noted on the groff
list, he seems to have forgotten that `TQ` takes no arguments, so a
formatter that doesn't support it won't throw any text away.

I also like your suggestion that if we really want to economize on
space, we could present a command's long option form before its short,
old-style Unix synonym, which will work well when the short option (plus
its argument, if any) fits within the space for the paragraph tag.  This
might be a good idea for another reason; in GNU user space, the long
option is the much more self-documenting form, and the single-character
option name a kind of "expert mode" alternative.  As a general rule,
when presenting technical material, one should not lead with "expert
mode".

Another benefit of this commit was that it made my "prepare for MR"
commit simpler.  So I reckon this is a good time to re-submit that (and
the big sed-driven MR migration humdinger; you can look for that soon.

Regards,
Branden

[1] https://lists.gnu.org/archive/html/groff/2023-10/msg00024.html
[2] https://www.bell-labs.com/usr/dmr/www/1stEdman.html

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

Re: using the TQ macro

[Alejandro Colomar]

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

Hi Branden,

On Wed, Oct 25, 2023 at 09:11:03AM -0500, G. Branden Robinson wrote:
> Hi Alex,
> 
> I pulled man-pages Git and saw this.
> 
> commit 6fdb1c03075b31364968bcccf472a4d4a86952a6 (origin/master, origin/HEAD)
> Author: Alejandro Colomar <alx@kernel.org>
> Date:   Sun Oct 22 14:57:46 2023 +0200
> 
>     man*/: ffix (Use '.TQ' where appropriate)
> 
>     When there are multiple tags for a paragraph, using a single TP and
>     separating the tags with commas makes the man(7) source more complex.
>     It also has a disadvantage: when searching through a manual page,
>     heuristics such as "   --option" don't work so well.
> 
>     By using GNU's TQ, we simplify the source of the pages, and improve the
>     ability to search them.
> 
>     Signed-off-by: Alejandro Colomar <alx@kernel.org>
> 
> I wanted to offer my support for it, in part since Ingo was so critical
> over on the groff list.[1]

Thanks :)

> 
> Your use of `TQ` seems entirely idiomatic here.  You're right that it
> makes the man(7) source less complex, but it also emphasizes even to the
> casual reader the parallel syntax of `TP` and `TQ`, which inexpert man
> page authors will surely appreciate.
> 
> Another advantage is that if people get carried away with the former
> approach, creating a lengthy paragraph tag, they might overrun the line
> length, which would be really ugly.
> 
> I don't share Ingo's concern that this style of stacking paragraphing
> tags is inherently wasteful of screen real estate.  Man pages are, and
> have always been--going back to the 1971 First Edition Unix
> manual--pretty sparse in their use of text on the page.[2]  In part,
> this helps the eye of the reader to navigate the content.
> 
> Ingo would have more of a point if someone had a dozen tags stacked up
> for one paragraph, but doing so would suggest other problems; either
> your interface doesn't need that many ways to say the same thing and you
> should retire and de-document some forms of expression; something should
> be parameterized (i.e., turned into a hyphenated noun phrase in
> italics); or you're packing too many different things into one item's
> presentation.  Not everything can be solved with markup: sometimes we
> have to do the dirty work of writing clearly in natural language.
> 
> But I don't see any problem like that in the Linux man-pages, so I think
> his criticism was not entirely apropos.  Also, as I noted on the groff
> list, he seems to have forgotten that `TQ` takes no arguments, so a
> formatter that doesn't support it won't throw any text away.
> 
> I also like your suggestion that if we really want to economize on
> space, we could present a command's long option form before its short,
> old-style Unix synonym, which will work well when the short option (plus
> its argument, if any) fits within the space for the paragraph tag.  This
> might be a good idea for another reason; in GNU user space, the long
> option is the much more self-documenting form, and the single-character
> option name a kind of "expert mode" alternative.  As a general rule,
> when presenting technical material, one should not lead with "expert
> mode".
> 
> Another benefit of this commit was that it made my "prepare for MR"
> commit simpler.  So I reckon this is a good time to re-submit that (and
> the big sed-driven MR migration humdinger; you can look for that soon.

Heh, I guessed it would :p

BTW, I just checked and Gentoo still doesn't consider 1.23.0 stable
enough <https://packages.gentoo.org/packages/sys-apps/groff>.  :|

Although with word from Ingo that he has urgent plans to implement MR, I
may merge the MR patch earlier.

Cheers,
Alex

> 
> Regards,
> Branden
> 
> [1] https://lists.gnu.org/archive/html/groff/2023-10/msg00024.html
> [2] https://www.bell-labs.com/usr/dmr/www/1stEdman.html



-- 
<https://www.alejandro-colomar.es/>

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

groff 1.23.0 stability (was: using the TQ macro)

[G. Branden Robinson]

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

Hi Alex,

At 2023-10-25T17:08:19+0200, Alejandro Colomar wrote:
> BTW, I just checked and Gentoo still doesn't consider 1.23.0 stable
> enough <https://packages.gentoo.org/packages/sys-apps/groff>.  :|

I don't understand that claim.  1.23.x is as stable as it can be; there
have been no point releases.  Its behavior is not changing based on the
calendar.  I have to assume that there are either changes since 1.22.4
documented in NEWS (and if not, that's probably a bug) that they're
concerned about, or they're worried the broader community hasn't gotten
enough exposure to it yet.  repology.org has been sitting at 64
instances of groff 1.23.0 for weeks now; I think pretty much everyone
who's going to adopt it has done so by now.

CCing Sam James (the only Gentoo developer I know by name, because he's
been active some of the same places I have been) in case he can throw
some light on this.

Regards,
Branden

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

Re: groff 1.23.0 stability (was: using the TQ macro)

[Sam James]

"G. Branden Robinson" <g.branden.robinson@gmail.com> writes:

> [[PGP Signed Part:Undecided]]
> Hi Alex,
>
> At 2023-10-25T17:08:19+0200, Alejandro Colomar wrote:
>> BTW, I just checked and Gentoo still doesn't consider 1.23.0 stable
>> enough <https://packages.gentoo.org/packages/sys-apps/groff>.  :|
>

Alex, this is based on a misunderstanding of how our process works -- please
CC me if you have questions or if something looks off in future, so I
can explain/help if required.

> I don't understand that claim.  1.23.x is as stable as it can be; there
> have been no point releases.  Its behavior is not changing based on the
> calendar.

The standard rule in Gentoo is 30 days after something has been released
before it's considered for "stabilisation". We wait longer for critical
packages like groff to give more time for any reported bugs in "~arch"
(our testing area, which a lot of users participate in). It is generally
not a comment on upstream stability at all.

> I have to assume that there are either changes since 1.22.4
> documented in NEWS (and if not, that's probably a bug) that they're
> concerned about, or they're worried the broader community hasn't gotten
> enough exposure to it yet.  repology.org has been sitting at 64
> instances of groff 1.23.0 for weeks now; I think pretty much everyone
> who's going to adopt it has done so by now.
>

... in this case, the only blockers were really:
* me having https://github.com/Perl/perl5/issues/21239
  in the back of my head (wasn't paying full attention, just knew I had
  to go back and read any developments/further comments) 

* needing to look into a reported failure
  (https://bugs.gentoo.org/910226) - which looks like it should be fixed
  when we update our version of openvswitch (or we backport the patch,
  or both)

> CCing Sam James (the only Gentoo developer I know by name, because he's
> been active some of the same places I have been) in case he can throw
> some light on this.

Happily! Please feel free to loop me in if you reckon I can give input
on things.

So, all in all, none of this is a reflection on upstream, just a mix
of: how we do things normally (waiting a bit post-release unless there's
some serious regression in our stable version), waiting a bit longer
because it's a critical package (sometimes 60 days, sometimes a bit
longer), and not getting around to looking at that openvswitch bug yet.

I promise I would report any problems if I determined they were in any
way an upstream issue :)

Thanks for reaching out.

>
> Regards,
> Branden
>

best,
sam

Re: groff 1.23.0 stability (was: using the TQ macro)

[Alejandro Colomar]

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

Hi Sam!

On Tue, Oct 31, 2023 at 04:38:13AM +0000, Sam James wrote:
> "G. Branden Robinson" <g.branden.robinson@gmail.com> writes:
> > At 2023-10-25T17:08:19+0200, Alejandro Colomar wrote:
> >> BTW, I just checked and Gentoo still doesn't consider 1.23.0 stable
> >> enough <https://packages.gentoo.org/packages/sys-apps/groff>.  :|
> >
> 
> Alex, this is based on a misunderstanding of how our process works -- please
> CC me if you have questions or if something looks off in future, so I
> can explain/help if required.
> 
> > I don't understand that claim.  1.23.x is as stable as it can be; there
> > have been no point releases.  Its behavior is not changing based on the
> > calendar.
> 
> The standard rule in Gentoo is 30 days after something has been released
> before it's considered for "stabilisation". We wait longer for critical
> packages like groff to give more time for any reported bugs in "~arch"
> (our testing area, which a lot of users participate in). It is generally
> not a comment on upstream stability at all.

Yep, I understand it's just about your use in combination with other
packages in your distribution.  What I'm not sure is if by default
Gentoo installs the stable packages or the testing ones.  If you install
by default the stable one, I wouldn't want to force a dependency on a
package that you don't yet install by default.

> 
> > I have to assume that there are either changes since 1.22.4
> > documented in NEWS (and if not, that's probably a bug) that they're
> > concerned about, or they're worried the broader community hasn't gotten
> > enough exposure to it yet.  repology.org has been sitting at 64
> > instances of groff 1.23.0 for weeks now; I think pretty much everyone
> > who's going to adopt it has done so by now.
> >
> 
> ... in this case, the only blockers were really:
> * me having https://github.com/Perl/perl5/issues/21239
>   in the back of my head (wasn't paying full attention, just knew I had
>   to go back and read any developments/further comments) 
> 
> * needing to look into a reported failure
>   (https://bugs.gentoo.org/910226) - which looks like it should be fixed
>   when we update our version of openvswitch (or we backport the patch,
>   or both)

So, if the Linux man-pages forces a dependency of groff-1.23.0, would it
be problematic for Gentoo before you declare it stable, or would it be
fine?

> 
> > CCing Sam James (the only Gentoo developer I know by name, because he's
> > been active some of the same places I have been) in case he can throw
> > some light on this.
> 
> Happily! Please feel free to loop me in if you reckon I can give input
> on things.
> 
> So, all in all, none of this is a reflection on upstream, just a mix
> of: how we do things normally (waiting a bit post-release unless there's
> some serious regression in our stable version), waiting a bit longer
> because it's a critical package (sometimes 60 days, sometimes a bit
> longer), and not getting around to looking at that openvswitch bug yet.

Yeah, the quality of groff-1.23.0 is way better than 1.22.4.  I'm just
worried that forcing distros to use it too early might be detrimental.

Cheers,
Alex

> 
> I promise I would report any problems if I determined they were in any
> way an upstream issue :)
> 
> Thanks for reaching out.
> 
> >
> > Regards,
> > Branden
> >
> 
> best,
> sam
> 

-- 
<https://www.alejandro-colomar.es/>

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

Re: groff 1.23.0 stability (was: using the TQ macro)

[Sam James]

Alejandro Colomar <alx@kernel.org> writes:

> [[PGP Signed Part:Undecided]]
> Hi Sam!
>
> On Tue, Oct 31, 2023 at 04:38:13AM +0000, Sam James wrote:
>> "G. Branden Robinson" <g.branden.robinson@gmail.com> writes:
>> > At 2023-10-25T17:08:19+0200, Alejandro Colomar wrote:
>> >> BTW, I just checked and Gentoo still doesn't consider 1.23.0 stable
>> >> enough <https://packages.gentoo.org/packages/sys-apps/groff>.  :|
>> >
>> 
>> Alex, this is based on a misunderstanding of how our process works -- please
>> CC me if you have questions or if something looks off in future, so I
>> can explain/help if required.
>> 
>> > I don't understand that claim.  1.23.x is as stable as it can be; there
>> > have been no point releases.  Its behavior is not changing based on the
>> > calendar.
>> 
>> The standard rule in Gentoo is 30 days after something has been released
>> before it's considered for "stabilisation". We wait longer for critical
>> packages like groff to give more time for any reported bugs in "~arch"
>> (our testing area, which a lot of users participate in). It is generally
>> not a comment on upstream stability at all.
>
> Yep, I understand it's just about your use in combination with other
> packages in your distribution.  What I'm not sure is if by default
> Gentoo installs the stable packages or the testing ones.  If you install
> by default the stable one, I wouldn't want to force a dependency on a
> package that you don't yet install by default.

That's no problem - we regularly have things which require a new
dependency to become stable and it's a nudge if it hasn't happened anyway.

(See below).

>
>> 
>> > I have to assume that there are either changes since 1.22.4
>> > documented in NEWS (and if not, that's probably a bug) that they're
>> > concerned about, or they're worried the broader community hasn't gotten
>> > enough exposure to it yet.  repology.org has been sitting at 64
>> > instances of groff 1.23.0 for weeks now; I think pretty much everyone
>> > who's going to adopt it has done so by now.
>> >
>> 
>> ... in this case, the only blockers were really:
>> * me having https://github.com/Perl/perl5/issues/21239
>>   in the back of my head (wasn't paying full attention, just knew I had
>>   to go back and read any developments/further comments) 
>> 
>> * needing to look into a reported failure
>>   (https://bugs.gentoo.org/910226) - which looks like it should be fixed
>>   when we update our version of openvswitch (or we backport the patch,
>>   or both)
>
> So, if the Linux man-pages forces a dependency of groff-1.23.0, would it
> be problematic for Gentoo before you declare it stable, or would it be
> fine?

Yeah, this is fine - go ahead. The only issue would really be if
groff-1.23.0 was causing many issues which would prevent us from
unleashing newer man-pages any time soon, but that is not the case.

>
>> 
>> > CCing Sam James (the only Gentoo developer I know by name, because he's
>> > been active some of the same places I have been) in case he can throw
>> > some light on this.
>> 
>> Happily! Please feel free to loop me in if you reckon I can give input
>> on things.
>> 
>> So, all in all, none of this is a reflection on upstream, just a mix
>> of: how we do things normally (waiting a bit post-release unless there's
>> some serious regression in our stable version), waiting a bit longer
>> because it's a critical package (sometimes 60 days, sometimes a bit
>> longer), and not getting around to looking at that openvswitch bug yet.
>
> Yeah, the quality of groff-1.23.0 is way better than 1.22.4.  I'm just
> worried that forcing distros to use it too early might be detrimental.
>
> Cheers,
> Alex
>
>> 
>> I promise I would report any problems if I determined they were in any
>> way an upstream issue :)
>> 
>> Thanks for reaching out.
>> 
>> >
>> > Regards,
>> > Branden
>> >
>> 
>> best,
>> sam
>> 

thanks,
sam

Re: groff 1.23.0 stability (was: using the TQ macro)

[Alejandro Colomar]

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

Hi Sam, Branden,

On Mon, Nov 13, 2023 at 11:48:29PM +0000, Sam James wrote:
...

> That's no problem - we regularly have things which require a new
> dependency to become stable and it's a nudge if it hasn't happened anyway.
> 
> (See below).

...

> Yeah, this is fine - go ahead. The only issue would really be if
> groff-1.23.0 was causing many issues which would prevent us from
> unleashing newer man-pages any time soon, but that is not the case.

Thanks!

Branden: wind calm, visibility 10, sky clear.  ;)

Cheers,
Alex

-- 
<https://www.alejandro-colomar.es/>

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