Package: ucf
Version: 3.0048
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with a new version
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z < "man
page"
[Use "groff -e ' $' <file>" to find obvious trailing spaces.]
["test-groff" is a script in the repository for "groff"; is not shipped]
(local copy and "troff" slightly changed by me).
[The fate of "test-nroff" was decided in groff bug #55941.]
* What was the outcome of this action?
troff:<stdin>:6: warning: trailing space in the line
troff:<stdin>:11: warning: trailing space in the line
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.12.9-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1),
LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
Versions of packages ucf depends on:
ii debconf [debconf-2.0] 1.5.89
ii libtext-wrapi18n-perl 0.06-10
ii procps 2:4.0.4-6
ii sensible-utils 0.0.24
ucf recommends no packages.
ucf suggests no packages.
-- debconf information excluded
Input file is ucf.1
Output from "mandoc -T lint ucf.1": (shortened list)
-.-.
Output from "test-groff -mandoc -t -ww -z ucf.1": (shortened list)
2 trailing space in the line
-.-.
Change two HYPHEN-MINUSES (code 0x2D) to an em-dash (\(em),
if one is intended.
" \(em " creates a too big gap in the text (in "troff").
An en-dash is usually surrounded by a space,
while an em-dash is used without spaces.
"man" (1 byte characters in input) transforms an en-dash (\(en) to one
HYPHEN-MINUS,
and an em-dash to two HYPHEN-MINUSES without considering the space
around it.
If "--" are two single "-"
(begin of an option or end of options)
then use "\-\-".
ucf.1:160:always been ok to use ucf when debconf is not running -- it shall
-.-.
Wrong distance between sentences in the input file.
Separate the sentences and subordinate clauses; each begins on a new
line. See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").
The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.
Remember coding: Only one command ("sentence") on each (logical) line.
E-mail: Easier to quote exactly the relevant lines.
Generally: Easier to edit the sentence.
Patches: Less unaffected text.
Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
Mark a final abbreviation point as such by suffixing it with "\&".
18:interaction time. It uses debconf to interact with the user, as per Debian
29:follows and resolves symbolic links before acting. As far as
48:scripts as well. Using
67:time. Indeed, the transitioning facility is better than the one
74:status. The second form in the SYNOPSIS above is for purging
81:question. For example, a file with the suffix
97:Dry run. Print the actions that would be taken if the script is
103:(n defaults to 1). Please note there must be no spaces before the
104:optional digit n. This turns on copious debugging information.
107:Removes all vestiges of the file from the state hashfile. This is
128:files and sub directories of this directory) to foo. By default, the
130:directory. Setting this option overrides settings in the environment
148:configuration file. If the user likes what they see, they can ask to
149:have these changes merged in. This allows one to get new upstream
151:configuration file. This is accomplished by taking the configuration
193:package it belongs to. This is done with a simple call to
203:may be asked at installation time. Specifically, questions should not
256:the file (on user request, of course). There is also a preview
270:recreate the locally deleted file). Additionally, when ucf creates an
279:variable are also supported. See dpkg(1) for further information.
320:file. Do this if you want to change your decision to not update to a
-.-.
Split a punctuation from a single argument, if a two-font macro is meant.
49:.B ucf,
55:.I /etc,
84:.B ucf.
132:.B UCF_SOURCE_DIR,
134:.B conf_source_dir.
140:.B UCF_OLD_MDSUM_FILE,
142:.B conf_old_mdsum_file.
176:.I /var/lib/ucf.
194:.B ucfr.
197:.B ucfq.
221:.I 7.6.3,
223:.I potato.
261:.B UCF_FORCE_CONFFNEW,
264:.B UCF_FORCE_CONFFOLD,
282:.I new_file.md5sum,
286:.I <Destination>.
288:.I /var/lib/ucf/hashfile,
290:.I /var/lib/ucf/hashfile.X,
301:.I foo.conf,
303:.I /usr/share/foo/configuration,
346:.I emacsen\-common.
-.-.
Name of a manual is set in bold, the section in roman.
See man-pages(7).
279:variable are also supported. See dpkg(1) for further information.
-.-.
No space is needed before a quote (") at the end of a line
6:.RI [ options "] "
11:.RI [ options "] "
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
troff:<stdin>:6: warning: trailing space in the line
troff:<stdin>:11: warning: trailing space in the line
-.-.
Spelling (from codespell):
cofiguration ==> configuration
--- ucf.1 2025-01-22 03:28:51.994648126 +0000
+++ ucf.1.new 2025-01-23 20:34:29.493892683 +0000
@@ -3,19 +3,20 @@
ucf \- Update Configuration File: preserve user changes in configuration files
.SH SYNOPSIS
.B ucf
-.RI [ options "] "
+.RI [ options ]
.I <New File>
.I <Destination>
.PP
.B ucf
-.RI [ options "] "
+.RI [ options ]
.I \-\-purge
.I <Destination>
.SH DESCRIPTION
This utility provides a means of asking the user whether or not to
accept new versions of configuration files provided by the package
maintainer, with various heuristics designed to minimize
-interaction time. It uses debconf to interact with the user, as per Debian
+interaction time.
+It uses debconf to interact with the user, as per Debian
policy. In the SYNOPSIS above,
.I New file
is the configuration file as provided by the package (either shipped
@@ -26,7 +27,8 @@ is the location (usually under /etc) whe
lives, and is potentially modified by the end user. Since the files
edited would be real files, and not symbolic links,
.B ucf
-follows and resolves symbolic links before acting. As far as
+follows and resolves symbolic links before acting.
+As far as
possible, ucf attempts to preserve the ownership and permission of
the
.I New file
@@ -45,43 +47,47 @@ policy states that files under
which are configuration files
.B must
preserve user changes, and this applies to files handled by maintainer
-scripts as well. Using
-.B ucf,
+scripts as well.
+Using
+.BR ucf ,
one may ship a bunch of default configuration files somewhere in
.I /usr
(
.I /usr/share/<pkg>
is a good location), and maintain files in
-.I /etc,
+.IR /etc ,
preserving user changes and in general offering the same facilities
while upgrading that
.B dpkg
normally provides for
-.I \*(lqconffiles\*(rq
+.IR \*(lqconffiles\*(rq .
.PP
Additionally, this script provides facilities for transitioning a file
that had not been provided
.I conffile
like protection to come under this
schema, and attempts to minimize questions asked at install
-time. Indeed, the transitioning facility is better than the one
+time.
+Indeed, the transitioning facility is better than the one
offered by
.B dpkg
while transitioning a file from a
.I non\-conffile
to
.I conffile
-status. The second form in the SYNOPSIS above is for purging
+status.
+The second form in the SYNOPSIS above is for purging
information about the configuration file when the package is purged;
and is critical for allowing smooth reinstallations.
.PP
During the course of operations, when working with configuration files,
.B ucf
optionally creates copies of versions of the configuration file in
-question. For example, a file with the suffix
+question.
+For example, a file with the suffix
.I "ucf-old"
holds the old version of a configuration file replaced by
-.B ucf.
+.BR ucf .
Also, copies of the configuration file with the suffixes
.I "ucf-new"
and
@@ -94,17 +100,21 @@ copies of the configuration file with th
Print a short usage message
.TP
.B "\-n, \-\-no\-action"
-Dry run. Print the actions that would be taken if the script is
+Dry run.
+Print the actions that would be taken if the script is
invoked, but take no action.
.TP
.B "\-d[n], \-\-debug=[n]"
Set the debug level to the (optional) level
.I n
-(n defaults to 1). Please note there must be no spaces before the
-optional digit n. This turns on copious debugging information.
+(n defaults to 1).
+Please note there must be no spaces before the
+optional digit n.
+This turns on copious debugging information.
.TP
.B "\-p, \-\-purge"
-Removes all vestiges of the file from the state hashfile. This is
+Removes all vestiges of the file from the state hashfile.
+This is
required to allow a package to be reinstalled after it is purged;
since otherwise, the real configuration file is removed, but it
remains in the hash file; and on reinstall no action is taken, since
@@ -125,30 +135,35 @@ configuration files.
.TP
.B "\-s foo, \-\-src\-dir foo"
Set the source directory (historical md5sums are expected to live in
-files and sub directories of this directory) to foo. By default, the
+files and sub directories of this directory) to foo.
+By default, the
directory the new_file lives in is assumed to be the source
-directory. Setting this option overrides settings in the environment
+directory.
+Setting this option overrides settings in the environment
variable
-.B UCF_SOURCE_DIR,
+.BR UCF_SOURCE_DIR ,
and in the configuration file variable
-.B conf_source_dir.
+.BR conf_source_dir .
.TP
.B "\-\-sum\-file foo"
Force the historical md5sums to be read from this file, rather than
defaulting to living in the source directory. Setting this option
overrides settings in the environment variable
-.B UCF_OLD_MDSUM_FILE,
+.BR UCF_OLD_MDSUM_FILE ,
and in the configuration file variable
-.B conf_old_mdsum_file.
+.BR conf_old_mdsum_file .
.TP
.B "\-\-three\-way"
This turns on the option, during installation, for the user to be
offered a chance to see a merge of the changes between old maintainer
version and the new maintainer version into the local copy of the
-configuration file. If the user likes what they see, they can ask to
-have these changes merged in. This allows one to get new upstream
+configuration file.
+If the user likes what they see, they can ask to
+have these changes merged in.
+This allows one to get new upstream
changes merged in even while retaining local modifications to the
-configuration file. This is accomplished by taking the configuration
+configuration file.
+This is accomplished by taking the configuration
file and stashing it in a cache area during registration, and using
diff3 during the install (the stashed file name is a munged version of
the full path of the configuration file to avoid name space clashes).
@@ -157,7 +172,7 @@ the full path of the configuration file
Indicate that it is ok for
.I ucf
to use an already running debconf instance for prompting (it has
-always been ok to use ucf when debconf is not running -- it shall
+always been ok to use ucf when debconf is not running \(en it shall
invoke debconf as needed).
.TP
.B "\-\-debconf\-template foo"
@@ -173,7 +188,7 @@ option is also set.
.TP
.B "\-\-state\-dir /path/to/dir"
Set the state directory to /path/to/dir instead of the default
-.I /var/lib/ucf.
+.IR /var/lib/ucf .
Used mostly for testing.
.TP
.B "\-Z"
@@ -190,37 +205,39 @@ still on the system).
It is recommended that you also register any file being managed by
.B ucf
with the ucf registry; this associates the configuration file with the
-package it belongs to. This is done with a simple call to
-.B ucfr.
+package it belongs to.
+This is done with a simple call to
+.BR ucfr .
Users may then query the association between a configuration file and
the package using the tool
-.B ucfq.
+.BR ucfq .
Please see the appropriate manual pages for details.
.PP
If a file maintained by maintainer scripts is being transitioned from an
unprotected status to the protection afforded by the script, the
maintainer can help ease the transition by reducing the questions that
-may be asked at installation time. Specifically, questions should not
+may be asked at installation time.
+Specifically, questions should not
be asked if the file in question is an unmodified version that was one
shipped in a previous version of this package; and the maintainer can
help by telling the script about the historical md5sums that published
versions of this file contained.
.PP
The way to do this is to either create a file called
-.B <New file>.md5sum,
+.BR "<New file>.md5sum" ,
with one md5sum on each line, (the file names you use are ignored, except
for the entry named default), or create a directory, called
-.B <New file>.md5sum.d,
+.BR "<New file>.md5sum.d" ,
which should contain any number of files, each containing a single
line, namely, the md5sum of a previous version of
-.B <New file>.
+.BR "<New file>" .
The names of these files are not important, with one exception: The
file called default is treated specially. For example, the author
personally uses either package version numbers or release code names,
like
-.I 7.6.3,
+.IR 7.6.3 ,
or
-.I potato.
+.IR potato .
If none of the historical md5sums match, we are almost certain that
either the historical record of md5sums is not complete, or the user
has changed the configuration file.
@@ -231,7 +248,7 @@ md5sums match, and if the file
exists, or if there is a line corresponding to a
.I default
file in
-.B <New file>.md5sum,
+.BR "<New file>.md5sum" ,
it shall be used as the default md5sum of the
.I previous
version of the package assumed to have been installed on this machine.
@@ -240,34 +257,36 @@ packages (like just one), the maintainer
guess, but the option is provided to the maintainer.
.PP
If the file
-.B <New file>.md5sum,
+.BR "<New file>.md5sum" ,
or the directory
.B <New file>.md5sum.d
does not exist, or none of the md5sums match, we test the installed
.I <Destination>
file to see whether it is the same as the
-.I <New file>.
+.IR "<New file>" .
If not, we ask the user whether they want us to replace the file.
.PP
An additional facility is also offered: optionally, ucf can store one
old version of the maintainers copy of the configuration file, and,
on upgrade, calculate the changes made in the maintainers version of
the configuration file, and apply that patch to the local version of
-the file (on user request, of course). There is also a preview
+the file (on user request, of course).
+There is also a preview
facility where the user can inspect the results of such a merge,
before asking the action to be taken.
.SH "ENVIRONMENT VARIABLES"
The variable
-.B UCF_FORCE_CONFFNEW,
+.BR UCF_FORCE_CONFFNEW ,
if set, forces the new file to always overwrite the installed
destination file, while the variable
-.B UCF_FORCE_CONFFOLD,
+.BR UCF_FORCE_CONFFOLD ,
if set silently retains the installed file.
.B UCF_FORCE_CONFFMISS
is only applicable when the installed destination file does not exist
(perhaps due to user removal),and forces ucf to recreate the missing
file (the default behaviour is to honor the users wishes and not
-recreate the locally deleted file). Additionally, when ucf creates an
+recreate the locally deleted file).
+Additionally, when ucf creates an
inferior shell, it populates the variables
.B UCF_CONFFILE_NEW
and
@@ -276,18 +295,21 @@ which are useful for inspecting the chan
.PP
The confmiss, confnew, confold, confdef and confask flags of the
.B DPKG_FORCE
-variable are also supported. See dpkg(1) for further information.
+variable are also supported.
+See
+.BR dpkg (1)
+for further information.
.SH FILES
This script creates the file
-.I new_file.md5sum,
+.IR new_file.md5sum ,
and it may copy the file (presumably shipped with the package)
.I <New file>
to its destination,
-.I <Destination>.
+.IR <Destination> .
.PP
-.I /var/lib/ucf/hashfile,
+.IR /var/lib/ucf/hashfile ,
and
-.I /var/lib/ucf/hashfile.X,
+.IR /var/lib/ucf/hashfile.X ,
where
.I X
is a small integer, where previous versions of the hashfile are
@@ -298,9 +320,9 @@ stored.
If the package
.I foo
wants to use ucf to handle user interaction for configuration file
-.I foo.conf,
+.IR foo.conf ,
a version of which is provided in the package as
-.I /usr/share/foo/configuration,
+.IR /usr/share/foo/configuration ,
a simple invocation of ucf in the post inst file is all that is
needed:
.PP
@@ -316,8 +338,9 @@ examples in /usr/share/doc/ucf/examples)
.I /etc/foo.conf
Please note that purge can also be used to make ucf forget the
previous state of the files, and when the package is next installed or
-updated, ucf will ask the user to replace the current cofiguration
-file. Do this if you want to change your decision to not update to a
+updated, ucf will ask the user to replace the current configuration
+file.
+Do this if you want to change your decision to not update to a
maintainer provided version of the configuration file.
.PP
The motivation for this script was to provide conffile like handling
@@ -326,7 +349,7 @@ for start files for emacs lisp packages
) These start files are not
shipped with the package, instead, they are installed during the
post installation configuration phase by the script
-.I /usr/lib/emacsen\-common/emacs\-package\-install $package_name.
+.IR "/usr/lib/emacsen\-common/emacs\-package\-install $package_name" .
.PP
This script is meant to be invoked by the packages install script at
.I /usr/lib/emacsen\-common/packages/install/$package_name
@@ -339,11 +362,11 @@ new file (
.I /etc/emacs21/site\-start.d/50<pkg\-init.el
), and it should do the rest.
.SH "SEE ALSO"
-ucf.conf(5), ucfr(1), ucfq(1), dpkg(1) and diff3(1).
+.BR ucf.conf (5),\ ucfr (1),\ ucfq (1),\ dpkg "(1) and " diff3 (1).
The
.B Debian
Emacs policy, shipped with the package
-.I emacsen\-common.
+.IR emacsen\-common .
.SH AUTHOR
This manual page was written Manoj Srivastava <sriva...@debian.org>,
for the Debian GNU/Linux system.
Any program (person), that produces man pages, should check the output
for defects by using (both groff and nroff)
[gn]roff -mandoc -t -ww -b -z -K utf8 <man page>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
Any "autogenerator" should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
It should also check its input files for too long (> 80) lines.
This is just a simple quality control measure.
The "autogenerator" may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
Not beginning each input sentence on a new line.
Line length should thus be reduced.
The script "reportbug" uses 'quoted-printable' encoding when a line is
longer than 1024 characters in an 'ascii' file.
See man-pages(7), item "semantic newline".
-.-
The difference between the formatted output of the original and patched file
can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -u <out1> <out2>
and for groff, using
\"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - \"
instead of 'nroff -mandoc'
Add the option '-t', if the file contains a table.
Read the output from 'diff -u ...' with 'less -R' or similar.
-.-.
If 'man' (man-db) is used to check the manual for warnings,
the following must be set:
The option \"-warnings=w\"
The environmental variable:
export MAN_KEEP_STDERR=yes (or any non-empty value)
or
(produce only warnings):
export MANROFFOPT=\"-ww -b -z\"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-
