cabal man does not work on macOS

[andreasabel]

Re #6548:

cabal man does not work on macOS

$ cabal man 
man: invalid option -- l
man, version 1.6c

usage: man [-adfhktwW] [section] [-M path] [-P pager] [-S list]
	[-m system] [-p string] name ...

  a : find all matching entries
...
fd:13: commitBuffer: resource vanished (Broken pipe)

Also, there is a typo in an error message:

$ cabal man happy
Error: cabal: 'manpage' doesn't take any extra arguments: happy

[andreasabel]

Something that might be more portable is piping into groff:

$ cabal man --raw | groff -Tutf8 -i | less

(That looks horrible. But even the HTML rendering is horrible.)

However, the output of cabal man is not well-formatted, it seems:

$ cabal man --raw | groff -Tutf8 -i > /dev/null 2> man-errors.txt
$ cat man-errors.txt 
<standard input>:3825: warning: macro `new-repl'' not defined (probably missing space after `ne')
<standard input>:20376: warning: macro `new-build',' not defined (probably missing space after `ne')
<standard input>:20381: warning: macro `new-build' not defined (probably missing space after `ne')

Quick fix is to drop the piping into man part and make --raw the default.

Then folks can choose their OS-specific rendering of their taste.

[fgaz]

Is there any way to make man read a page from stdin (or at least from a file) on macos? does cabal man --raw | man /dev/stdin work? what about cabal man --raw > temporary_file && man temporary_file? I guess no due to the groff error?

[gbaz]

What about using nroff instead of groff as in https://unix.stackexchange.com/a/313110 ?

[andreasabel]

Here is man's man page for BSD: https://www.freebsd.org/cgi/man.cgi?query=man

@fgaz wrote:

does cabal man --raw | man /dev/stdin work?

Thanks indeed, this works, yet without formatting.

However, this is of limited use because:

$ cabal man --raw | wc
   54621  126439  871117

cabal man produces a 50kloc text! Not sure that this meets the intuitive expectations of a man page.

It seems like every option is repeated for each command. The text is highly redundant:

$ cabal man --raw | sort | uniq | wc
    1385    7760   56194

So, it is inflated by a factor of >30.

What is actually the purpose of cabal man? Dump the whole help text rather than exploring it via the --help flag?

Is it used to automatically produce man-pages for some distro?

@gbaz wrote:

What about using nroff instead of groff as in unix.stackexchange.com/a/313110 ?

Thanks, this actually produces nice formatting.

$ cabal man --raw | nroff -man /dev/stdin | less

It still suffers from the redundancy problem, though.

[andreasabel]

See #7714: I am trying to implement a pipe in Haskell to the effect of

$ cabal man --raw | nroff -man /dev/stdin | less

but for some reason it does not do what I would expect. Help wanted!

[fgaz]

We have to keep in mind that nroff/groff could be absent too! For example in NixOS:

$ cabal man --raw | nroff -man /dev/stdin
The program 'nroff' is not in your PATH. You can make it available in an
ephemeral shell by typing:
  nix-shell -p groff

Should the command depend on the platform?

Furthermore, less may not be the user's $PAGER

[gbaz]

I think this is a lot of hoops to jump through for a rarely used command that doesn't seem particularly important for most purposes? I'm in favor of doing a basic fix to it, but unless we already have infrastructure in place to lookup a pager etc, probably overkill.

[fgaz]

Oh for sure, I just meant that the fix shouldn't be at the expense of other users, like in linux, where man is ubiquitous and respects $PAGER, but groff isn't as much.

I wasn't actually proposing to check for $PAGER, just to case on the platform, which would be strictly an improvement for all users. The pager issue was an argument for keeping man where possible.

edit: well ok, nroff is actually a dependency of man, it's just that NixOS doesn't expose dependencies by default, which isn't what the majority does. So I guess this affects less platforms than I thought, and only the $PAGER regression remains, which is minor compared to making the command work on all platforms

[andreasabel]

The output of cabal man --raw is producing the following problems when piped into nroff -man:

• The sequence 'ne, if placed a the beginning of a line, seems to invoke a macro:

  cabal.man:3825: warning: macro `new-repl'' not defined (probably missing space after `ne')
  

  This happens when quotes like 'new-repl' etc. end up at the beginning of the line by chance.
  A fix is to not have a line break before 'ne, but this is maybe not so obvious how to realize this.
• Problems with .R:

  `R' is a string (producing the registered sign), not a macro.
  

  According to man node produces warnings on macOS nodejs/node#18434 (comment) the prefix .R is superfluous ("pretty silly") and can be deleted. This removes the warnings.

[hasufell]

apparently, this also happens on BSD

[fgaz]

@hasufell feel free to review #7726 ;)