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. 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.
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
Regards, Branden
Cheers, Alex
[1] https://savannah.gnu.org/bugs/index.php?62471 [2] https://savannah.gnu.org/bugs/index.php?61597 [3] https://savannah.gnu.org/bugs/index.php?63449
-- <http://www.alejandro-colomar.es/>
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
