Add scdoc manpage. - Githubissues

lucc / nvimpager

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

Other

372 stars 20 forks source link

Add scdoc manpage. #42

Closed eNV25 closed 3 years ago

eNV25 commented 3 years ago

This pull request adds a manpage in scdoc. You can make it default if you want.

This can used with make MANPAGE_PROCESSOR=scdoc.

scdoc is better than pandoc and lowndown for making manpages because it is available in many distributions: https://repology.org/project/scdoc/versions

lucc commented 3 years ago

scdoc looks nice but I do not want to maintain two versions of the man page sources: DRY!

So if you find a way to make the source portable that would be fine. Other ideas?

PS: What is the actual problem you are solving here?

eNV25 commented 3 years ago

Realistically you'll probably have to either not use scdoc or switch to scdoc entirely. Here I put both of them so you can choose. It's fine you don't merge this PR, this was just a suggestion.

In my distro pandoc pulls too many Haskell dependencies and lowdown is not avaliable in the repos, but scdoc is available in the repos. Using scdoc is more convenient for me.

lucc commented 3 years ago

This topic has come up recently: #37 & #38

I think my requirements are:

a readable format
can be used by many potential collaborators
one source only, if possible no build artefacts that have to be committed to the repo by a developer

And the arguments for markdown are:

readable
renders on github so the man page can be read and referenced there
"most" developers already know it (have written a readme file I suspect)

The reason for pandoc was that I have it installed and use it for all kinds of stuff. Lowdown was proposed as a simpler alternative. It looks like scdoc could be a good alternative, looking at its availability (it is available in all repositories where nvimpager is already packaged, for example).

I will keep this open and think about it.

@ericonr would scdoc fit your requirements from #38?

ericonr commented 3 years ago

scdoc does fit all the requirements I had :)

Thanks for mentioning me.

lucc commented 3 years ago

I decided to switch to scdoc entirely. Pandoc and lowdown support have been dropped.

I hope the scdoc will fit the requirements of all people concerned with this one and the related issues in the recent months. For me it fits because the syntax is reasonably close to markdown and the docs for the syntax are very simple and short (in contrast to groff). It seems to be rather small but still available in many repositories.

Thank you all for you help on this topic!