[Apt-listbugs-commits] [apt-listbugs] 02/05: reformat the whole man page
Francesco Poli
frx-guest at moszumanska.debian.org
Sun Sep 25 10:43:10 UTC 2016
This is an automated email from the git hooks/post-receive script.
frx-guest pushed a commit to branch master
in repository apt-listbugs.
commit bf54e6b7994b3f91a7bc2b079f7573826fe50e6a
Author: Francesco Poli (wintermute) <invernomuto at paranoici.org>
Date: Sat Sep 17 22:33:34 2016 +0200
reformat the whole man page
---
bin/apt-listbugs | 236 ++++++++++++++++++++++++-----------------------
debian/changelog | 4 +
lib/aptlistbugs/logic.rb | 4 +-
3 files changed, 129 insertions(+), 115 deletions(-)
diff --git a/bin/apt-listbugs b/bin/apt-listbugs
index c0b0532..1e5af41 100755
--- a/bin/apt-listbugs
+++ b/bin/apt-listbugs
@@ -28,172 +28,178 @@
#
=begin
-== NAME
+= NAME
apt-listbugs - Lists critical bugs before each APT installation/upgrade
-== SYNOPSIS
+= SYNOPSIS
-apt-listbugs [options] <command> [arguments]
+(({apt-listbugs})) [(({-s})) ((*severities*))] [(({-T})) ((*tags*))]
+[(({-S})) ((*states*))] [(({-B})) ((*bug#*))] [(({-D}))]
+[(({-H})) ((*hostname*))] [(({-p})) ((*port*))] [(({-P})) ((*priority*))]
+[(({-E})) ((*title*))] [(({-q}))] [(({-C})) ((*apt.conf*))] [(({-F}))]
+[(({-N}))] [(({-y}))] [(({-n}))] [(({-d}))]
+((*command*)) [((*argument*)) ...]
-== DESCRIPTION
+(({apt-listbugs -h}))
-apt-listbugs is a tool which retrieves bug reports from the Debian
+(({apt-listbugs -v}))
+
+= DESCRIPTION
+
+(({apt-listbugs})) is a tool which retrieves bug reports from the Debian
Bug Tracking System and lists them. In particular, it is intended to
be invoked before each installation or upgrade by APT, or other
similar package managers, in order to check whether the
installation/upgrade is safe.
-== USAGE
-
-apt-listbugs [-h] [-v] [-s <severities>] [-T <tags>] [-S <states>] [-B <bug#>] [-D] [-H <hostname>] [-p <port>] [-P <priority>] [-E <title>] [-q] [-C <apt.conf>] [-F] [-N] [-y] [-n] [-d] <command> [arguments]
-
-== OPTIONS
-
-* -h, --help
-
- Print usage help and exit.
+= OPTIONS
-* -v, --version
-
- Print version number and exit.
-
-* -s <severities>, --severity <severities>
+: -s ((*severities*)), --severity ((*severities*))
Filter (and sort) bugs by severity, showing only the bugs matching
specified values. List the bug severities that you want to see,
separated by commas and in the desired order. Possible values are
- "critical", "grave", "serious", "important", "normal", "minor",
- "wishlist", or the special value "all" to disable filtering.
- Default: [critical,grave,serious]. The default list may be
- changed by setting the AptListbugs::Severities configuration option.
+ (({critical})), (({grave})), (({serious})), (({important})),
+ (({normal})), (({minor})), (({wishlist})), or the special value
+ (({all})) to disable filtering.
+ Default: (({critical,grave,serious})). The default list may be
+ changed by setting the (({AptListbugs::Severities})) configuration option.
-* -T <tags>, --tag <tags>
+: -T ((*tags*)), --tag ((*tags*))
- Filter bugs by tags, showing only the bugs matching _all_ specified
+ Filter bugs by tags, showing only the bugs matching all specified
values. List the tags that you want to see, separated by commas.
- Default: no filter. Possible values include "confirmed,l10n" to show
+ Default: no filter. Possible values include (({confirmed,l10n})) to show
only bugs that have both these tags.
-* -S <states>, --stats <states>
+: -S ((*states*)), --stats ((*states*))
Filter (and sort) bugs by pending-state, showing only the bugs
matching specified values. List the pending-state categories that
you want to see, separated by commas and in the desired order.
- Default: [pending,forwarded,pending-fixed,fixed,done]. Possible values are:
-
- pending = open bug
- forwarded = marked as "forwarded"
- pending-fixed = tagged as "pending"
- fixed = tagged as "fixed"
- absent = not found in this distribution/architecture
- done = resolved in some version for this
- distribution/architecture
-
+ Default: (({pending,forwarded,pending-fixed,fixed,done})). Possible
+ values are:
+ (({pending})) (open bug),
+ (({forwarded})) (marked as "forwarded"),
+ (({pending-fixed})) (tagged as "pending"),
+ (({fixed})) (tagged as "fixed"),
+ (({absent})) (not found in this distribution/architecture),
+ (({done})) (resolved in some version for this distribution/architecture).
Note that a bug can only match one such state (when multiple
conditions on this list match, the later one takes priority), and
- that "pending" does not mean "tagged as pending".
+ that (({pending})) does not mean "tagged as pending".
-* -B <bug#>, --bugs <bug#>
+: -B ((*bug#*)), --bugs ((*bug#*))
Filter bugs by number, showing only the bugs directly specified.
List the bug numbers that you want to see, separated by commas
- (e.g. "123456,567890,135792"). Default: no filter.
+ (e.g. (({123456,567890,135792}))). Default: no filter.
-* -D, --show-downgrade
+: -D, --show-downgrade
Show bugs of downgraded packages. (apt mode only)
-* -H <hostname>, --hostname <hostname>
+: -H ((*hostname*)), --hostname ((*hostname*))
- Specifies the hostname of the Debian Bug Tracking System [bugs.debian.org].
+ Specifies the hostname of the Debian Bug Tracking System. Default:
+ (({bugs.debian.org})) .
-* -p <port>, --port <port>
+: -p ((*port*)), --port ((*port*))
Specifies the port number of the web interface of the Debian Bug
- Tracking System [80].
+ Tracking System. Default: 80.
-* -P <priority>, --pin-priority <priority>
+: -P ((*priority*)), --pin-priority ((*priority*))
- Specifies Pin-Priority value [30000].
+ Specifies (({Pin-Priority})) value. Default: 30000.
-* -E <title>, --title <title>
+: -E ((*title*)), --title ((*title*))
Specifies the title of RSS output.
-* -q, --quiet
+: -q, --quiet
Don't display progress bar. This option is assumed if stdout is not a
terminal.
-* -C <apt.conf>, --aptconf <apt.conf>
+: -C ((*apt.conf*)), --aptconf ((*apt.conf*))
Specifies the APT configuration file to use.
-* -F, --force-pin
+: -F, --force-pin
When in apt mode, assumes that you want to automatically pin all buggy
packages without any prompt. This option is assumed if stdout is not a
- terminal, unless the "-N" command-line option is used.
+ terminal, unless the (({-N})) command-line option is used.
-* -N, --force-no-pin
+: -N, --force-no-pin
When in apt mode, never automatically pin any package without prompt.
This is the default behavior, as long as stdout is a terminal.
-* -y, --force-yes
+: -y, --force-yes
Assumes that you select yes for all questions. When in apt mode,
this implies that you accept to continue with the installation/upgrade,
even when bugs are found or errors occur.
-* -n, --force-no
+: -n, --force-no
Assumes that you select no for all questions. When in apt mode,
this implies that you want to abort the installation/upgrade, as
soon as bugs are found or errors occur. This option is assumed
- if stdout is not a terminal, unless the "-y" command-line option is used.
+ if stdout is not a terminal, unless the (({-y})) command-line option is used.
-* -d, --debug
+: -d, --debug
Give extra debug output, important for debugging problems. Please
- include -d when reporting problems.
+ include (({-d})) when reporting problems.
+
+: -h, --help
-== COMMANDS
+ Print usage help and exit.
+
+: -v, --version
+
+ Print version number and exit.
+
+= COMMANDS
: apt
Reads package actions from a file descriptor specified in the
- APT_HOOK_INFO_FD environment variable (typically provided by APT
- or other compatible package manager; Pre-Install-Pkgs hook info
- protocol version 3 is expected - see apt.conf(5) for more details).
+ $(({APT_HOOK_INFO_FD})) environment variable (typically provided by APT
+ or other compatible package manager; (({Pre-Install-Pkgs})) hook info
+ protocol version 3 is expected - see (({apt.conf}))(5) for more details).
-: list [<package1[:arch][/version]> <package2[:arch][/version]>...]
+: list [((*package*))[:((*arch*))][/((*version*))] ...]
Reads package names from the arguments and simply lists bugs of
these packages. Package versions may be specified with a slash, as in
- apt/1.0 for example. Package architectures may be specified with a colon,
- as in apt:amd64 or apt:amd64/1.0 (but please note that the Debian Bug
- Tracking System does not distinguish the architectures, hence the
- same bugs will be listed, regardless of the specified architecture).
+ (({apt/1.0})) for example. Package architectures may be specified
+ with a colon, as in (({apt:amd64})) or (({apt:amd64/1.0})) (but please
+ note that the Debian Bug Tracking System does not distinguish the
+ architectures, hence the same bugs will be listed, regardless of the
+ specified architecture).
-: rss [<package1[:arch][/version]> <package2[:arch][/version]>...]
+: rss [((*package*))[:((*arch*))][/((*version*))] ...]
Reads package names from the arguments and lists bugs of these packages
in RSS format. Again, package versions may be specified with a slash
and architectures with a colon.
-== ENVIRONMENT VARIABLES
+= ENVIRONMENT VARIABLES
: APT_LISTBUGS_FRONTEND
- If this variable is set to "none", apt-listbugs will not execute at all;
- this might be useful if you would like to script the use of a program that
- calls apt-listbugs.
+ If this variable is set to "none", (({apt-listbugs})) will not execute
+ at all; this might be useful if you would like to script the use of a
+ program that calls (({apt-listbugs})).
: http_proxy
- If http_proxy is set, the value is used for HTTP Proxy, unless
+ If $(({http_proxy})) is set, the value is used for HTTP Proxy, unless
proxy settings are found in APT configuration (see below).
: APT_HOOK_INFO_FD
@@ -202,37 +208,37 @@ apt-listbugs [-h] [-v] [-s <severities>] [-T <tags>] [-S <states>] [-B <bug#>] [
compatible package managers are expected to write information to this
file descriptor and to properly set this environment variable).
-== CONFIGURATION FILE
+= CONFIGURATION FILE
-apt-listbugs understands APT configuration file (see apt.conf). The
-notable configuration options are
+(({apt-listbugs})) understands APT configuration file (see (({apt.conf}))(5)
+for more details). The notable configuration options are
: Acquire::http::Proxy
- Default HTTP Proxy setting (overrides any http_proxy environment variable
- value).
- An empty string or the special keyword 'DIRECT' will disable proxy.
+ Default HTTP Proxy setting (overrides any $(({http_proxy})) environment
+ variable value).
+ An empty string or the special keyword "DIRECT" will disable proxy.
: Acquire::http::Proxy-Auto-Detect
Automatic HTTP Proxy discovery (overrides the default HTTP Proxy setting
- and any http_proxy environment variable value).
+ and any $(({http_proxy})) environment variable value).
It can be used to specify an external command that is expected to output
the proxy on stdout.
: Acquire::http::Proxy::bugs.debian.org
Specific HTTP Proxy setting (overrides any other proxy setting).
- Useful for setting HTTP proxy for apt-listbugs.
- The special keyword 'DIRECT' will disable proxy.
+ Useful for setting HTTP proxy for (({apt-listbugs})).
+ The special keyword "DIRECT" will disable proxy.
: AptListbugs::Severities
Default (comma-separated) list of bug severities to be shown. When
- this option is not set, the list is [critical,grave,serious], unless
- explicitly altered by using the "-s" command-line option. On the other
+ this option is not set, the list is "critical,grave,serious", unless
+ explicitly altered by using the (({-s})) command-line option. On the other
hand, when this option is set, the list of severities is its value,
- unless explicitly altered by using the "-s" command-line option.
+ unless explicitly altered by using the (({-s})) command-line option.
: AptListbugs::IgnoreRegexp
@@ -245,44 +251,41 @@ notable configuration options are
Maximum number of packages to be queried (on the Debian Bug Tracking
System) in a single batch. Default value is 200. The query operation is
- performed in batches of at most QueryStep packages, for performance
- reasons; setting a lower value may slow down apt-listbugs, but may
+ performed in batches of at most (({QueryStep})) packages, for performance
+ reasons; setting a lower value may slow down (({apt-listbugs})), but may
increase reliability on poor network links.
: AptListbugs::ParseStep
Maximum number of bug reports to be queried (on the Debian Bug Tracking
System) and parsed in a single batch. Default value is 200. The query
- and parse operation is performed in batches of at most ParseStep bugs,
- for performance reasons; setting a lower value may slow down apt-listbugs,
- but may increase reliability on poor network links.
+ and parse operation is performed in batches of at most (({ParseStep})) bugs,
+ for performance reasons; setting a lower value may slow down
+ (({apt-listbugs})), but may increase reliability on poor network links.
-== OUTPUT EXAMPLE
+= OUTPUT EXAMPLE
[bug severity] bugs of [package] ([current version] -> [package version to be installed]) <[state of bug report]>
- [bug #] - [bug title] [(Fixed: fixed version, if it's fixed in a future version)]
-
- e.g.
+ [bN] - [#bug] - [bug title] [(Fixed: fixed version, if it's fixed in a future version)]
+ Summary:
+ [package]([number of] bugs)
+e.g.:
- Retrieving bug reports... Done
- Parsing Found/Fixed information... Done
important bugs of apt-listbugs (0.0.47 -> 0.0.49) <Outstanding>
b1 - #332442 - apt-listbugs: Apt-listbugs doesn't actually download any bug reports
b2 - #389903 - apt-listbugs: Does not offer to exit if timeout occurs fetching reports
Summary:
apt-listbugs(2 bugs)
-
-
-== EXIT STATUS
+= EXIT STATUS
: 0
If the program ran successfully and (when in apt mode) you decided
to continue with the installation/upgrade. Or otherwise, if a SIGUSR1
- was received (for instance because you issued the command "killall
- -USR1 apt-listbugs").
+ was received (for instance because you issued the command (({killall
+ -USR1 apt-listbugs}))).
: 1
@@ -300,23 +303,30 @@ notable configuration options are
N.B.: When the program is invoked by APT, any non-zero exit status will
cause the installation/upgrade to be aborted.
-== AUTHORS
+= AUTHORS
+
+2002 - 2004: (({apt-listbugs})) was originally written by Masato Taruishi
+<taru at debian.org>.
+
+2006 - 2008: Junichi Uekawa <dancer at debian.org> rewrote it to handle BTS
+Versioning features and the SOAP interface. The (({--bugs})) option was
+added by Francesco Poli in 2008.
+
+2009 - 2010: (({apt-listbugs})) was maintained by Francesco Poli
+<invernomuto at paranoici.org> and Ryan Niebur <ryan at debian.org>
+
+2011 - 2012: maintenance was carried on by Francesco Poli and Thomas
+Mueller <thomas.mueller at tmit.eu>.
-apt-listbugs was originally written by Masato Taruishi
-<taru at debian.org>, and rewritten by Junichi Uekawa
-<dancer at debian.org> in 2006 to handle BTS Versioning features and the
-SOAP interface. The --bugs option was added by Francesco Poli
-<invernomuto at paranoici.org> in 2008. During 2009-2010, apt-listbugs was
-maintained by Francesco Poli and Ryan Niebur <ryan at debian.org>, then, during
-2011-2012, by Francesco Poli and Thomas Mueller <thomas.mueller at tmit.eu>.
-It is currently maintained by Francesco Poli.
+2013 - present day: (({apt-listbugs})) has been maintained by Francesco Poli.
The latest source code is available from
-https://anonscm.debian.org/cgit/apt-listbugs/apt-listbugs.git/
+((<"https://anonscm.debian.org/cgit/apt-listbugs/apt-listbugs.git/"|URL:https://anonscm.debian.org/cgit/apt-listbugs/apt-listbugs.git/>))
-== SEE ALSO
+= SEE ALSO
-apt.conf(5), sensible-browser(1), www-browser(1), querybts(1)
+(({apt.conf}))(5), (({sensible-browser}))(1), (({www-browser}))(1),
+(({querybts}))(1)
=end
diff --git a/debian/changelog b/debian/changelog
index 8df7ada..4a7e1ce 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -6,6 +6,10 @@ apt-listbugs (0.1.19) UNRELEASED; urgency=medium
* improved the man page:
- made it claim to document apt-listbugs(1), rather than
bin/apt-listbugs(1)
+ - reformatted the whole document, to better comply with man page
+ usual conventions
+ * moved a couple of options in the online help to reflect the new option
+ ordering in the man page
-- Francesco Poli (wintermute) <invernomuto at paranoici.org> Thu, 21 Jul 2016 21:38:41 +0200
diff --git a/lib/aptlistbugs/logic.rb b/lib/aptlistbugs/logic.rb
index 7a416d4..ec3726e 100644
--- a/lib/aptlistbugs/logic.rb
+++ b/lib/aptlistbugs/logic.rb
@@ -49,8 +49,6 @@ class AppConfig
"\n",
_("Options:\n"),
# TRANSLATORS: the colons (:) in the following strings are vertically aligned, please keep their alignment consistent
- _(" -h : Display this help and exit.\n"),
- _(" -v : Show version number and exit.\n"),
# TRANSLATORS: the \"all\" between quotes should not be translated
sprintf(_(" -s <severities> : Filter bugs by severities you want to see\n (or \"all\" for all)\n [%s].\n"), @severity.join(',')),
_(" -T <tags> : Filter bugs by tags you want to see.\n"),
@@ -68,6 +66,8 @@ class AppConfig
_(" -y : Assume that you select yes for all questions.\n"),
_(" -n : Assume that you select no for all questions.\n"),
_(" -d : Debug.\n"),
+ _(" -h : Display this help and exit.\n"),
+ _(" -v : Show version number and exit.\n"),
_("Commands:\n"),
_(" apt : Apt mode.\n"),
_(" list <pkg...> : List bug reports of the specified packages.\n"),
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/apt-listbugs/apt-listbugs.git
More information about the Apt-listbugs-commits
mailing list