* [PATCH 2/9] doc: split option variants into separate items
2021-05-17 3:35 7% [PATCH 0/9] doc: lei manpages, round 5 Kyle Meyer
@ 2021-05-17 3:35 3% ` Kyle Meyer
0 siblings, 0 replies; 2+ results
From: Kyle Meyer @ 2021-05-17 3:35 UTC (permalink / raw)
To: meta
e226f18934eb7291 modified the lei-q manpage so that each variant of an
option gets a dedicated =item to make L</--xyz> look nicer and to
follow the Perl core documentation. Do the same for the other
manpages.
Note that this still leaves the variants of an option grouped in one
scenario: when a list of options without descriptions is presented as
a pointer to another location. Splitting the variants in that case
would make it harder for the reader to tell what the distinct options
are.
---
Documentation/lei-add-external.pod | 12 +++++++++---
Documentation/lei-blob.pod | 24 ++++++++++++++++++------
Documentation/lei-forget-external.pod | 4 +++-
Documentation/lei-import.pod | 4 +++-
Documentation/lei-init.pod | 4 +++-
Documentation/lei-ls-external.pod | 8 ++++++--
Documentation/lei-ls-label.pod | 8 ++++++--
Documentation/lei-p2q.pod | 8 ++++++--
Documentation/lei-tag.pod | 8 ++++++--
Documentation/public-inbox-compact.pod | 6 +++++-
Documentation/public-inbox-convert.pod | 4 +++-
Documentation/public-inbox-daemon.pod | 16 ++++++++++++----
Documentation/public-inbox-extindex.pod | 4 +++-
Documentation/public-inbox-imapd.pod | 4 +++-
Documentation/public-inbox-index.pod | 12 +++++++++---
Documentation/public-inbox-init.pod | 20 +++++++++++++++-----
Documentation/public-inbox-nntpd.pod | 4 +++-
Documentation/public-inbox-xcpdb.pod | 14 +++++++++++---
18 files changed, 124 insertions(+), 40 deletions(-)
diff --git a/Documentation/lei-add-external.pod b/Documentation/lei-add-external.pod
index ad0e1d07..71229865 100644
--- a/Documentation/lei-add-external.pod
+++ b/Documentation/lei-add-external.pod
@@ -30,11 +30,15 @@ Default: 0
Create C<LOCATION> by mirroring the public-inbox at C<URL>.
-=item -v, --verbose
+=item -v
+
+=item --verbose
Provide more feedback on stderr.
-=item -q, --quiet
+=item -q
+
+=item --quiet
Suppress feedback messages.
@@ -44,7 +48,9 @@ Suppress feedback messages.
=over
-=item --torsocks=auto|no|yes, --no-torsocks
+=item --torsocks=auto|no|yes
+
+=item --no-torsocks
Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks.
diff --git a/Documentation/lei-blob.pod b/Documentation/lei-blob.pod
index 341b5505..76918324 100644
--- a/Documentation/lei-blob.pod
+++ b/Documentation/lei-blob.pod
@@ -31,15 +31,21 @@ Do not look in the git repository of the current working directory.
Do not look in mail storage for C<OID>. This is implied by
C<--oid-a>, C<--path-a>, and C<--path-b>.
-=item -A OID-A, --oid-a=OID-A
+=item -A OID-A
+
+=item --oid-a=OID-A
Provide pre-image object ID as a hint for reconstructing C<OID>.
-=item -a PATH-A, --path-a=PATH-A
+=item -a PATH-A
+
+=item --path-a=PATH-A
Provide pre-image pathname as a hint for reconstructing C<OID>.
-=item -b PATH-B, --path-b=PATH-B
+=item -b PATH-B
+
+=item --path-b=PATH-B
Provide post-image pathname as a hint for reconstructing C<OID>.
@@ -61,7 +67,9 @@ Limit operations to those requiring network access.
Don't include results from externals.
-=item -I LOCATION, --include=LOCATION
+=item -I LOCATION
+
+=item --include=LOCATION
Include specified external in search. This option may be given
multiple times.
@@ -81,11 +89,15 @@ multiple times, in which case the search uses only the specified set.
Disable the default behavior of memoizing remote messages into the
local store.
-=item -v, --verbose
+=item -v
+
+=item --verbose
Provide more feedback on stderr.
-=item --torsocks=auto|no|yes, --no-torsocks
+=item --torsocks=auto|no|yes
+
+=item --no-torsocks
Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks.
diff --git a/Documentation/lei-forget-external.pod b/Documentation/lei-forget-external.pod
index 0d065a76..e0e3b8e1 100644
--- a/Documentation/lei-forget-external.pod
+++ b/Documentation/lei-forget-external.pod
@@ -16,7 +16,9 @@ future search results.
=over
-=item -q, --quiet
+=item -q
+
+=item --quiet
Suppress feedback messages.
diff --git a/Documentation/lei-import.pod b/Documentation/lei-import.pod
index 5b6a6f26..1fe2dac3 100644
--- a/Documentation/lei-import.pod
+++ b/Documentation/lei-import.pod
@@ -24,7 +24,9 @@ C<mboxcl2>, C<mboxcl>, or C<mboxo>.
=over
-=item -F MAIL_FORMAT, --in-format=MAIL_FORMAT
+=item -F MAIL_FORMAT
+
+=item --in-format=MAIL_FORMAT
Message input format. Unless messages are given on stdin, using a
format prefix with C<LOCATION> is preferred.
diff --git a/Documentation/lei-init.pod b/Documentation/lei-init.pod
index 54ae9dbe..4bfc3b9f 100644
--- a/Documentation/lei-init.pod
+++ b/Documentation/lei-init.pod
@@ -17,7 +17,9 @@ location.
=over
-=item -q, --quiet
+=item -q
+
+=item --quiet
Suppress feedback messages.
diff --git a/Documentation/lei-ls-external.pod b/Documentation/lei-ls-external.pod
index 124b7763..4c0c263d 100644
--- a/Documentation/lei-ls-external.pod
+++ b/Documentation/lei-ls-external.pod
@@ -15,7 +15,9 @@ to matching entries.
=over
-=item -g, --globoff
+=item -g
+
+=item --globoff
Do not match C<FILTER> using C<*?> wildcards and C<[]> ranges.
@@ -27,7 +29,9 @@ Limit operations to the local filesystem.
Limit operations to those requiring network access.
-=item -z, -0
+=item -z
+
+=item -0
Use C<\0> (NUL) instead of newline (CR) to delimit lines.
diff --git a/Documentation/lei-ls-label.pod b/Documentation/lei-ls-label.pod
index df100a24..41aa030d 100644
--- a/Documentation/lei-ls-label.pod
+++ b/Documentation/lei-ls-label.pod
@@ -14,11 +14,15 @@ List all known message labels ("mailboxes" in JMAP terminology).
=over
-=item -z, -0
+=item -z
+
+=item -0
Use C<\0> (NUL) instead of newline (CR) to delimit lines.
-=item -q, --quiet
+=item -q
+
+=item --quiet
Suppress feedback messages.
diff --git a/Documentation/lei-p2q.pod b/Documentation/lei-p2q.pod
index fc85fa88..f404ede0 100644
--- a/Documentation/lei-p2q.pod
+++ b/Documentation/lei-p2q.pod
@@ -23,7 +23,9 @@ L<git-format-patch(1)> is used to generate the patch.
=over
-=item -w PREFIX[,PREFIX], --want=PREFIX[,PREFIX]
+=item -w PREFIX[,PREFIX]
+
+=item --want=PREFIX[,PREFIX]
Search prefixes to use. C<dfpost> (post-image git blob ID) and C<dfn>
(file names from the diff) are the most useful. Other available
@@ -54,7 +56,9 @@ Dump output that shows the information collected for every prefix.
This information can be useful for seeing how a patch is processed,
but the format should not be considered stable.
-=item -q, --quiet
+=item -q
+
+=item --quiet
Suppress feedback messages.
diff --git a/Documentation/lei-tag.pod b/Documentation/lei-tag.pod
index 5282b3d2..b2509ba4 100644
--- a/Documentation/lei-tag.pod
+++ b/Documentation/lei-tag.pod
@@ -26,14 +26,18 @@ specified messages, and "-L:INBOX" would remove the "INBOX" label.
=over
-=item -F MAIL_FORMAT, --in-format=MAIL_FORMAT
+=item -F MAIL_FORMAT
+
+=item --in-format=MAIL_FORMAT
Message input format: C<eml>, C<mboxrd>, C<mboxcl2>, C<mboxcl>, or
C<mboxo>.
Default: C<eml>
-=item -q, --quiet
+=item -q
+
+=item --quiet
Suppress feedback messages.
diff --git a/Documentation/public-inbox-compact.pod b/Documentation/public-inbox-compact.pod
index cf64fe0d..d2b74c86 100644
--- a/Documentation/public-inbox-compact.pod
+++ b/Documentation/public-inbox-compact.pod
@@ -34,7 +34,11 @@ Compact all inboxes configured in ~/.public-inbox/config.
This is an alternative to specifying individual inboxes directories
on the command-line.
-=item --blocksize / --no-full / --fuller
+=item --blocksize
+
+=item --no-full
+
+=item --fuller
These options are passed directly to L<xapian-compact(1)>.
diff --git a/Documentation/public-inbox-convert.pod b/Documentation/public-inbox-convert.pod
index b8c8d54f..a2f8caf5 100644
--- a/Documentation/public-inbox-convert.pod
+++ b/Documentation/public-inbox-convert.pod
@@ -25,7 +25,9 @@ By default, public-inbox-convert creates a new index in the
v2 inbox and indexes all existing messages, a lengthy
operation for large inboxes.
-=item -j JOBS, --jobs=JOBS
+=item -j JOBS
+
+=item --jobs=JOBS
Control the number of indexing jobs and Xapian shards of the v2
inbox. By default, this is the detected CPU count but capped
diff --git a/Documentation/public-inbox-daemon.pod b/Documentation/public-inbox-daemon.pod
index 3bf95496..ec210efa 100644
--- a/Documentation/public-inbox-daemon.pod
+++ b/Documentation/public-inbox-daemon.pod
@@ -28,7 +28,9 @@ processes to take advantage of multiple CPUs.
=over
-=item -l, --listen ADDRESS
+=item -l ADDRESS
+
+=item --listen ADDRESS
This takes an absolute path to a Unix socket or HOST:PORT
to listen on. For example, to listen to TCP connections on
@@ -45,7 +47,9 @@ L<systemd.socket(5)> or similar
Default: server-dependent unless socket activation is used with
L<systemd(1)> or similar (see L<systemd.socket(5)>).
-=item -1, --stdout PATH
+=item -1
+
+=item --stdout PATH
Specify an appendable path to redirect stdout descriptor (1) to.
Using this is preferable to setting up the redirect externally
@@ -54,11 +58,15 @@ SIGUSR1 to be handled (see L<SIGNALS/SIGNALS> below).
Default: /dev/null
-=item -2, --stderr PATH
+=item -2 PATH
+
+=item --stderr PATH
Like C<--stdout>, but for the stderr descriptor (2).
-=item -W, --worker-processes
+=item -W
+
+=item --worker-processes
Set the number of worker processes.
diff --git a/Documentation/public-inbox-extindex.pod b/Documentation/public-inbox-extindex.pod
index bed65272..fed5017b 100644
--- a/Documentation/public-inbox-extindex.pod
+++ b/Documentation/public-inbox-extindex.pod
@@ -23,7 +23,9 @@ along with L<DBD::SQLite> and L<DBI> Perl modules.
=over
-=item --jobs=JOBS, -j
+=item -j JOBS
+
+=item --jobs=JOBS
... TODO, see L<public-inbox-index(5)>
diff --git a/Documentation/public-inbox-imapd.pod b/Documentation/public-inbox-imapd.pod
index 71e0ea7f..52df4d51 100644
--- a/Documentation/public-inbox-imapd.pod
+++ b/Documentation/public-inbox-imapd.pod
@@ -27,7 +27,9 @@ are supported and documented below.
=over
-=item -l, --listen PROTO://ADDRESS/?cert=/path/to/cert,key=/path/to/key
+=item -l PROTO://ADDRESS/?cert=/path/to/cert,key=/path/to/key
+
+=item --listen PROTO://ADDRESS/?cert=/path/to/cert,key=/path/to/key
In addition to the normal C<-l>/C<--listen> switch described in
L<public-inbox-daemon(8)>, the C<PROTO> prefix (e.g. C<imap://> or
diff --git a/Documentation/public-inbox-index.pod b/Documentation/public-inbox-index.pod
index 3bdd5efc..57fedb69 100644
--- a/Documentation/public-inbox-index.pod
+++ b/Documentation/public-inbox-index.pod
@@ -34,7 +34,9 @@ normal search functionality.
=over
-=item --jobs=JOBS, -j
+=item -j JOBS
+
+=item --jobs=JOBS
Influences the number of Xapian indexing shards in a
(L<public-inbox-v2-format(5)>) inbox.
@@ -52,7 +54,9 @@ the overview and article number mapping).
Default: the number of existing Xapian shards
-=item --compact / -c
+=item -c
+
+=item --compact
Compacts the Xapian DBs after indexing. This is recommended
when using C<--reindex> to avoid running out of disk space
@@ -162,7 +166,9 @@ See L<public-inbox-init(1)/--skip-docdata> for description and caveats.
Available in public-inbox 1.6.0+.
-=item --update-extindex=EXTINDEX, -E
+=item -E EXTINDEX
+
+=item --update-extindex=EXTINDEX
Update the given external index (L<public-inbox-extindex-format(5)>.
Either the configured section name (e.g. C<all>) or a directory name
diff --git a/Documentation/public-inbox-init.pod b/Documentation/public-inbox-init.pod
index 5a875f9d..62624f14 100644
--- a/Documentation/public-inbox-init.pod
+++ b/Documentation/public-inbox-init.pod
@@ -20,7 +20,9 @@ may be specified for inboxes with multiple addresses.
=over
-=item -V, --version FORMAT_VERSION
+=item -V FORMAT_VERSION
+
+=item --version FORMAT_VERSION
Specify C<2> here to use the scalable L<public-inbox-v2-format(5)>
if you have L<DBD::SQLite> installed.
@@ -31,7 +33,9 @@ L<DBD::SQLite>.
Default: C<1>
-=item -L, --indexlevel <basic|medium|full>
+=item -L <basic|medium|full>
+
+=item --indexlevel <basic|medium|full>
Controls the indexing level for L<public-inbox-index(1)>
@@ -39,7 +43,9 @@ See L<public-inbox-config(5)> for more information.
Default: C<full>
-=item --ng, --newsgroup NEWSGROUP
+=item --ng NEWSGROUP
+
+=item --newsgroup NEWSGROUP
The NNTP group name for use with L<public-inbox-nntpd(8)>. This
may be any newsgroup name with hierarchies delimited by C<.>.
@@ -70,7 +76,9 @@ Available in public-inbox 1.6.0+.
Default: unset, no NNTP article numbers are skipped
-=item -S, --skip-epoch
+=item -S
+
+=item --skip-epoch
For C<-V2> (L<public-inbox-v2-format(5)>) inboxes only, this option
allows archivists to publish incomplete archives with newer
@@ -81,7 +89,9 @@ Available since public-inbox 1.2.0.
Default: unset, no epochs are skipped
-=item -j, --jobs=JOBS
+=item -j JOBS
+
+=item --jobs=JOBS
Control the number of Xapian index shards in a
C<-V2> (L<public-inbox-v2-format(5)>) inbox.
diff --git a/Documentation/public-inbox-nntpd.pod b/Documentation/public-inbox-nntpd.pod
index 83f7c83a..651428ab 100644
--- a/Documentation/public-inbox-nntpd.pod
+++ b/Documentation/public-inbox-nntpd.pod
@@ -26,7 +26,9 @@ are supported and documented below.
=over
-=item -l, --listen PROTO://ADDRESS/?cert=/path/to/cert,key=/path/to/key
+=item -l PROTO://ADDRESS/?cert=/path/to/cert,key=/path/to/key
+
+=item --listen PROTO://ADDRESS/?cert=/path/to/cert,key=/path/to/key
In addition to the normal C<-l>/C<--listen> switch described in
L<public-inbox-daemon(8)>, the protocol prefix (e.g. C<nntp://> or
diff --git a/Documentation/public-inbox-xcpdb.pod b/Documentation/public-inbox-xcpdb.pod
index eb675965..e7c07ed3 100644
--- a/Documentation/public-inbox-xcpdb.pod
+++ b/Documentation/public-inbox-xcpdb.pod
@@ -30,7 +30,9 @@ Copy all inboxes configured in ~/.public-inbox/config.
This is an alternative to specifying individual inboxes directories
on the command-line.
-=item -c, --compact
+=item -c
+
+=item --compact
In addition to performing the copy operation, run L<xapian-compact(1)>
on each Xapian shard after copying but before finalizing it.
@@ -42,7 +44,9 @@ preferable for gigantic inboxes where the coarse-grained lock
currently required for L<public-inbox-compact(1)> can cause
the compaction to take hours at-a-time.
-=item --reshard=N / -R N
+=item -R N
+
+=item --reshard=N
Reshard the Xapian database on a L<v2|public-inbox-v2-format(5)>
inbox to C<N> shards . Since L<xapian-compact(1)> is not suitable
@@ -52,7 +56,11 @@ existing Xapian database(s) to any positive value of C<N>.
This is useful in case the Xapian DB was created with too few or
too many shards given the capabilities of the current hardware.
-=item --blocksize / --no-full / --fuller
+=item --blocksize
+
+=item --no-full
+
+=item --fuller
These options are passed directly to L<xapian-compact(1)> when
used with C<--compact>.
--
2.31.1
^ permalink raw reply related [relevance 3%]
* [PATCH 0/9] doc: lei manpages, round 5
@ 2021-05-17 3:35 7% Kyle Meyer
2021-05-17 3:35 3% ` [PATCH 2/9] doc: split option variants into separate items Kyle Meyer
0 siblings, 1 reply; 2+ results
From: Kyle Meyer @ 2021-05-17 3:35 UTC (permalink / raw)
To: meta
This series updates the lei manpages, continuing from
<20210329031117.28516-1-kyle@kyleam.com>. It covers changes up to the
current tip of master (236831da32b1240d..8cc23ac6f7a38479).
The second patch touches outside of lei manpages as a followup to
e226f18934eb7291 (doc: lei q: split =item aliases onto separate lines,
2021-04-28).
[1/9] doc lei blob: avoid combined description of separate options
[2/9] doc: split option variants into separate items
[3/9] doc lei blob: point to lei-q for shared options
[4/9] doc lei: resort lei-tag entries
[5/9] doc lei q: fix a typo
[6/9] doc lei q: add missing value for --lock
[7/9] doc lei: add manpage for convert
[8/9] doc lei: add manpages for new commands
[9/9] doc lei: update manpages with new options
Documentation/lei-add-external.pod | 12 ++-
Documentation/lei-blob.pod | 62 +++++++--------
.../{lei-import.pod => lei-convert.pod} | 40 ++++++----
Documentation/lei-edit-search.pod | 28 +++++++
Documentation/lei-forget-external.pod | 4 +-
Documentation/lei-forget-search.pod | 28 +++++++
Documentation/lei-import.pod | 20 ++++-
Documentation/lei-init.pod | 4 +-
Documentation/lei-lcat.pod | 79 +++++++++++++++++++
Documentation/lei-ls-external.pod | 8 +-
Documentation/lei-ls-label.pod | 8 +-
...i-ls-external.pod => lei-ls-mail-sync.pod} | 22 +++---
Documentation/lei-ls-search.pod | 65 +++++++++++++++
Documentation/lei-overview.pod | 12 +++
Documentation/lei-p2q.pod | 8 +-
Documentation/lei-q.pod | 16 +++-
Documentation/lei-rediff.pod | 79 +++++++++++++++++++
Documentation/lei-tag.pod | 8 +-
Documentation/lei-up.pod | 48 +++++++++++
Documentation/lei.pod | 18 +++++
Documentation/public-inbox-compact.pod | 6 +-
Documentation/public-inbox-convert.pod | 4 +-
Documentation/public-inbox-daemon.pod | 16 +++-
Documentation/public-inbox-extindex.pod | 4 +-
Documentation/public-inbox-imapd.pod | 4 +-
Documentation/public-inbox-index.pod | 12 ++-
Documentation/public-inbox-init.pod | 20 +++--
Documentation/public-inbox-nntpd.pod | 4 +-
Documentation/public-inbox-xcpdb.pod | 14 +++-
Documentation/txt2pre | 11 ++-
MANIFEST | 8 ++
Makefile.PL | 8 +-
32 files changed, 580 insertions(+), 100 deletions(-)
copy Documentation/{lei-import.pod => lei-convert.pod} (54%)
create mode 100644 Documentation/lei-edit-search.pod
create mode 100644 Documentation/lei-forget-search.pod
create mode 100644 Documentation/lei-lcat.pod
copy Documentation/{lei-ls-external.pod => lei-ls-mail-sync.pod} (64%)
create mode 100644 Documentation/lei-ls-search.pod
create mode 100644 Documentation/lei-rediff.pod
create mode 100644 Documentation/lei-up.pod
base-commit: 8cc23ac6f7a3847977ec57c2a3e9e391fdb94da6
--
2.31.1
^ permalink raw reply [relevance 7%]
Results 1-2 of 2 | reverse | options above
-- pct% links below jump to the message on this page, permalinks otherwise --
2021-05-17 3:35 7% [PATCH 0/9] doc: lei manpages, round 5 Kyle Meyer
2021-05-17 3:35 3% ` [PATCH 2/9] doc: split option variants into separate items Kyle Meyer
Code repositories for project(s) associated with this public inbox
https://80x24.org/public-inbox.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).