facebook / PathPicker

PathPicker accepts a wide range of input -- output from git commands, grep results, searches -- pretty much anything. After parsing the input, PathPicker presents you with a nice UI to select which files you're interested in. After that you can open them in your favorite editor or execute arbitrary commands.
https://facebook.github.io/PathPicker/
MIT License
5.11k stars 283 forks source link

Feature Request: Make man page easier to read, put each flag in its own line. #403

Closed thiagowfx closed 3 years ago

thiagowfx commented 3 years ago

Original title: Feature Request: Fpp persistent mode, for opening files in $EDITOR, one-by-one.

This FR is a bit hard to describe, so I'll give a concrete example which is probably easier to understand.

Consider pacman -Ql fpp which prints the list of all files installed by the fpp package in Arch Linux:

% pacman -Ql fpp
fpp /usr/
fpp /usr/bin/
fpp /usr/bin/fpp
fpp /usr/share/
fpp /usr/share/doc/
fpp /usr/share/doc/fpp/
fpp /usr/share/doc/fpp/CODE_OF_CONDUCT.md
fpp /usr/share/doc/fpp/CONTRIBUTING.md
fpp /usr/share/doc/fpp/README.md
fpp /usr/share/doc/fpp/assets/
fpp /usr/share/doc/fpp/assets/ZeroClipboard.min.js
fpp /usr/share/doc/fpp/assets/ZeroClipboard.swf
fpp /usr/share/doc/fpp/assets/bootstrap.min.css
...

Now let's say I want to use fpp against this very output:

% pacman -Ql fpp | fpp

This does what you expect: It opens fpp against the output above.

Now here's my use case: I'd like to interactively navigate that output to open detected files one by one with my favorite $EDITOR:

  1. I'd navigate to /usr/bin/fpp and press Enter. That opens it in my $EDITOR.
  2. After studying the file, I quit the editor.

Now here's my feature request:

Observed behavior: After 2), I get back to the command prompt.

Wanted behavior: After 2), I would like to get back to the previous fpp exec, as if I had run pacman -Ql fpp | fpp again. My next action would be to use the fpp selection tool to open another file in my $EDITOR (say, /usr/share/doc/fpp/README.md), then close it, then open another file, and so on.

In other words, the idea is to maintain the output of a given command fixed, and then make fpp go continuously back to that output whenever the editor is closed.

In that scenario, it would be best if fpp didn't execute the command (pacman -Ql fpp) again, but rather just saved the output once and then kept going back to it.

This could be used for running commands multiple times as well; in my use case above, I open my $EDITOR multiple times, but I could also want to run different commands several times in a row, with the same output.

thiagowfx commented 3 years ago

It turns out this feature already exists today, but it is not very discoverable. I wrote this FR and then surprisingly found it right afterwards, but I decided to write it anyway for discoverability purposes:

  -ko, --keep-open      keep PathPicker open once a file selection or command is performed. This will loop the program until Ctrl-C is used to terminate the
                        process.

In my example above, just do pacman -Ql fpp | fpp -ko.

Let's repurpose this FR instead:

It is trivial to find this feature with fpp --help, which is nicely formatted:

optional arguments:
  -h, --help            show this help message and exit
  -r, --record          Record input and output. This is largely used for testing, but you may find it useful for scripting.
  --version             Print the version of fpp and exit.
  --clean               Remove the state files that fpp uses when starting up, including the previous input used and selection pickle. Useful when using fpp in
                        a script context where the previous state should be discarded.
  -ko, --keep-open      keep PathPicker open once a file selection or command is performed. This will loop the program until Ctrl-C is used to terminate the
                        process.

However, it's very hard to find this feature with man fpp, which is not nicely formatted:

FPP(1)                                                                                                                                                FPP(1)

NAME
       fpp - Facebook PathPicker; a command line tool for selecting files out of bash output

SYNOPSIS
       usage: fpp [-h] [-r] [--version] [--clean] [-ko] [-c COMMAND [COMMAND ...]] [-nfc]

       optional arguments: -h, --help show this help message and exit -r, --record Record input and output. This is largely used for testing, but you may
       find it useful for scripting. --version Print the version of fpp and exit. --clean Remove the state files that fpp uses when starting up, including
       the previous input used and selection pickle. Useful when using fpp in a script context where the previous state should be discarded. -ko,
       --keep-open keep PathPicker open once a file selection or command is performed. This will loop the program until Ctrl-C is used to terminate the
       process. -c COMMAND [COMMAND ...], --command COMMAND [COMMAND ...] You may specify a command while invoking fpp that will be run once files have been
       selected. Normally, fpp opens your editor (see discussion of $EDITOR, $VISUAL, and $FPP_EDITOR) when you press enter. If you specify a command here,
       it will be invoked instead. -nfc, --no-file-checks You may want to turn off file system validation for a particular instance of PathPicker; this flag
       disables our internal logic for checking if a regex match is an actual file on the system. This is particularly useful when using PathPicker for an
       input of, say, deleted files in git status that you would like to restore to a given revision. It enables you to select the deleted files even though
       they do not exist on the system anymore.

All flags are in a single line, which makes them hard to read.

So I am repurposing this FR to the following:

Make man page easier to read, put each flag in its own line.

KapJI commented 3 years ago

I agree that man page can be improved. It'd great if you can submit a PR for that 🙂

thiagowfx commented 3 years ago

Do you know what is the rationale for the man page though? There's already --help. Having two separate sources of documentation (both the man page and --help) is an unnecessary duplication of effort. The --help output is already properly formatted and well readable.

I wouldn't mind submitting a PR to delete the man page, hence consolidating docs into a single source of truth. But maintaining the man page and the --help text separately seems an unnecessary duplication of effort.

Compare:

Edit: Another thought/idea is to somehow generate the man page from the usage_strings.py file above. I'll probably not pursue this though, as I am already maintaining the fpp-git package in the AUR. Hopefully someone else can pick this up though.

KapJI commented 3 years ago

This makes sense. I don't mind deleting man page completely.

thiagowfx commented 3 years ago

Hi Ruslan,

Upon reading the source code more deeply, I take back my last comment. It turns out the man page is not a duplication of effort: It is reusing the same strings as --help, in this case it should be fine to keep it. Initially I assumed the help was being written and maintained in two separate sources. So nevermind!

I sent a PR to fix the man page generation script and update it (it hasn't been updated since 2015!). See https://github.com/facebook/PathPicker/pull/404.

If it makes sense, you could probably automate your repository to automatically regenerate the manual page on every commit (with github actions), but that's beyond the scope of my contribution.