Re: man page width limit and example indentation (was: rseq(2) man page)

[G. Branden Robinson]

Hi Alex,

At 2023-01-10T21:29:39+0100, Alejandro Colomar wrote:
> On 1/10/23 20:03, G. Branden Robinson wrote:
> > (My former advice was 78 columns; I am revising that advice in a
> > more conservative direction having dug more deeply into tbl(1)
> > behavior.)
> 
> The terminal is 80 cols,

Not necessarily; it could be much wider.  The point I'm making is that
thanks to tbl(1) bugs, composing your table for within what you _think_
is 80 columns might cause it to overrun anyway.

> so I expect that setting a hard limit of 80 to the output should be
> fin, right?

No.  I would stay at 78n or even go down to 77 or 76 if you wanted to be
really paranoid.  But you kind of have to work at it to get to the 77
case, and the 76 is because of something I think I might do for groff
1.23.  But I'm not sure yet.

> tbl man2/perf_event_open.2 \
> | eqn -Tutf8  \
> | troff -man -t -M ./etc/groff/tmac -m checkstyle -rCHECKSTYLE=3 -ww -Tutf8
> -rLL=78n  \
> | grotty -c  \
> | col -b -p -x  \
> | (! grep -n '.\{80\}.' | sed 's,^,man2/perf_event_open.2:,' >&2)
> 
> 
> Or do you think that I should change that rule?  In the end, that grep only
> tests what users will see.  It can't measure anything else.

That's an excellent approach.  If all your man pages stay within the
80-column limit under that test, then you're fine--don't change a thing.

> If you think I can add any other test, please suggest it, because I'm
> not sure I understand it.

My lengthy exploration of the issues is because I am more the kind of
paranoid person who likes Ada and Haskell than the sort who slouches off
the end of a `switch` statement without defining a `default` case
because I'm sure I handled every scenario and if I didn't it's not
important anyway.  :-P

> As for your example, I put it in an actual man page (added TH and SH),
> and removed ll, and it still showed weird no matter what the terminal
> width was, so I don't really understand it.  However, it shows badly,
> so I hope whatever the issue is, you fix it for 1.24 :)

Well, some of it, I'm still trying to fix for 1.23.  I _still_ have not
heard back from Bertrand.  It's been two weeks.  I need to start
considering begging Werner to come out of retirement just long enough to
tag and push some tar archives.  :-O

> > Practical Advice for Man Page Authors
> > =====================================
> > 
> > A.  The 80-column limit on output line length for terminals is "safe" if
> >      tbl(1) is not used.
> 
> If it is used, it is also the only limit that makes sense, isn't it?
> Please show some actual manual page with which I can reproduce a bug
> when the terminal isn't wide enough.

Okay.  Is a mocked-up manual page good enough?  I'm attaching one.

> > > For code examples we use .in +4n rather than .RS.  I don't remember
> > > the exact reason, but it had some glitches in some cases.
> > 
> > There were no glitches that I recall, but Michael wanted the man(7)
> > source to be in a form where examples could be moved freely between
> > various contexts without needing any internal alteration.  The
> > discussion was in November 2020.  The following message and his reply
> > capture the boundaries of the problem.
> > 
> > https://lore.kernel.org/linux-man/20201113094755.bg6pl7g2s5h2w4mu@localhost.localdomain/
> 
> Ahh, thanks.  So yes, there was a glitch: RS forced a blank line, which may
> not be desirable in all cases.

Er, I don't think that's true.  `RS` forces a _break_, but not vertical
space ("blank line(s)").  I've added a demonstration to the attached man
page.

If you can point me to what you're referring to, maybe I can clarify.

> Fun thing: My dad talked to me about ChatGPT a couple of weeks ago (I
> had never heard of it).  We tried it with some code; I showed a
> function I had written, and asked it to review it.  ChatGPT proposed
> an alternative implementation, but it introduced two bugs.  :P

Wow, it really is as good as the average programmer at a tech company!

Regards,
Branden

wide-table.man
Description: Unix manual page

signature.asc
Description: PGP signature