[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Alejandro Colomar
Subject: Re: man page width limit and example indentation (was: rseq(2) man page)
Date: Wed, 11 Jan 2023 00:30:16 +0100
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.6.0

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.

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

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.





Attachment: OpenPGP_signature
Description: OpenPGP digital signature

reply via email to

[Prev in Thread] Current Thread [Next in Thread]