man page bad

[Humm42]

rlwrap(1) is a bad man page:

• the title should be all caps—RLWRAP(1)
• the date is wrong
• where em-dashes or maybe en-dashes should be used, \-—“minus”—is
  used instead
• where hyphen-minuses should be used, \- is used
• there are blank lines in the man page, both where there should be
  nothing of that sort (eg., in NAME) and where there should be
  paragraph breaks, ie. PP
• there is trailing whitespace
• examples are just indented in the input, sometimes even in fill mode
• man page references are both bad (bold and with a blank after the
  name) and inconsistent (sometimes without the blank)
• sentence-ending full stops are not at EOLs and sometimes do and
  sometimes don’t have two blanks following
• quotes are ASCII quotes "

It is very valuable that it exists, but I’d like to stress that the
man page as-is, without talking about its content, is really, really
terrible, both in input and output.

I don’t know how such a man page could come into existence. It looks
kinda generated, but then too inconsistent for that.

Before fixing it, I’d like to hear your input on why it is that way,
as well as any special wishes (Can I use -mdoc, or does it need to
stay at -man? Em-dashes or en-dashes? If -man, options with
hyphen-minuses (as is arguably correct) or with wrong \-? Or do you
straight-up don’t care and NACK right away?).

[hanslub42]

I agree with your criticism (though I don't think it impacts the usefulness of the manpage that much)

rlwrap is an old program (I started working in it in 1999), and I initially took some existing manpage (rxvt if I remember right) as a quick and dirty template to work from. After that, I only updated the manpage piecemeal to document new rlwrap features. Wriing a few lines of troff every year is not a good way to get fluent in it.

That is why I plan to start using a tool like asciidoctor to generate the troff for me. So, while your offer to repair the manpage is appreciated, you can probably spend your time more usefully on some other project.

[Humm42]

While I recommend learning a little troff and -mdoc (for example with <https://manpages.bsd.lv/mdoc.html>), using a different language might also yield acceptable, even though not great, results. So that’s fine, I guess.

[nkh]

https://github.com/rtomayko/ronn may be another good alternative to write the man page source

[dontlaugh]

Here's another option for translating a flavor of Markdown to a manual page https://manpages.debian.org/testing/scdoc/scdoc.5.en.html

[ernstki]

I love this issue for so many reasons.

• @Humm42's high standards for man pages, and willingness to call it how they see it
  • …and offering to help make the corrections, even if that didn't pan out
• @hanslub42's being so chill about the criticism
• everyone's recommendations for avoiding writing roff

For what it's worth, I have a circa-2016 version of the rlwrap man page, as shipped with Ubuntu 20.04 and I think it's well above average for a manual page in 2024. But that's from the perspective of someone who uses a lot of "new" tools written in Rust and Go and such where they don't even bother shipping an automatically-generated man page, even though such generators do exist, let alone an artisinal, hand-crafted one, adhering to time-worn standards.

Even though I think the rlwrap man page is fine, I still bookmarked this issue and tagged it with man styleguide, so I know what to look for when I'm writing my own man page someday (although I usually let perlpod do that, and hope that it does the right thing).

Cheers, everyone. Stay classy. ;)

[ernstki]

P.S.: @hanslub42 Thanks for creating rlwrap and keeping it up all these years! I've been using it for a long time now, and I appreciate the heck out of it.

If you were to, say, switch on the sponsoring options in GitHub, I'd most assuredly buy you several beers in thanks, or coffees, or your favorite non-alcoholic, non-caffeinated alternative beverage. 🍻