Hyphenation in the man page

[d-e-s-o]

Here is what a certain page of the manual currently looks like:

To me, it's confusing and actively wrong to hyphenate "code snippets" (whatever you may call them) the way it is happening. I even saw NITROCLI_ being hyphenated.

I found this manual page on how to control hyphenation.

It seems we could actually define hyphenation for words including their formatting:

.hw \fBnitrocli\fR \fB\-\-login\fR

And it appears as if that may be working. But of course...oh this pain. Maintaining a list of all bold/italic words... And then there is the issue that \fB\-\-no\-capslock\fR actually has a more or less natural hyphenation point (at the third hyphen), but if we wanted to honor that the result won't be displayed as intended:

Any other ideas? I think we could hack together infrastructure that generates a list of all bold/italic words as part of make doc and includes them from the "main" man page file.

[d-e-s-o]

Oh, well, it seems that we can use \% for that purpose.

\%\fB\-\-login\fR

That may be good enough then. I wonder when we reach a point where the actual text can no longer be deciphered from all the cryptic !#&*(!@# surrounding it.

[robinkrahl]

Hmm, good point. I don’t know a solution for this problem offhand. By the way, I already planned to open a pull request with some changes to the man page after the current requests have landed: - Even worse than this wrapping problem are the code examples. My suggestion would be to hard-wrap them at 80 characters because this is a typical width for man viewers and it should also work for the PS/PDF output. - groff recommends that sentences are separated by multiple spaces or by a newline (see groff(7)). This enables cool features like better spacing when filling lines.

[d-e-s-o]

• Even worse than this wrapping problem are the code examples. My suggestion would be to hard-wrap them at 80 characters because this is a typical width for man viewers and it should also work for the PS/PDF output.

Yeah. I was just experimenting with .EX & .EE but they just blow through any margins:

(first two are wrapped in these macros, the third isn't)

• groff recommends that sentences are separated by multiple spaces or by a newline (see groff(7)). This enables cool features like better spacing when filling lines.

Interesting. Which section is that in? Can't find it off hand.

Perhaps we should get back to the initial discussion of whether we should really be writing in groff directly. If there was a neat higher level language that would just spit out that stuff and take care of the fine details itself, that would be my preferred choice.

[robinkrahl]

> - groff recommends that sentences are separated by multiple spaces > or by a newline (see groff(7)). This enables cool features like > better spacing when filling lines. Interesting. Which section is that in? Can't find it off hand.

Control characters, the items for ., space and newline.

Perhaps we should get back to the initial discussion of whether we should really be writing in groff directly. If there was a neat higher level language that would just spit out that stuff and take care of the fine details itself, that would be my preferred choice.

There are two viable options that I’m aware of: pod2man is written in and shipped with perl, scdoc is written in C and packaged for most distributions. Here are the respective man pages in their own format: https://perldoc.perl.org/pod2man.txt (at the end of the file, search for =head1) https://git.sr.ht/~sircmpwn/scdoc/blob/master/scdoc.5.scd Both would make the file easier to read, but the question is whether they would help us with the issues that actually hurt us, like wrapping code snippets.

[robinkrahl]

I had another look at the two options. As far as I see, scdoc does not support manipulating the hyphenation settings. pod2man just disables hyphenation for the entire manpage. The result does not look as bad as I thought, but I’d still prefer proper hyphenation if possible.

By the way, would you consider automatically generating the PDF file (and possibly an HTML version?) and pushing it to some webspace, e. g. GitHub Pages? Shouldn’t be too difficult with GitHub Actions.

[d-e-s-o]

Yeah, no hyphenation may be better than what we currently have.

By the way, would you consider automatically generating the PDF file (and possibly an HTML version?) and pushing it to some webspace, e. g. GitHub Pages? Shouldn’t be too difficult with GitHub Actions.

Yeah, we could do that. Ideally it would at least use the same commands / Makefile magic as we would use locally.

[robinkrahl]

For reference, sequoia uses this tool to generate man pages from clap (output).