search

antonmedv / walk

Terminal file manager
MIT License
3.26k stars 90 forks source link

add a manpage #36

Closed omar-polo closed 1 year ago

omar-polo commented 1 year ago

Hi!

I've just discovered llama, but I had a really strong good first impression and I'm liking it a lot!

However, llama had the unfortunate chance of being the nth program I've seen this week without a manual page and I felt the urge to change the situation, so I wrote one. Of course, I'll be happy to help maintaining the manpage in the longer term too.

Thanks for maintaining llama!

antonmedv commented 1 year ago

Hi 👋🏻 thanks.

How this different from readme? How this man should be installed?

omar-polo commented 1 year ago

A manpage and the README are two different kind of documentation, both very important. A README is perfect to introduce the user to the project, so that they can "get" what it's about, and usually also further information about the project itself (i.e. where and how to file bug, how to contribute, how to build, ...), while a manpage is a different kind of documentation that's aimed ad describing (with a precise format) everything about the tool itself. They have some overlap, but they're different media for the documentation. Also, a manual page is usually installed in the system and so it's in sync with the program version, whereas a README is usually consulted online and it's relative to the latest version. (manpage also have other advantages: they have a semantic markdown written explicitly for documenting things -- mandoc -- that allows to export them easily to a variety of formats, to have different UIs for reading them, and finally to quickly search system-wide, and I could go on, but I've already written a wall of text, apologies! :-)

Installing the manpage it's a duty of who packages it. I don't think go provides a way to install the documentation (regardless of the form), but that's fine. The packagers who maintain this package for a distribution will take care of making it available in the user.

Just a final note that I forgot to include in my previous message: to read the manpage type man -l llama.1. When installed system-wide (usually /usr/local/share/man/man1 on linux but it may depend on the distro) it'll be available as man llama just like any other manual page.

Cheers

antonmedv commented 1 year ago

Makes sense)

another question: what with copyright?

omar-polo commented 1 year ago

force pushed because I've missed shift+arrows, g and G, plus I've did some minor reformatting (the keybindings table is a bit nicer now.)

regarding the copyright honestly I don't mind. The proposed manpage has the ISC blurb at the top simply because it's my default license for various projects (and i did a copy-paste to initialize the file), but if you prefer I can license the manpage with a different license.

omar-polo commented 1 year ago

rebased and updated to include the new stuff :)

edit: still using the ISC license; if you have preference for other licenses I'm open to change it.