This is an automated email from the git hooks/post-receive script. guillem pushed a commit to branch master in repository dpkg.
View the commit online: https://git.dpkg.org/cgit/dpkg/dpkg.git/commit/?id=8a544d09efc3c3be438fe77a8ab78d1b971eb1f6 commit 8a544d09efc3c3be438fe77a8ab78d1b971eb1f6 Author: Guillem Jover <[email protected]> AuthorDate: Tue May 5 05:20:40 2020 +0200 man: Unify warning and note admonitions formatting Capitalize first words after the admonitions. Use bold for notes and warnings, and italic for warnings if the contents makes using bold ambiguous. --- debian/changelog | 1 + man/dpkg-buildpackage.man | 5 +++-- man/dpkg-divert.man | 4 ++-- man/dpkg-gensymbols.man | 4 ++-- man/dpkg-name.man | 8 ++++++-- man/dpkg-parsechangelog.man | 7 +++++-- man/dpkg-scansources.man | 4 +++- man/dpkg-shlibdeps.man | 2 +- man/dpkg-source.man | 4 ++-- man/dpkg-statoverride.man | 4 ++-- man/dpkg.man | 25 +++++++++++++++---------- man/start-stop-daemon.man | 20 ++++++++++++++------ 12 files changed, 56 insertions(+), 32 deletions(-) diff --git a/debian/changelog b/debian/changelog index a2ee2f611..c75f16de1 100644 --- a/debian/changelog +++ b/debian/changelog @@ -31,6 +31,7 @@ dpkg (1.20.1) UNRELEASED; urgency=medium - man: Clarify and fix file formats SYNOPSIS. - man: Clarify that deb-control(5) is a subset of deb-src-control(5). Closes: #958229 + - man: Unify warning and note admonitions formatting. * Build system: - Handle .git being a plain file when getting the dpkg tree version. - Add debian/changelog as a Changes file to the CPAN distribution. diff --git a/man/dpkg-buildpackage.man b/man/dpkg-buildpackage.man index f98bd04f3..3f9b87282 100644 --- a/man/dpkg-buildpackage.man +++ b/man/dpkg-buildpackage.man @@ -120,7 +120,8 @@ The allowed values are: .TP .B source Builds the source package. -Note: when using this value standalone and if what you want is simply to +.IP +\fBNote:\fP When using this value standalone and if what you want is simply to (re-)build the source package from a clean source tree, using \fBdpkg\-source\fP directly is always a better option as it does not require any build dependencies to be installed which are otherwise @@ -369,7 +370,7 @@ always be executed even if the following action is not performed (except for the \fBbinary\fP hook). All the hooks will run in the unpacked source directory. -Note: Hooks can affect the build process, and cause build failures if +\fBNote:\fP Hooks can affect the build process, and cause build failures if their commands fail, so watch out for unintended consequences. The current \fIhook-name\fP supported are: diff --git a/man/dpkg-divert.man b/man/dpkg-divert.man index b37a4852f..cacba7908 100644 --- a/man/dpkg-divert.man +++ b/man/dpkg-divert.man @@ -156,8 +156,8 @@ The currently accepted values are: \fBauto\fP (default), \fBalways\fP and File which contains the current list of diversions of the system. It is located in the \fBdpkg\fP administration directory, along with other files important to \fBdpkg\fP, such as \fIstatus\fP or \fIavailable\fP. -.br -Note: \fBdpkg\-divert\fP preserves the old copy of this file, with extension +.IP +\fBNote:\fP \fBdpkg\-divert\fP preserves the old copy of this file, with extension \fI\-old\fP, before replacing it with the new one. . .SH NOTES diff --git a/man/dpkg-gensymbols.man b/man/dpkg-gensymbols.man index 0473f25dc..7ce32b66b 100644 --- a/man/dpkg-gensymbols.man +++ b/man/dpkg-gensymbols.man @@ -145,8 +145,8 @@ Prepend .I directory to the list of directories to search for private shared libraries (since dpkg 1.19.1). This option can be used multiple times. - -Note: Use this option instead of setting \fBLD_LIBRARY_PATH\fP, +.IP +\fBNote:\fP Use this option instead of setting \fBLD_LIBRARY_PATH\fP, as that environment variable is used to control the run-time linker and abusing it to set the shared library paths at build-time can be problematic when cross-compiling for example. diff --git a/man/dpkg-name.man b/man/dpkg-name.man index a686d5e4c..f17bcc693 100644 --- a/man/dpkg-name.man +++ b/man/dpkg-name.man @@ -65,12 +65,16 @@ and in this case, as well as for sections \fBnon\-free\fP and \fBcontrib\fP the target directory is «\fIsection\fP/binary\-\fIarchitecture\fP». The section field is not required so a lot of packages will find their way to the \fBno\-section\fP area. -Use this option with care, it's messy. +.IP +.B Warning: +.I Use this option with care, it is messy. .TP .BR \-c ", " \-\-create\-dir This option can used together with the \fB\-s\fP option. If a target directory isn't found it will be created automatically. -.B Use this option with care. +.IP +.B Warning: +.I Use this option with care. .TP .BR \-? ", " \-\-help Show the usage message and exit. diff --git a/man/dpkg-parsechangelog.man b/man/dpkg-parsechangelog.man index 728fe6eb4..3a8d26ea2 100644 --- a/man/dpkg-parsechangelog.man +++ b/man/dpkg-parsechangelog.man @@ -125,10 +125,13 @@ metadata for each entry is preserved. .TP .B \-\-reverse Include all changes in reverse order (since dpkg 1.19.1). -Note: for the \fBdpkg\fP format the first entry will be the most ancient entry. +.IP +\fBNote:\fP For the \fBdpkg\fP format the first entry will be the most ancient +entry. .TP .B \-\-all -Include all changes. Note: other options have no effect when this is in use. +Include all changes. +\fBNote:\fP Other options have no effect when this is in use. .TP .BR \-s ", " \-\-since " \fIversion\fP" .TQ diff --git a/man/dpkg-scansources.man b/man/dpkg-scansources.man index 6186dacbc..d896ce4f5 100644 --- a/man/dpkg-scansources.man +++ b/man/dpkg-scansources.man @@ -42,7 +42,9 @@ files. The file can be compressed (since dpkg 1.15.5). See .BR deb\-override (5) -for the format of this file. Note: Since +for the format of this file. +.IP +\fBNote:\fP Since the override file is indexed by binary, not source packages, there's a bit of a problem here. The current implementation uses the highest priority of all the binary packages produced by a \fI.dsc\fR file for the priority of the diff --git a/man/dpkg-shlibdeps.man b/man/dpkg-shlibdeps.man index 3984e0336..7455415f5 100644 --- a/man/dpkg-shlibdeps.man +++ b/man/dpkg-shlibdeps.man @@ -145,7 +145,7 @@ Prepend to the list of directories to search for private shared libraries (since dpkg 1.17.0). This option can be used multiple times. -Note: Use this option instead of setting \fBLD_LIBRARY_PATH\fP, +\fBNote:\fP Use this option instead of setting \fBLD_LIBRARY_PATH\fP, as that environment variable is used to control the run-time linker and abusing it to set the shared library paths at build-time can be problematic when cross-compiling for example. diff --git a/man/dpkg-source.man b/man/dpkg-source.man index dca4b4cda..67c00dc8f 100644 --- a/man/dpkg-source.man +++ b/man/dpkg-source.man @@ -559,7 +559,7 @@ files as well as many temporary files (see default value associated to \fB.pc\fP directory used by \fBquilt\fP is ignored during generation of the automatic patch. -Note: \fBdpkg\-source\fP \fB\-\-before\-build\fP (and \fB\-\-build\fP) will +\fBNote:\fP \fBdpkg\-source\fP \fB\-\-before\-build\fP (and \fB\-\-build\fP) will ensure that all patches listed in the series file are applied so that a package build always has all patches applied. It does this by finding unapplied patches (they are listed in the \fBseries\fP file but not in @@ -853,7 +853,7 @@ Here's an example of such a file: # ignore changes on config.{sub,guess} extend-diff-ignore = "(^|/)(config\.sub|config\.guess)$" .P -Note: \fBformat\fR options are not accepted in this file, you should +\fBNote:\fP \fBformat\fR options are not accepted in this file, you should use \fBdebian/source/format\fR instead. .SS debian/source/local\-options Exactly like \fBdebian/source/options\fP except that the file is not diff --git a/man/dpkg-statoverride.man b/man/dpkg-statoverride.man index e6e64945b..984b2898e 100644 --- a/man/dpkg-statoverride.man +++ b/man/dpkg-statoverride.man @@ -168,8 +168,8 @@ The currently accepted values are: \fBauto\fP (default), \fBalways\fP and File which contains the current list of stat overrides of the system. It is located in the \fBdpkg\fP administration directory, along with other files important to \fBdpkg\fP, such as \fIstatus\fP or \fIavailable\fP. -.br -Note: \fBdpkg\-statoverride\fP preserves the old copy of this file, with +.IP +\fBNote:\fP \fBdpkg\-statoverride\fP preserves the old copy of this file, with extension “\-old”, before replacing it with the new one. . .SH SEE ALSO diff --git a/man/dpkg.man b/man/dpkg.man index 72afc5a06..9d3db958b 100644 --- a/man/dpkg.man +++ b/man/dpkg.man @@ -223,7 +223,7 @@ If \fB\-a\fP or \fB\-\-pending\fP is given instead of a package name, then all packages unpacked or removed, but marked to be purged in file \fI%ADMINDIR%/status\fP, are purged. -Note: some configuration files might be unknown to \fBdpkg\fP because they +\fBNote:\fP Some configuration files might be unknown to \fBdpkg\fP because they are created and handled separately through the configuration scripts. In that case, \fBdpkg\fP won't remove them by itself, but the package's \fIpostrm\fP script (which is called by \fBdpkg\fP), has to take care of @@ -327,7 +327,7 @@ to deinstall any packages not in list given to \fB\-\-set\-selections\fP. Searches for packages selected for installation, but which for some reason still haven't been installed. .IP -Note: This command makes use of both the available file and the package +\fBNote:\fP This command makes use of both the available file and the package selections. .TP .B \-\-predep\-package @@ -337,7 +337,7 @@ pre-dependencies and has itself no unsatisfied pre-dependencies. If such a package is present, output it as a Packages file entry, which can be massaged as appropriate. .IP -Note: This command makes use of both the available file and the package +\fBNote:\fP This command makes use of both the available file and the package selections. .IP Returns 0 when a package is printed, 1 when no suitable package is @@ -427,9 +427,11 @@ be used, due to confusing semantics. To illustrate: \fB0.1 < 0.1\fP evaluates to true. .\" .TP .\" .B \-\-command\-fd \fIn\fP -.\" Accept a series of commands on input file descriptor \fIn\fP. Note: -.\" additional options set on the command line, and through this file descriptor, -.\" are not reset for subsequent commands executed during the same run. +.\" Accept a series of commands on input file descriptor \fIn\fP. +.\" .IP +.\" \fBNote:\fP Additional options set on the command line, and through this +.\" file descriptor, are not reset for subsequent commands executed during the +.\" same run. .TP .BR \-? ", " \-\-help Display a brief help message. @@ -561,7 +563,7 @@ package depends. \fBhold\fP: Allow automatic installs, upgrades or removals of packages even when marked to be on “hold”. -Note: This does not prevent these actions when requested explicitly. +\fBNote:\fP This does not prevent these actions when requested explicitly. \fBremove\-reinstreq\fP: Remove a package, even if it's broken and marked to require @@ -746,7 +748,9 @@ since dpkg 1.17.19). This option can be specified multiple times. The order the options are specified is preserved, with the ones from the configuration files taking precedence. The environment variable \fBDPKG_HOOK_ACTION\fP is set for the hooks to the -current \fBdpkg\fP action. Note: front-ends might call \fBdpkg\fP several +current \fBdpkg\fP action. +.IP +\fBNote:\fP Front-ends might call \fBdpkg\fP several times per invocation, which might run the hooks more times than expected. .TP .BI \-\-path\-exclude= glob-pattern @@ -756,7 +760,7 @@ Set \fIglob-pattern\fP as a path filter, either by excluding or re-including previously excluded paths matching the specified patterns during install (since dpkg 1.15.8). -\fIWarning: take into account that depending on the excluded paths you +\fIWarning: Take into account that depending on the excluded paths you might completely break your system, use with caution.\fP The glob patterns use the same wildcards used in the shell, were @@ -768,7 +772,8 @@ As usual, ‘?’ matches any single character (again, including ‘/’). And ‘[’ starts a character class, which can contain a list of characters, ranges and complementations. See \fBglob\fP(7) for detailed information about -globbing. Note: the current implementation might re-include more directories +globbing. +\fBNote:\fP The current implementation might re-include more directories and symlinks than needed, to be on the safe side and avoid possible unpack failures; future work might fix this. diff --git a/man/start-stop-daemon.man b/man/start-stop-daemon.man index 3375ecb65..47aa35dbe 100644 --- a/man/start-stop-daemon.man +++ b/man/start-stop-daemon.man @@ -36,7 +36,7 @@ is used to control the creation and termination of system-level processes. Using one of the matching options, \fBstart\-stop\-daemon\fP can be configured to find existing instances of a running process. .PP -Note: unless +\fBNote:\fP Unless .B \-\-pid or .B \-\-pidfile @@ -119,11 +119,11 @@ The \fIppid\fP must be a number greater than 0. .BR \-p ", " \-\-pidfile " \fIpidfile\fP" Check whether a process has created the file \fIpidfile\fP. .IP -Note: using this matching option alone might cause unintended processes to +\fBNote:\fP Using this matching option alone might cause unintended processes to be acted on, if the old process terminated without being able to remove the \fIpidfile\fP. .IP -\fBWarning:\fP using this match option with a world-writable pidfile or using +\fBWarning:\fP Using this match option with a world-writable pidfile or using it alone with a daemon that writes the pidfile as an unprivileged (non-root) user will be refused with an error (since version 1.19.3) as this is a security risk, because either any user can write to it, or if the daemon @@ -134,7 +134,9 @@ Using \fI/dev/null\fP is exempt from these checks. .TP .BR \-x ", " \-\-exec " \fIexecutable\fP" Check for processes that are instances of this \fIexecutable\fP. The -\fIexecutable\fP argument should be an absolute pathname. Note: this might +\fIexecutable\fP argument should be an absolute pathname. +.IP +\fBNote:\fP This might not work as intended with interpreted scripts, as the executable will point to the interpreter. Take into account processes running from inside a chroot will also be matched, so other match restrictions might be needed. @@ -142,13 +144,17 @@ will also be matched, so other match restrictions might be needed. .BR \-n ", " \-\-name " \fIprocess-name\fP" Check for processes with the name \fIprocess-name\fP. The \fIprocess-name\fP is usually the process filename, but it could have been changed by the -process itself. Note: on most systems this information is retrieved from +process itself. +.IP +\fBNote:\fP On most systems this information is retrieved from the process comm name from the kernel, which tends to have a relatively short length limit (assuming more than 15 characters is non-portable). .TP .BR \-u ", " \-\-user " \fIusername\fP|\fIuid\fP Check for processes owned by the user specified by \fIusername\fP or -\fIuid\fP. Note: using this matching option alone will cause all processes +\fIuid\fP. +.IP +\fBNote:\fP Using this matching option alone will cause all processes matching the user to be acted on. . .SS Generic options @@ -263,6 +269,7 @@ Typically used with programs that don't detach on their own. This option will force .B start\-stop\-daemon to fork before starting the process, and force it into the background. +.IP .B Warning: start\-stop\-daemon cannot check the exit status if the process fails to execute for .B any @@ -334,6 +341,7 @@ create the file referenced with and place the pid into it just before executing the process. Note, the file will only be removed when stopping the program if \fB\-\-remove\-pidfile\fP is used. +.IP .B Note: This feature may not work in all cases. Most notably when the program being executed forks from its main process. Because of this, it is usually -- Dpkg.Org's dpkg
