Skip to content

Commit a661e28

Browse files
thiagowfxthiagowfx
authored
Fix man page (#403) (#404)
- Updates man page with newly added flags since 2015. Man page had been last updated only in 2015. - Fix formatting of flags in man page. Instead of joining lines, now each flag is correctly displayed in its own line, making it easier to read. - Fix man page generation script, which was broken and still referencing the old usageStrings.py (correct filename is usage_strings.py).
1 parent e0d5cfc commit a661e28

File tree

4 files changed

+84
-12
lines changed

4 files changed

+84
-12
lines changed

‎.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,3 +10,5 @@ fpp.deb
1010
fpp*.deb
1111
debian/usr/
1212
pathpicker*.deb
13+
# man page leftovers
14+
manpage.adoc

‎debian/usr/share/man/man1/fpp.1

Lines changed: 78 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
'\" t
22
.\" Title: fpp
3-
.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
4-
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
5-
.\" Date: 06/15/2015
3+
.\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
4+
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
5+
.\" Date: 07/01/2021
66
.\" Manual: \ \&
77
.\" Source: \ \&
88
.\" Language: English
99
.\"
10-
.TH "FPP" "1" "06/15/2015" "\ \&" "\ \&"
10+
.TH "FPP" "1" "07/01/2021" "\ \&" "\ \&"
1111
.\" -----------------------------------------------------------------
1212
.\" * Define some portability stuff
1313
.\" -----------------------------------------------------------------
@@ -31,9 +31,63 @@
3131
fpp \- Facebook PathPicker; a command line tool for selecting files out of bash output
3232
.SH "SYNOPSIS"
3333
.sp
34-
usage: fpp [\-h] [\-r] [\-\-version] [\-\-clean] [\-ko] [\-c COMMAND [COMMAND \&...]] [\-nfc]
35-
.sp
36-
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\&.
34+
.nf
35+
usage: fpp [\-h] [\-r] [\-\-version] [\-\-clean] [\-ko] [\-c COMMAND [COMMAND \&.\&.\&.]]
36+
[\-e EXECUTE_KEYS [EXECUTE_KEYS \&.\&.\&.]] [\-nfc] [\-ai] [\-ni] [\-a]
37+
38+
optional arguments:
39+
\-h, \-\-help show this help message and exit
40+
\-r, \-\-record Record input and output\&. This is largely used for
41+
testing, but you may find it useful for scripting\&.
42+
\-\-version Print the version of fpp and exit\&.
43+
\-\-clean Remove the state files that fpp uses when starting up,
44+
including the previous input used and selection
45+
pickle\&. Useful when using fpp in a script context
46+
where the previous state should be discarded\&.
47+
\-ko, \-\-keep\-open keep PathPicker open once a file selection or command
48+
is performed\&. This will loop the program until Ctrl\-C
49+
is used to terminate the process\&.
50+
\-c COMMAND [COMMAND \&.\&.\&.], \-\-command COMMAND [COMMAND \&.\&.\&.]
51+
You may specify a command while invoking fpp that will
52+
be run once files have been selected\&. Normally, fpp
53+
opens your editor (see discussion of $EDITOR, $VISUAL,
54+
and $FPP_EDITOR) when you press enter\&. If you specify
55+
a command here, it will be invoked instead\&.
56+
\-e EXECUTE_KEYS [EXECUTE_KEYS \&.\&.\&.], \-\-execute\-keys EXECUTE_KEYS [EXECUTE_KEYS \&.\&.\&.]
57+
Automatically execute the given keys when the file
58+
list shows up\&. This is useful on certain cases, e\&.g\&.
59+
using "END" in order to automatically go to the last
60+
entry when there is a long list\&.
61+
\-nfc, \-\-no\-file\-checks
62+
You may want to turn off file system validation for a
63+
particular instance of PathPicker; this flag disables
64+
our internal logic for checking if a regex match is an
65+
actual file on the system\&. This is particularly useful
66+
when using PathPicker for an input of, say, deleted
67+
files in git status that you would like to restore to
68+
a given revision\&. It enables you to select the deleted
69+
files even though they do not exist on the system
70+
anymore\&.
71+
\-ai, \-\-all\-input You may force PathPicker to recognize all lines as
72+
acceptable input\&. Typically, PathPicker will scan the
73+
input for references to file paths\&. Passing this
74+
option will disable those scans and the program will
75+
assume that every input line is a match\&. In practice,
76+
this option allows for input selection for a variety
77+
of sources that would otherwise be unsupported \-\- git
78+
branches, mercurial bookmarks, etc\&.
79+
\-ni, \-\-non\-interactive
80+
Normally, the command that runs after you\*(Aqve chosen
81+
files to operate on is spawned in an interactive
82+
subshell\&. This allows you to use aliases and have
83+
access to environment variables defined in your
84+
startup files, but can have strange side\-effects when
85+
starting and stopping jobs and redirecting inputs\&.
86+
Using this flag runs your commands in a non\-
87+
interactive subshell, like a normal shell script\&.
88+
\-a, \-\-all Automatically select all available lines once the
89+
interactive editor has been entered\&.
90+
.fi
3791
.SH "INTRO"
3892
.sp
3993
To get started with fpp, pipe some kind of terminal output into the program\&. Examples include:
@@ -195,6 +249,17 @@ Once fpp parses your input (and something that looks like a file matches), it wi
195249
[x] quick select mode
196250
.RE
197251
.sp
252+
.RS 4
253+
.ie n \{\
254+
\h'-04'\(bu\h'+03'\c
255+
.\}
256+
.el \{\
257+
.sp -1
258+
.IP \(bu 2.3
259+
.\}
260+
[d] describe file
261+
.RE
262+
.sp
198263
Once you have your files selected, you can either open them in your favorite text editor or execute commands with them via command mode:
199264
.sp
200265
.RS 4
@@ -290,6 +355,12 @@ Editor
290355
.sp
291356
The $FPP_EDITOR environment variable can be set to tell PathPicker which editor to open the selected files with\&. If that variable is not set, $VISUAL and then $EDITOR are used as fallbacks, with "vim" as a last resort\&.
292357
.sp
358+
The $FPP_DISABLE_SPLIT environment variable will disable splitting files into panes for vim clients (aka sequential editing)\&.
359+
.sp
360+
Directory
361+
.sp
362+
PathPicker saves state files for use when starting up, including the previous input used and selection pickle\&. By default, these files are saved in $XDG_CACHE_HOME/fpp, but the $FPP_DIR environment variable can be used to tell PathPicker to use another directory\&.
363+
.sp
293364
Colors
294365
.sp
295366
FPP will understand colors if the piped input uses them\&. In general, most tools do not unless requested to do so\&.

‎scripts/makeManpage.sh

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,5 @@
44
# This source code is licensed under the MIT license found in the
55
# LICENSE file in the root directory of this source tree.
66
command -v a2x >/dev/null 2>&1 || { echo >&2 "I require a2x provided by asciidoc, but it's not installed. Aborting."; exit 1; }
7-
python3 src/usageStrings.py > manpage.adoc;
8-
a2x --doctype manpage --format manpage manpage.adoc --destination-dir ./debian/usr/share/man/man1/;
9-
gzip -9 ./debian/usr/share/man/man1/fpp.1;
7+
(cd src && python3 -m pathpicker.usage_strings > manpage.adoc)
8+
a2x --format manpage "src/manpage.adoc" --destination-dir debian/usr/share/man/man1/

‎src/pathpicker/usage_strings.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -180,9 +180,9 @@
180180
MANPAGE_HEADER,
181181
MANPAGE_NAME_SECTION,
182182
MANPAGE_SYNOPSIS,
183-
# FIXME: asciidoc example block?
184-
# http://www.methods.co.nz/asciidoc/userguide.html#X48
183+
"--------------------------------------",
185184
ScreenFlags.get_arg_parser().format_help(),
185+
"--------------------------------------",
186186
MANPAGE_INTRO_PRE,
187187
INTRO,
188188
USAGE_PAGE_HEADER,

0 commit comments

Comments
 (0)