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

[thiagowfx]

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]

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

[thiagowfx]

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:

• https://github.com/facebook/PathPicker/blob/master/debian/usr/share/man/man1/fpp.1 (man, not updated in ~6 years)
• https://github.com/facebook/PathPicker/blob/master/src/pathpicker/usage_strings.py (--help, updated a few months ago)

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]

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

[thiagowfx]

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 #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.