Add man (1) entry

[gyscos]

Adding a man entry would be a nice improvement for when fd is packaged (And possibly some day for when installed via cargo install?).

[sharkdp]

Good suggestion, thank you!

Does anyone know a modern/easy way to write man pages? For another project, I was using pandoc to create them from markdown pages (see here), but I'm not sure if that's also the best option here.

In particular, I would like to avoid having to keep man page and --help text in sync manually.

[gyscos]

It seems ripgrep, the other big rust project, uses pandoc as well.
As for clap, it's an open issue: clap-rs/clap#552.

[pickfire]

@sharkdp I know how to write man pages in both roff and mandoc (which I had learned from suckless). Need some help?

It would be really nice if it wasn't written in pandoc first since some of the man pages generated by pandoc is generally ugly (like code snippets).

[sharkdp]

@sharkdp I know how to write man pages in both roff and mandoc (which I had learned from suckless). Need some help?

Yes, that would be great!

(Side remark: Concerning the EXAMPLES section, see #73.)

[pickfire]

@sharkdp Which one would you like it to be in? roff (might be troff) or mandoc?

[sharkdp]

@pickfire I don't know neither of these tools, so I would trust your judgement.

[pickfire]

@sharkdp Here they are, I have both of them, I think it will be easier to work with the one that is easily understandable in this case. I will do a simple comparison of both of them.

roff (troff)

• ancient general typesetting but still widely used
• simple and easy but looks kinda messy for me sometimes
• powerful (diagrams...) but man pages are here and there

fd-roff.1

mdoc

• designed for man pages
• stateful but longer to write
• Cool docs available at http://manpages.bsd.lv/
• Neovim switched to mdoc at Rewrite English man pages in mdoc, update for Nvim (old) neovim/neovim#2395

fd-mdoc.1

So still up to you to choose which one do you all wanted to include. By the way, I haven't fully included all the examples and I wrote some of the options myself (not from fd --help but it's kinda a cool feature that I had just discovered).

[sharkdp]

@pickfire Thank you very much! mdoc looks cool, but is it fully supported on Linux?

I found this on Wikipedia:

While mandoc works well with the mdoc manuals used in the BSD Operating Systems, it poorly handles older troff macros such as man, me, and the roff language itself. This makes it a poor fit for Linux distributions, which primarily use man troff macros and low-level roff for their manual pages.

Also, if I open fd-mdoc.1 with man -l on my system, it has this header:

FD(1)                BSD General Commands Manual               FD(1)

NAME
     fd — find files

SYNOPSIS
     fd [-HIsaLp0hV] [-d depth] [-t filetype] [-e ext] [-c when]
        [-j num] [pattern] [path]

DESCRIPTION
     fd is a simple, fast and user-friendly alternative to find(1).

[pickfire]

@sharkdp Yeah, it have that header. Just tell me which one you like (probably easier to maintain for you all), can I work on this as part of my hacktoberfest?

Note: Maybe I will find another task here as well.

[sharkdp]

Ok, if I have to choose, I'd go with roff for now.

can I work on this as part of my hacktoberfest

Of course! Any progress on this (or any other task) would be greatly appreciated.

[pickfire]

@sharkdp Anything that needs to improve over the existing? Like addon to examples or modify the options to suit fd --help?

[sharkdp]

The current one looks pretty great already. Would you like to open a pull request to add this?

I have a couple of comments (like the name of the executable in the synopsis 😃), but I think this can be better discussed in the pull request / review.

[dashohoxha]

In the past I have used http://rtomayko.github.io/ronn/ for writing man pages. They look like this:

• https://gitlab.com/EasyGnuPG/egpg/blob/gnupg-2.2/man/egpg.1.ronn
• https://gitlab.com/EasyGnuPG/egpg/tree/gnupg-2.2/man

[pickfire]

@dashohoxha I think installing ruby and the dependencies are possible but I think it would be better to write it in roff or mandoc format rather than writing it in a format that requires external ruby dependency.

If anything, generating man pages from rust / clap would be nice since it already depends on rust. Or otherwise, writing roff markup would not be that hard as well.

[dashohoxha]

ronn format is like markdown. From it you can also generate an HTML page, besides a man page. My reasons for using it was to avoid writting roff markup (which seems hard and unfamiliar to me), and for being able to generate other formats as well (like HTML).

[pickfire]

@dashohoxha But why ruby dependency? We need to have installed ruby + ruby-ronn which requires additional ~12 MB dependencies as well as reducing it's portability possibly.

[dashohoxha]

I am for the simplicity and universality of the markdown format, not for inceasing dependancies. If you can find (or build) a rust tool that does the same thing as ronn, that's fine too.

By the way, I don't think it increases the dependency or reduces portability, because it is something that is done by the developers (convertion from ronn format to roff or html format). The users don't need to install ruby or ronn.