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

[Alejandro Colomar]

Hi Branden,

On 1/10/23 22:39, G. Branden Robinson wrote:
[...]

> 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.

Merit of the original implementation goes to Ralph.

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

They do (I don't remember if all, but I think so; or at most there are a few 
exceptions).  However, I don't run `make lint` before every commit, so I may 
introduce issues from time to time, then fix them when I notice :)

> > 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

You can't do it, right?  Or do you?

> > > 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.

Yep.  Now I understand.  So yeah, I never try to guess how much the page will 
take up on screen, and just check experimentally.  And the test works nicely to 
make sure I don't forget to check (but I still may forget to run the test :).

> > > > 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.

You're right.  I don't remember what was the exact issue we had with it.
Anyway, .in just works so far. :)

> 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!

Quite right.  That's what I said to him! :P
AI learns from average, and so it produces average.

He then had a distopian theory that it could replace the average programmer in 
the future, and then good programmers would be hired to fix the bugs, costing 
much less to companies.  While I don't like the idea, I find it likely to happen 
at some point.

Cheers,

Alex

> Regards,
> Branden

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

OpenPGP_signature
Description: OpenPGP digital signature