search

walles / moar

Moar is a pager. It's designed to just do the right thing without any configuration.
Other
587 stars 17 forks source link

[Feature Request] `man` page #87

Closed hiddeninthesand closed 1 year ago

hiddeninthesand commented 2 years ago

It would be nice to have a manpage for moar

walles commented 2 years ago

Nice to have yes, but it would also require writing and maintaining it.

Docs are already maintained (to the best of my ability...) in moar --help output and in the README.md, having a man page as well would add a third place.

What's the concrete use case here @hiddeninthesand , when do you think a man page would provide additional value to what's already in --help and in the README.md?

hiddeninthesand commented 2 years ago

What's the concrete use case here @hiddeninthesand , when do you think a man page would provide additional value to what's already in --help and in the README.md?

In short, standardization. The README would only be useful to those who are looking at the repository itself, and not useful to most end users, and while the CLI help flag is always appreciated, it does seem overly brief compared to the manpage of less, which takes heavy advantage of the built in pager of the manual.

I believe ideally most of the contents of the README should be in the manpage for easy offline viewing, while the help page could be the brief version of what's held in the manual.

nkh commented 1 year ago

I second the man page request, and it's now possible to generate it from markdown.

walles commented 1 year ago

@nkh do you have an example command line to convert moar's README.md into a usable man page?

nkh commented 1 year ago

https://github.com/search?q=markdown+man+page

I'm playing with this one right now https://kristaps.bsd.lv/lowdown/ it also has a github page https://github.com/kristapsdz/lowdown

but you'll need more than just convert the moar's README, man pages have a format that should be followed. here's an example https://github.com/nkh/vimkat. There are plenty resources.

man man-pages (how did I miss that one fo so many years?!) https://itsfoss.com/linux-man-page-guide/

a few man pages that are worth looking at: bash, tmux, perlrun, ...

walles commented 1 year ago

Homebrew progress: https://github.com/Homebrew/homebrew-core/pull/106321

walles commented 1 year ago

Done.

nkh commented 1 year ago

Options should be in the man page, that's what the man page is for

nkh commented 1 year ago

long options should have double dash ... --some-option, even if one accept them on the command line as you do. and that makes it easy to know which one are short and which one are long

walles commented 1 year ago

@nkh man page updated with options, please report further man page issues separately.