Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add man (1) entry #77

Closed
gyscos opened this issue Oct 8, 2017 · 17 comments
Closed

Add man (1) entry #77

gyscos opened this issue Oct 8, 2017 · 17 comments
Milestone

Comments

@gyscos
Copy link

gyscos commented Oct 8, 2017

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
Copy link
Owner

sharkdp commented Oct 8, 2017

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
Copy link
Author

gyscos commented Oct 8, 2017

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
Copy link
Contributor

@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
Copy link
Owner

sharkdp commented Oct 13, 2017

@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
Copy link
Contributor

pickfire commented Oct 13, 2017

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

@sharkdp
Copy link
Owner

sharkdp commented Oct 13, 2017

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

@pickfire
Copy link
Contributor

@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

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
Copy link
Owner

sharkdp commented Oct 14, 2017

@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
Copy link
Contributor

@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
Copy link
Owner

sharkdp commented Oct 15, 2017

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
Copy link
Contributor

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

@sharkdp
Copy link
Owner

sharkdp commented Oct 16, 2017

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.

@sharkdp sharkdp closed this as completed Oct 19, 2017
@sharkdp sharkdp added this to the v5.0 milestone Oct 19, 2017
@dashohoxha
Copy link

@pickfire
Copy link
Contributor

@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
Copy link

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
Copy link
Contributor

@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
Copy link

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

4 participants