search

lucc / nvimpager

Use nvim as a pager to view manpages, diffs, etc with nvim's syntax highlighting
Other
372 stars 20 forks source link

Use lowdown instead of pandoc for manpage generation. #38

Closed ericonr closed 3 years ago

ericonr commented 3 years ago

pandoc is quite hard to build on some platforms, due to depending on the complicated Haskell toolchain. lowdown is built with C and no dependencies besides the C library, so it's extremely portable.

This patch adopts metadata in the style supported by lowdown (at least for now, YAML blocks might yet be supported), with the -m command line options that are provided since version 0.8.1 of lowdown.

We can remove the "header" item because it's by default what man(1) displays.

Also make a DATE variable, which can be overriden when building this in environments without git available, or when building from a tarball.

https://github.com/kristapsdz/lowdown

lucc commented 3 years ago

Hello @ericonr! This is a topic that recently also came up in #37. Thank you for stepping up.

There are some points I would like to discuss or fix before merging:

  1. it seems that both #37 and this PR are concerned about "portability" or "easy of installation". But to me it looks like lowdown is available in much fewer repositories than pandoc: https://repology.org/project/pandoc/versions vs https://repology.org/project/lowdown/versions. So I suggest that we introduce a make variable in order to select the markdown processor
  2. Is there any argument why lowdown and not any of the competitors? If we introduce a new processor you just want to ask why this one. The docs of lowdown say not to use it for man pages but as I said in https://github.com/lucc/nvimpager/pull/37#issuecomment-761563445 I think markdown is fine for writing man pages.
  3. I don't understand your comment about the header not being needed. It is missing from the rendered man page when I am testing your branch on NixOS.
  4. The Authors section is missing after this change.
lucc commented 3 years ago

I tried to fix some of the points I noted above.

ericonr commented 3 years ago

Regarding 1, I think it's a reasonable solution. Haskell can be a bit hard to bootstrap / get working on environments like ARM and PowerPC, which Void Linux targets. Since ideally we'd like to be able to build the man pages for all versions of the package, a converter written in C instead of Haskell is of great help there.

Regarding 2, I didn't really like the cmark output/interface, and that's the only other one I know of.

Regarding 3, does NixOS use man-db from GNU or BSD's mandoc? Maybe it's only mandoc which adds the header automatically... I can revert that removal, then.

Regarding 4, I hadn't noticed that Pandoc added a section for author, sorry.

Thanks for the quick response! Your changes look reasonable at first glance, so thanks :)

lucc commented 3 years ago

Regarding 2, I didn't really like the cmark output/interface, and that's the only other one I know of.

There is also ronn, md2man, go-md2man and remark-man. But I am fine with lowdown, just wondering if you had any arguments. My argument for pandoc was "I already use it" :)

Regarding 3, does NixOS use man-db from GNU or BSD's mandoc? Maybe it's only mandoc which adds the header automatically... I can revert that removal, then.

man-db.

ericonr commented 3 years ago

Ok, I squashed all our commits and added a note about the generator to the README.

lucc commented 3 years ago

Thank you!

ericonr commented 3 years ago

Thanks for the quick back and forth :)