From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: X-Spam-ASN: AS16276 188.165.0.0/16 X-Spam-Status: No, score=-3.4 required=3.0 tests=AWL,BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_HI,SPF_HELO_NONE, SPF_PASS shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2 Received: from out2.migadu.com (out2.migadu.com [188.165.223.204]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by dcvr.yhbt.net (Postfix) with ESMTPS id EAA0E1F9E5 for ; Mon, 17 May 2021 03:35:46 +0000 (UTC) X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=kyleam.com; s=key1; t=1621222545; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=U0AyHX+QcPere15RR8LFQmyBdxSUWc80oJCtyJ1HcHQ=; b=hLaNSZI+m2SD0odNGei7Kijz1C5QHS1V3CzjP5UXG6Fa4umhajhnh5mwj9ewoTXqlDP4hX WZA2SLkpfscqdbC6tnCvhkpIEKi0LJsqAAsc5ukwa1hpPHLVZ71P4PX2xcbod8qZlI3MJ4 EAzbynd6D6CjuACqrdwvAQDsvZYeBR3I40YiSO68Fj2T+v7ydntkPBJJDjdP0e+YnQeGss Rt53o6cSAP4pt5QJHt6k8/KP4jPViPM2DFVs5nAvjQYAr7huzssKnnn6B2EWoXQMaqtvZz bF90KuwrqX/r7r7gf0isN/Ysx+geqIXUOXyFq7MHtDUGPtTuNZh3SQ7uyfN3uQ== From: Kyle Meyer To: meta@public-inbox.org Subject: [PATCH 2/9] doc: split option variants into separate items Date: Sun, 16 May 2021 23:35:21 -0400 Message-Id: <20210517033528.18966-3-kyle@kyleam.com> In-Reply-To: <20210517033528.18966-1-kyle@kyleam.com> References: <20210517033528.18966-1-kyle@kyleam.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Migadu-Flow: FLOW_OUT X-Migadu-Auth-User: kyle@kyleam.com List-Id: e226f18934eb7291 modified the lei-q manpage so that each variant of an option gets a dedicated =item to make L 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 by mirroring the public-inbox at C. -=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 and L 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. 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. -=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. -=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. @@ -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 and L 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, C, or C. =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 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 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 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 (post-image git blob ID) and C (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, C, C, C, or C. Default: C -=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. 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 or similar Default: server-dependent unless socket activation is used with L or similar (see L). -=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 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 and L Perl modules. =over -=item --jobs=JOBS, -j +=item -j JOBS + +=item --jobs=JOBS ... TODO, see L 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, the C prefix (e.g. C 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) 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 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. Either the configured section name (e.g. C) 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 if you have L installed. @@ -31,7 +33,9 @@ L. Default: C<1> -=item -L, --indexlevel +=item -L + +=item --indexlevel Controls the indexing level for L @@ -39,7 +43,9 @@ See L for more information. Default: C -=item --ng, --newsgroup NEWSGROUP +=item --ng NEWSGROUP + +=item --newsgroup NEWSGROUP The NNTP group name for use with L. 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) 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) 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, the protocol prefix (e.g. C 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 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 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 inbox to C shards . Since L is not suitable @@ -52,7 +56,11 @@ existing Xapian database(s) to any positive value of C. 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 when used with C<--compact>. -- 2.31.1