Handwrite groff manpage, remove .md and pandoc dep.

lucc / nvimpager

Use nvim as a pager to view manpages, diffs, etc with nvim's syntax highlighting

Other

372 stars 20 forks source link

Handwrite groff manpage, remove .md and pandoc dep. #37

Closed equwal closed 3 years ago

equwal commented 3 years ago

The manpage generated by pandoc has been manually edited to be easy to maintain (rather than looking like compiler output), so that an md file + pandoc at build time isn't needed.

You will notice that there are essentially no changes to the output of the manual, except for these:

options are in bold under OPTIONS
"italics" (ie. underlines) are used instead of directional quotes, and are used when referencing options in prose.

It uses groff's man macros (not mdoc).

equwal commented 3 years ago

An edit to consider is to remove all references to .PD, which is depricated due to its implications for generating HTML. I didn't do this, because it changes the output. I'll add that commit if you would like.

.PD 0
.P
...
.PD

Specifically, it is depricated because it doesn't actually work in HTML, which doesn't support spacing between paragraphs in a meaningful way.

lucc commented 3 years ago

The reason I originally used markdown for the man page is that I did not learn groff. I also have no motivation to learn it so if I merge this change I would have trouble maintaining the man page.

Can you give me a reason why this change is needed? What is bad about the current man page? Maybe we can find another solution which does not force me to learn some obscure 50 year old markup language which is, as far as I can tell, only used for man pages.

lucc commented 3 years ago

If the size of pandoc is your only concern there are two alternatives I can think of

use a different markdown -> man processor (pandoc was just the one I knew)
provide a autogenerated nvimpager.1 file that travis or a github action can create for users who do not want to install pandoc

equwal commented 3 years ago

The reason I originally used markdown for the man page is that I did not learn groff. I also have no motivation to learn it so if I merge this change I would have trouble maintaining the man page.

Can you give me a reason why this change is needed? What is bad about the current man page? Maybe we can find another solution which does not force me to learn some obscure 50 year old markup language which is, as far as I can tell, only used for man pages.

Frankly I don't think there is much to learn in the man macros, especially with the job of maintaining a man page rather than creating one from scratch. They are hardly more complicated than markdown.

If you disagree with me on this then go ahead and close the request; while I haven't looked into other options, probably there are some other ones that could be hacked in to be used instead of pandoc if available on the system.

lucc commented 3 years ago

Yeah, I think we just disagree about roff.

If you (or someone else later on) is interested in providing an alternative to pandoc, I am open for that. One could also change the markdown a bit to make it compile with the new processor. I think the "requirements" for this are

the man page should render on github so that we can link from the readme
if possible it should still render with pandoc (because I use that a lot)

@equwal thank you for wanting to contribute, even though I am now turning down your proposal.