[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: Tue, 10 Jan 2023 21:29:39 +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 20:03, G. Branden Robinson wrote:
[formatting issues; CC list trimmed, added groff@]

At 2023-01-06T23:57:35+0100, Alejandro Colomar wrote:
On 1/6/23 21:57, Mathieu Desnoyers wrote:
The line above goes beyond column 80 in formatted output.  That's a
hard limit for manual pages.

The hard limit should be thought of as somewhat lower--as low as 76--in
pages that use tbl(1).  This is due to a groff design issue that goes
back 30 years.[1]  I will try to resolve it for groff 1.24 but it might
be the biggest challenge I've yet undertaken with the codebase.  It will
require a redesign of how tbl(1) gets information through to the
terminal output driver, grotty(1).

(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, so I expect that setting a hard limit of 80 to the output should be fin, right?

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.

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

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


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.


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.

There is a limit to Michael's solution, but if the Linux man pages don't
go bonkers with deeply nested regions, it's workable.  (If they do, then
migrating examples may need to be reformatted due to changes in the
available line length; the more you indent, the less there is.)

It would please me to come up with a way, possibly a groff man(7)
extension (smaller than most, like recognition of a second argument to
the `RS` macro), that would enable "purer" man(7) input without recourse
to troff requests.

...but it might not be worth it.  If you relocate an example from a
heavily-indented region to a less-indented one, you _gain_ some line
length, and this is not an error condition.  Abbreviations or
compromises you made in an example's formatting might no longer be
necessary, and only an engaged human brain will detect the fact that the
example can be recast to leverage the added line capacity.

I don't think ChatGPT is to up that sort of thing.  Yet.

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






Attachment: OpenPGP_signature
Description: OpenPGP digital signature

reply via email to

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