This is an automated email from the git hooks/post-receive script. guillem pushed a commit to branch main in repository dpkg.
View the commit online: https://git.dpkg.org/cgit/dpkg/dpkg.git/commit/?id=be93550bfab8c7cc698f7b5c0939d8095e421a00 commit be93550bfab8c7cc698f7b5c0939d8095e421a00 Author: Guillem Jover <[email protected]> AuthorDate: Fri Feb 10 02:05:30 2023 +0100 man: Unify admonition markup and formatting Use bold for the admonition keyword, but not for the colon. Stop marking up the text of the admonition as italic. --- man/deb-substvars.pod | 2 +- man/dpkg-buildflags.pod | 2 +- man/dpkg-buildpackage.pod | 9 +++++---- man/dpkg-divert.pod | 2 +- man/dpkg-gensymbols.pod | 2 +- man/dpkg-maintscript-helper.pod | 4 ++-- man/dpkg-name.pod | 6 ++---- man/dpkg-parsechangelog.pod | 4 ++-- man/dpkg-query.pod | 4 ++-- man/dpkg-scanpackages.pod | 2 +- man/dpkg-scansources.pod | 4 ++-- man/dpkg-shlibdeps.pod | 2 +- man/dpkg-source.pod | 6 +++--- man/dpkg-statoverride.pod | 6 +++--- man/dpkg.pod | 34 +++++++++++++++++----------------- man/dsc.pod | 2 +- man/start-stop-daemon.pod | 16 ++++++++-------- man/update-alternatives.pod | 2 +- 18 files changed, 54 insertions(+), 55 deletions(-) diff --git a/man/deb-substvars.pod b/man/deb-substvars.pod index 517675fae..5b74c5df8 100644 --- a/man/deb-substvars.pod +++ b/man/deb-substvars.pod @@ -169,7 +169,7 @@ file and symlink rounded to 1 KiB used units, and a baseline of 1 KiB for any other filesystem object type. With hardlinks only being counted once as a regular file. -B<Note:> Take into account that this can only ever be an approximation, +B<Note>: Take into account that this can only ever be an approximation, as the actual size used on the installed system will depend greatly on the filesystem used and its parameters, which might end up using either more or less space than the specified in this field. diff --git a/man/dpkg-buildflags.pod b/man/dpkg-buildflags.pod index 01c14269e..987b9ced0 100644 --- a/man/dpkg-buildflags.pod +++ b/man/dpkg-buildflags.pod @@ -581,7 +581,7 @@ might need to make sure that when building the shared libraries B<-fPIC> is always passed last (so that it overrides any previous B<-PIE>) to compilation flags such as B<CFLAGS>, and B<-shared> is passed last (so that it overrides any previous B<-pie>) to linking flags such as -B<LDFLAGS>. B<Note:> This should not be needed with the default +B<LDFLAGS>. B<Note>: This should not be needed with the default gcc specs machinery. Additionally, since PIE is implemented via a general register, some diff --git a/man/dpkg-buildpackage.pod b/man/dpkg-buildpackage.pod index e4b0c2cf7..f29c86b6f 100644 --- a/man/dpkg-buildpackage.pod +++ b/man/dpkg-buildpackage.pod @@ -159,7 +159,7 @@ The allowed values are: Builds the source package. -B<Note:> When using this value standalone and if what you want is simply to +B<Note>: When using this value standalone and if what you want is simply to (re-)build the source package from a clean source tree, using B<dpkg-source> directly is always a better option as it does not require any build dependencies to be installed which are otherwise @@ -347,7 +347,7 @@ thus forcing the parallel setting on the packaging (and possibly the upstream build system if that uses L<make(1)>) regardless of their support for parallel builds, which might cause build failures. -Note: Any Makefile that is not parallel-safe should be considered to be buggy. +B<Note>: Any Makefile that is not parallel-safe should be considered to be buggy. These should either be made parallel-safe, or marked as not being safe with the L<make(1)> B<.NOTPARALLEL> target. @@ -469,7 +469,7 @@ always be executed even if the following action is not performed (except for the B<binary> hook). All the hooks will run in the unpacked source directory. -B<Note:> Hooks can affect the build process, and cause build failures if +B<Note>: Hooks can affect the build process, and cause build failures if their commands fail, so watch out for unintended consequences. The current I<hook-name> supported are: @@ -557,7 +557,8 @@ B<--sign-keyid> since dpkg 1.21.10). Specify an OpenPGP I<key-file> containing the secret key to use when signing packages (since dpkg 1.21.10). -Note: For security reasons the I<key-file> is best kept locked with a password. +B<Note>: For security reasons the I<key-file> is best kept locked with a +password. =item B<-us>, B<--unsigned-source> diff --git a/man/dpkg-divert.pod b/man/dpkg-divert.pod index 8392611b3..774b09ef2 100644 --- a/man/dpkg-divert.pod +++ b/man/dpkg-divert.pod @@ -209,7 +209,7 @@ File which contains the current list of diversions of the system. It is located in the B<dpkg> administration directory, along with other files important to B<dpkg>, such as I<status> or I<available>. -B<Note:> B<dpkg-divert> preserves the old copy of this file, with extension +B<Note>: B<dpkg-divert> preserves the old copy of this file, with extension I<-old>, before replacing it with the new one. =back diff --git a/man/dpkg-gensymbols.pod b/man/dpkg-gensymbols.pod index fcf69fdeb..c29e8c182 100644 --- a/man/dpkg-gensymbols.pod +++ b/man/dpkg-gensymbols.pod @@ -181,7 +181,7 @@ 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. -B<Note:> Use this option instead of setting B<LD_LIBRARY_PATH>, +B<Note>: Use this option instead of setting B<LD_LIBRARY_PATH>, 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-maintscript-helper.pod b/man/dpkg-maintscript-helper.pod index 9875e7aa2..0536a1b62 100644 --- a/man/dpkg-maintscript-helper.pod +++ b/man/dpkg-maintscript-helper.pod @@ -122,7 +122,7 @@ scripts. =head2 Removing a conffile -Note: This can be replaced in most cases by the C<remove-on-upgrade> +B<Note>: This can be replaced in most cases by the C<remove-on-upgrade> flag in F<DEBIAN/conffiles> (since dpkg 1.20.6), see L<deb-conffiles(5)>. If a conffile is completely removed, it should be removed from disk, @@ -189,7 +189,7 @@ When upgrading a package, B<dpkg> will not automatically switch a symlink to a directory or vice-versa. Downgrades are not supported and the path will be left as is. -Note: The symlinks and directories created during these switches need to +B<Note>: The symlinks and directories created during these switches need to be shipped in the new packages, or B<dpkg> will not be able to remove them on purge. diff --git a/man/dpkg-name.pod b/man/dpkg-name.pod index 66b3af6f9..496c7e6c7 100644 --- a/man/dpkg-name.pod +++ b/man/dpkg-name.pod @@ -73,16 +73,14 @@ the target directory is «I<section>/binary-I<architecture>». The section field is not required so a lot of packages will find their way to the B<no-section> area. -B<Warning:> -I<Use this option with care, it is messy.> +B<Warning>: Use this option with care, it is messy. =item B<-c>, B<--create-dir> This option can used together with the B<-s> option. If a target directory isn't found it will be created automatically. -B<Warning:> -I<Use this option with care.> +B<Warning>: Use this option with care. =item B<-?>, B<--help> diff --git a/man/dpkg-parsechangelog.pod b/man/dpkg-parsechangelog.pod index d89615829..52026ed04 100644 --- a/man/dpkg-parsechangelog.pod +++ b/man/dpkg-parsechangelog.pod @@ -151,13 +151,13 @@ metadata for each entry is preserved. Include all changes in reverse order (since dpkg 1.19.1). -B<Note:> For the B<dpkg> format the first entry will be the most ancient +B<Note>: For the B<dpkg> format the first entry will be the most ancient entry. =item B<--all> Include all changes. -B<Note:> Other options have no effect when this is in use. +B<Note>: Other options have no effect when this is in use. =item B<-s>, B<--since> I<version> diff --git a/man/dpkg-query.pod b/man/dpkg-query.pod index 7db0957d1..a2fb1e828 100644 --- a/man/dpkg-query.pod +++ b/man/dpkg-query.pod @@ -154,7 +154,7 @@ Z<> package diverts others to: I<diverted-to> diverted by I<pkg> to: I<diverted-to> -Hint: When machine parsing the output, it is customary to set the locale to +B<Hint>: When machine parsing the output, it is customary to set the locale to B<C.UTF-8> to get reproducible results. This command will not list extra files created by maintainer scripts, @@ -224,7 +224,7 @@ Z<> local diversion from: I<diverted-from> local diversion to: I<diverted-to> -Hint: When machine parsing the output, it is customary to set the locale to +B<Hint>: When machine parsing the output, it is customary to set the locale to B<C.UTF-8> to get reproducible results. =item B<-p>, B<--print-avail> [I<package-name>...] diff --git a/man/dpkg-scanpackages.pod b/man/dpkg-scanpackages.pod index cb686c6d5..963fec15c 100644 --- a/man/dpkg-scanpackages.pod +++ b/man/dpkg-scanpackages.pod @@ -47,7 +47,7 @@ B<dpkg-scanpackages> yourself if making a directory of local packages to install on a cluster of machines. -B<Note:> +B<Note>: If you want to access the generated Packages file with B<apt>(8) you will probably need to compress the file with diff --git a/man/dpkg-scansources.pod b/man/dpkg-scansources.pod index e5c2a9e1c..31114960b 100644 --- a/man/dpkg-scansources.pod +++ b/man/dpkg-scansources.pod @@ -46,7 +46,7 @@ See B<deb-override>(5) for the format of this file. -B<Note:> Since +B<Note>: 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 I<.dsc> file for the priority of the @@ -57,7 +57,7 @@ The I<path-prefix>, if given, is prepended to the directory field in the generated source index. You generally use this to make the directory fields contain the path from the top of the Debian archive hierarchy. -B<Note:> +B<Note>: If you want to access the generated Sources file with B<apt>(8) you will probably need to compress the file with diff --git a/man/dpkg-shlibdeps.pod b/man/dpkg-shlibdeps.pod index 7880ab85e..83a09c0b8 100644 --- a/man/dpkg-shlibdeps.pod +++ b/man/dpkg-shlibdeps.pod @@ -182,7 +182,7 @@ I<directory> to the list of directories to search for private shared libraries (since dpkg 1.17.0). This option can be used multiple times. -B<Note:> Use this option instead of setting B<LD_LIBRARY_PATH>, +B<Note>: Use this option instead of setting B<LD_LIBRARY_PATH>, 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.pod b/man/dpkg-source.pod index be5e2046e..435b4846c 100644 --- a/man/dpkg-source.pod +++ b/man/dpkg-source.pod @@ -263,7 +263,7 @@ directories. =back -B<Note:> +B<Note>: While they have similar purposes, B<-i> and B<-I> have very different syntax and semantics. B<-i> can only be specified once and takes a perl compatible regular expression which is matched against @@ -637,7 +637,7 @@ B<-i> option in the B<--help> output). In particular, the B<.pc> directory used by B<quilt> is ignored during generation of the automatic patch. -B<Note:> B<dpkg-source> B<--before-build> (and B<--build>) will +B<Note>: B<dpkg-source> B<--before-build> (and B<--build>) 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 B<series> file but not in @@ -997,7 +997,7 @@ Here's an example of such a file: # ignore changes on config.{sub,guess} extend-diff-ignore = "(^|/)(config.sub|config.guess)$" -B<Note:> B<format> options are not accepted in this file, you should +B<Note>: B<format> options are not accepted in this file, you should use B<debian/source/format> instead. =head2 debian/source/local-options diff --git a/man/dpkg-statoverride.pod b/man/dpkg-statoverride.pod index b21edcb56..839ea3389 100644 --- a/man/dpkg-statoverride.pod +++ b/man/dpkg-statoverride.pod @@ -116,9 +116,9 @@ I<things> is a comma separated list of things specified below. B<--force-help> displays a message describing them. Things marked with (*) are forced by default. -I<Warning: These options are mostly intended to be used by experts only. +B<Warning>: These options are mostly intended to be used by experts only. Using them without fully understanding their effects may break your whole -system.> +system. =over 4 @@ -229,7 +229,7 @@ File which contains the current list of stat overrides of the system. It is located in the B<dpkg> administration directory, along with other files important to B<dpkg>, such as I<status> or I<available>. -B<Note:> B<dpkg-statoverride> preserves the old copy of this file, with +B<Note>: B<dpkg-statoverride> preserves the old copy of this file, with extension “-old”, before replacing it with the new one. =back diff --git a/man/dpkg.pod b/man/dpkg.pod index 659dd0724..b69ff3ec6 100644 --- a/man/dpkg.pod +++ b/man/dpkg.pod @@ -297,7 +297,7 @@ If B<-a> or B<--pending> is given instead of a package name, then all packages unpacked or removed, but marked to be purged in file I<%ADMINDIR%/status>, are purged. -B<Note:> Some configuration files might be unknown to B<dpkg> because they +B<Note>: Some configuration files might be unknown to B<dpkg> because they are created and handled separately through the configuration scripts. In that case, B<dpkg> won't remove them by itself, but the package's I<postrm> script (which is called by B<dpkg>), has to take care of @@ -418,7 +418,7 @@ to deinstall any packages not in list given to B<--set-selections>. Searches for packages selected for installation, but which for some reason still haven't been installed. -B<Note:> This command makes use of both the available file and the package +B<Note>: This command makes use of both the available file and the package selections. =item B<--predep-package> @@ -429,7 +429,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. -B<Note:> This command makes use of both the available file and the package +B<Note>: This command makes use of both the available file and the package selections. Returns 0 when a package is printed, 1 when no suitable package is @@ -553,7 +553,7 @@ evaluates to true. Accept a series of commands on input file descriptor I<n>. -B<Note:> Additional options set on the command line, and through this +B<Note>: Additional options set on the command line, and through this file descriptor, are not reset for subsequent commands executed during the same run. @@ -709,9 +709,9 @@ to do some things. I<things> is a comma separated list of things specified below. B<--force-help> displays a message describing them. Things marked with (*) are forced by default. -I<Warning: These options are mostly intended to be used by experts +B<Warning>: These options are mostly intended to be used by experts only. Using them without fully understanding their effects may break -your whole system.> +your whole system. =over 2 @@ -723,12 +723,12 @@ Turns on (or off) all force options. Install a package, even if newer version of it is already installed. -I<Warning: At present> B<dpkg> I<does not do any dependency +B<Warning>: At present> B<dpkg> does not do any dependency checking on downgrades and therefore will not warn you if the downgrade breaks the dependency of some other package. This can have serious side effects, downgrading essential system components can even make your whole -system unusable. Use with care.> +system unusable. Use with care. =item B<configure-any>: @@ -739,7 +739,7 @@ package depends. Allow automatic installs, upgrades or removals of packages even when marked to be on “hold”. -B<Note:> When these actions are requested explicitly, the “hold” package +B<Note>: When these actions are requested explicitly, the “hold” package selection state always gets ignored. =item B<remove-reinstreq>: @@ -864,15 +864,15 @@ degradation and the data safety issues, the latter by making the file system not produce zero-length files on abrupt system crashes with any software not doing syncs before atomic renames. -I<Warning: Using this option might improve performance at the cost of -losing data, use with care.> +B<Warning>: Using this option might improve performance at the cost of +losing data, use with care. =item B<script-chrootless>: Run maintainer scripts without B<chroot>(2)ing into B<instdir> even if the package does not support this mode of operation (since dpkg 1.18.5). -I<Warning: This can destroy your host system, use with extreme care.> +B<Warning>: This can destroy your host system, use with extreme care. =item B<architecture>: @@ -977,7 +977,7 @@ is preserved, with the ones from the configuration files taking precedence. The environment variable B<DPKG_HOOK_ACTION> is set for the hooks to the current B<dpkg> action. -B<Note:> Front-ends might call B<dpkg> several +B<Note>: Front-ends might call B<dpkg> several times per invocation, which might run the hooks more times than expected. =item B<--path-exclude=>I<glob-pattern> @@ -988,8 +988,8 @@ Set I<glob-pattern> as a path filter, either by excluding or re-including previously excluded paths matching the specified patterns during install (since dpkg 1.15.8). -I<Warning: Take into account that depending on the excluded paths you -might completely break your system, use with caution.> +B<Warning>: Take into account that depending on the excluded paths you +might completely break your system, use with caution. The glob patterns use the same wildcards used in the shell, were ‘*’ matches any sequence of characters, including the empty string @@ -1001,7 +1001,7 @@ And ‘[’ starts a character class, which can contain a list of characters, ranges and complementations. See B<glob>(7) for detailed information about globbing. -B<Note:> The current implementation might re-include more directories +B<Note>: The current implementation might re-include more directories and symlinks than needed, in particular when there is a more specific re-inclusion, to be on the safe side and avoid possible unpack failures; future work might fix this. @@ -1029,7 +1029,7 @@ pathname will be excluded (which could be automatically reincluded if the code sees the need). Any subsequent files contained within that directory will fail to unpack. -Hint: make sure the globs are not expanded by your shell. +B<Hint>: make sure the globs are not expanded by your shell. =item B<--verify-format> I<format-name> diff --git a/man/dsc.pod b/man/dsc.pod index 30652f4af..03c417565 100644 --- a/man/dsc.pod +++ b/man/dsc.pod @@ -184,7 +184,7 @@ restrictions removed, and OR dependencies flattened (that is, converted to separate AND relationships), except for binaries generated by this source package and its meta-dependency equivalent B<@>. -Rationale: this field is needed because otherwise to be able to get the +B<Rationale>: this field is needed because otherwise to be able to get the test dependencies, each source package would need to be unpacked. =item B<Build-Depends:> I<package-list> diff --git a/man/start-stop-daemon.pod b/man/start-stop-daemon.pod index 5574ceb8b..94085bb27 100644 --- a/man/start-stop-daemon.pod +++ b/man/start-stop-daemon.pod @@ -38,7 +38,7 @@ is used to control the creation and termination of system-level processes. Using one of the matching options, B<start-stop-daemon> can be configured to find existing instances of a running process. -B<Note:> Unless +B<Note>: Unless B<--pid> or B<--pidfile> @@ -136,11 +136,11 @@ The I<ppid> must be a number greater than 0. Check whether a process has created the file I<pidfile>. -B<Note:> Using this matching option alone might cause unintended processes to +B<Note>: Using this matching option alone might cause unintended processes to be acted on, if the old process terminated without being able to remove the I<pidfile>. -B<Warning:> Using this match option with a world-writable pidfile or using +B<Warning>: 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 @@ -154,7 +154,7 @@ Using I</dev/null> is exempt from these checks. Check for processes that are instances of this I<executable>. The I<executable> argument should be an absolute pathname. -B<Note:> This might +B<Note>: 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. @@ -165,7 +165,7 @@ Check for processes with the name I<process-name>. The I<process-name> is usually the process filename, but it could have been changed by the process itself. -B<Note:> On most systems this information is retrieved from +B<Note>: 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). @@ -174,7 +174,7 @@ short length limit (assuming more than 15 characters is non-portable). Check for processes owned by the user specified by I<username> or I<uid>. -B<Note:> Using this matching option alone will cause all processes +B<Note>: Using this matching option alone will cause all processes matching the user to be acted on. =back @@ -305,7 +305,7 @@ will force B<start-stop-daemon> to fork before starting the process, and force it into the background. -B<Warning: start-stop-daemon> +B<Warning>: B<start-stop-daemon> cannot check the exit status if the process fails to execute for B<any> reason. This is a last resort, and is only meant for programs that either @@ -401,7 +401,7 @@ and place the pid into it just before executing the process. Note, the file will only be removed when stopping the program if B<--remove-pidfile> is used. -B<Note:> +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 only useful when combined with the diff --git a/man/update-alternatives.pod b/man/update-alternatives.pod index 9dee3d67d..6e9c23992 100644 --- a/man/update-alternatives.pod +++ b/man/update-alternatives.pod @@ -90,7 +90,7 @@ B<postinst> (configure) to install the alternative and from B<prerm> and B<postrm> (remove) to remove the alternative. -B<Note:> in most (if not all) cases no other maintainer script actions should +B<Note>: in most (if not all) cases no other maintainer script actions should call B<update-alternatives>, in particular neither of B<upgrade> nor B<disappear>, as any other such action can lose the manual state of an alternative, or make the alternative temporarily flip-flop, or completely -- Dpkg.Org's dpkg
