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