[Pkg-shadow-devel] Bug#1087450: newusers.8: Some remarks about this man page
Bjarni Ingi Gislason
bjarniig at simnet.is
Wed Nov 13 18:34:45 GMT 2024
Package: passwd
Version: 1:4.16.0-4
Severity: minor
* What led up to the situation?
Checking for defects with
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z < "man page"
[Use "groff -e ' $' <file>" to find 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: backtrace: file '<stdin>':103
troff:<stdin>:103: 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.11.5-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 passwd depends on:
ii base-passwd 3.6.5
ii libacl1 2.3.2-2+b1
ii libattr1 1:2.5.2-2
ii libaudit1 1:4.0.1-3
ii libbsd0 0.12.2-2
ii libc6 2.40-3
ii libcrypt1 1:4.4.36-5
ii libpam-modules 1.5.3-7+b1
ii libpam0g 1.5.3-7+b1
ii libselinux1 3.7-3
ii libsemanage2 3.7-2
ii login.defs 1:4.16.0-4
Versions of packages passwd recommends:
ii sensible-utils 0.0.24
passwd suggests no packages.
-- no debconf information
-------------- next part --------------
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
-.-
So any 'generator' should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
This is just a simple quality control measure.
The 'generator' may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Input text line longer than 80 bytes.
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.
Lines should thus be shorter.
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 of '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)
-.-.
Output from "mandoc -T lint newusers.8": (possibly shortened list)
mandoc: newusers.8:36:2: WARNING: skipping paragraph macro: PP after SH
mandoc: newusers.8:41:187: STYLE: input text line longer than 80 bytes: (or the standard inp...
mandoc: newusers.8:50:93: STYLE: input text line longer than 80 bytes: It can be the name o...
mandoc: newusers.8:56:83: STYLE: input text line longer than 80 bytes: This field will be e...
mandoc: newusers.8:68:92: STYLE: input text line longer than 80 bytes: If this field contai...
mandoc: newusers.8:71:113: STYLE: input text line longer than 80 bytes: If the UID of an exi...
mandoc: newusers.8:78:82: STYLE: input text line longer than 80 bytes: If this field contai...
mandoc: newusers.8:81:195: STYLE: input text line longer than 80 bytes: If this field is a n...
mandoc: newusers.8:83:120: STYLE: input text line longer than 80 bytes: If this field is emp...
mandoc: newusers.8:85:83: STYLE: input text line longer than 80 bytes: to be used as the pr...
mandoc: newusers.8:87:94: STYLE: input text line longer than 80 bytes: If this field contai...
mandoc: newusers.8:102:180: STYLE: input text line longer than 80 bytes: If this field does n...
mandoc: newusers.8:104:392: STYLE: input text line longer than 80 bytes: of the new user\*(Aq...
mandoc: newusers.8:108:109: STYLE: input text line longer than 80 bytes: does not move or cop...
mandoc: newusers.8:113:84: STYLE: input text line longer than 80 bytes: This field defines t...
mandoc: newusers.8:117:230: STYLE: input text line longer than 80 bytes: first tries to creat...
mandoc: newusers.8:119:286: STYLE: input text line longer than 80 bytes: During this first pa...
mandoc: newusers.8:121:117: STYLE: input text line longer than 80 bytes: This command is inte...
mandoc: newusers.8:123:2: WARNING: skipping paragraph macro: PP after SH
mandoc: newusers.8:162:2: WARNING: skipping paragraph macro: PP after SH
mandoc: newusers.8:165:2: WARNING: skipping paragraph macro: PP after SH
mandoc: newusers.8:197:102: STYLE: input text line longer than 80 bytes: Maximum members per ...
mandoc: newusers.8:201:95: STYLE: input text line longer than 80 bytes: The default value is...
mandoc: newusers.8:203:177: STYLE: input text line longer than 80 bytes: This feature (split ...
mandoc: newusers.8:207:148: STYLE: input text line longer than 80 bytes: Note: split groups m...
mandoc: newusers.8:212:198: STYLE: input text line longer than 80 bytes: The maximum number o...
mandoc: newusers.8:217:202: STYLE: input text line longer than 80 bytes: The minimum number o...
mandoc: newusers.8:222:217: STYLE: input text line longer than 80 bytes: The number of days w...
mandoc: newusers.8:314:116: STYLE: input text line longer than 80 bytes: The file mode creati...
mandoc: newusers.8:328:2: WARNING: skipping paragraph macro: PP after SH
mandoc: newusers.8:370:2: WARNING: skipping paragraph macro: PP after SH
-.-.
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.
41:(or the standard input by default) and uses this information to update a set of existing users or to create new users\&. Each line is in the same format as the standard password file (see
51:\fBnewusers\fR)\&. In case of an existing user, the user\*(Aqs information will be changed, otherwise a new user will be created\&.
81:If this field is a number, this number will be used as the primary group ID of the user\&. If no groups exist with this GID, a new group will be created with this GID, and the name of the user\&.
102:If this field does not specify an existing directory, the specified directory is created, with ownership set to the user being created or updated and its primary group\&. Note that
104:of the new user\*(Aqs home directory\&. The newusers command will fail to create the home directory if the parent directories do not exist, and will send a message to stderr informing the user of the failure\&. The newusers command will not halt or return a failure to the calling shell if it fails to create the home directory, it will continue to process the batch of new users specified\&.
108:does not move or copy the content of the old directory to the new location\&. This should be done manually\&.
113:This field defines the shell of the user\&. No checks are performed on this field\&.
117:first tries to create or change all the specified users, and then write these changes to the user or group databases\&. If an error occurs (except in the final writes to the databases), no changes are committed to the databases\&.
119:During this first pass, users are created with a locked password (and passwords are not changed for the users which are not created)\&. A second pass is used to update the passwords using PAM\&. Failures to update a password are reported, but will not stop the other password updates\&.
159:directory\&. Only absolute paths are supported\&.
180:\fBGID_MAX\fR) is 1000 (resp\&. 60000)\&.
185:The mode for new home directories\&. If not specified, the
197:Maximum members per group entry\&. When the maximum is reached, a new group entry (line) is started in
203:This feature (split group) permits to limit the length of lines in the group file\&. This is useful to make sure that lines for NIS groups are not larger than 1024 characters\&.
207:Note: split groups may not be supported by all tools (even in the Shadow toolsuite)\&. You should not use this variable unless you really need it\&.
212:The maximum number of days a password may be used\&. If the password is older than this, a password change will be forced\&. If not specified, \-1 will be assumed (which disables the restriction)\&.
217:The minimum number of days allowed between password changes\&. Any password changes attempted sooner than this will be rejected\&. If not specified, 0 will be assumed (which disables the restriction)\&.
222:The number of days warning given before a password expires\&. A zero means warning is given only upon the day of expiration, a value of \-1 means no warning is given\&. If not specified, no warning will be provided\&.
309:\fBUID_MAX\fR) is 1000 (resp\&. 60000)\&.
314:The file mode creation mask is initialized to this value\&. If not specified, the mask will be initialized to 022\&.
-.-.
Test nr. 30:
Split lines longer than 80 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
Line 10, length 87
.TH "NEWUSERS" "8" "08/05/2024" "shadow\-utils 4\&.16\&.0" "System Management Commands"
Line 41, length 187
(or the standard input by default) and uses this information to update a set of existing users or to create new users\&. Each line is in the same format as the standard password file (see
Line 50, length 93
It can be the name of a new user or the name of an existing user (or a user created before by
Line 51, length 131
\fBnewusers\fR)\&. In case of an existing user, the user\*(Aqs information will be changed, otherwise a new user will be created\&.
Line 56, length 83
This field will be encrypted and used as the new value of the encrypted password\&.
Line 68, length 92
If this field contains the name of an existing user (or the name of a user created before by
Line 71, length 113
If the UID of an existing user is changed, the files ownership of the user\*(Aqs file should be fixed manually\&.
Line 78, length 82
If this field contains the name of an existing group (or a group created before by
Line 79, length 91
\fBnewusers\fR), the GID of this group will be used as the primary group ID for the user\&.
Line 81, length 195
If this field is a number, this number will be used as the primary group ID of the user\&. If no groups exist with this GID, a new group will be created with this GID, and the name of the user\&.
Line 83, length 120
If this field is empty, a new group will be created with the name of the user and a GID will be automatically defined by
Line 85, length 83
to be used as the primary group ID for the user and as the GID for the new group\&.
Line 87, length 94
If this field contains the name of a group which does not exist (and was not created before by
Line 88, length 111
\fBnewusers\fR), a new group will be created with the specified name and a GID will be automatically defined by
Line 102, length 180
If this field does not specify an existing directory, the specified directory is created, with ownership set to the user being created or updated and its primary group\&. Note that
Line 104, length 392
of the new user\*(Aqs home directory\&. The newusers command will fail to create the home directory if the parent directories do not exist, and will send a message to stderr informing the user of the failure\&. The newusers command will not halt or return a failure to the calling shell if it fails to create the home directory, it will continue to process the batch of new users specified\&.
Line 108, length 109
does not move or copy the content of the old directory to the new location\&. This should be done manually\&.
Line 113, length 84
This field defines the shell of the user\&. No checks are performed on this field\&.
Line 117, length 230
first tries to create or change all the specified users, and then write these changes to the user or group databases\&. If an error occurs (except in the final writes to the databases), no changes are committed to the databases\&.
Line 119, length 286
During this first pass, users are created with a locked password (and passwords are not changed for the users which are not created)\&. A second pass is used to update the passwords using PAM\&. Failures to update a password are reported, but will not stop the other password updates\&.
Line 121, length 117
This command is intended to be used in a large system environment where many accounts are updated at a single time\&.
Line 197, length 102
Maximum members per group entry\&. When the maximum is reached, a new group entry (line) is started in
Line 201, length 95
The default value is 0, meaning that there are no limits in the number of members in a group\&.
Line 203, length 177
This feature (split group) permits to limit the length of lines in the group file\&. This is useful to make sure that lines for NIS groups are not larger than 1024 characters\&.
Line 207, length 148
Note: split groups may not be supported by all tools (even in the Shadow toolsuite)\&. You should not use this variable unless you really need it\&.
Line 212, length 198
The maximum number of days a password may be used\&. If the password is older than this, a password change will be forced\&. If not specified, \-1 will be assumed (which disables the restriction)\&.
Line 217, length 202
The minimum number of days allowed between password changes\&. Any password changes attempted sooner than this will be rejected\&. If not specified, 0 will be assumed (which disables the restriction)\&.
Line 222, length 217
The number of days warning given before a password expires\&. A zero means warning is given only upon the day of expiration, a value of \-1 means no warning is given\&. If not specified, no warning will be provided\&.
Line 225, length 84
\fBSUB_GID_MIN\fR (number), \fBSUB_GID_MAX\fR (number), \fBSUB_GID_COUNT\fR (number)
Line 248, length 84
\fBSUB_UID_MIN\fR (number), \fBSUB_UID_MAX\fR (number), \fBSUB_UID_COUNT\fR (number)
Line 314, length 116
The file mode creation mask is initialized to this value\&. If not specified, the mask will be initialized to 022\&.
-.-.
Show if docman-to-man created this
4:.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
-.-.
Test nr. 64:
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
newusers.8:117:first tries to create or change all the specified users, and then write these changes to the user or group databases\&. If an error occurs (except in the final writes to the databases), no changes are committed to the databases\&.
newusers.8:119:During this first pass, users are created with a locked password (and passwords are not changed for the users which are not created)\&. A second pass is used to update the passwords using PAM\&. Failures to update a password are reported, but will not stop the other password updates\&.
newusers.8:180:\fBGID_MAX\fR) is 1000 (resp\&. 60000)\&.
newusers.8:207:Note: split groups may not be supported by all tools (even in the Shadow toolsuite)\&. You should not use this variable unless you really need it\&.
newusers.8:212:The maximum number of days a password may be used\&. If the password is older than this, a password change will be forced\&. If not specified, \-1 will be assumed (which disables the restriction)\&.
newusers.8:217:The minimum number of days allowed between password changes\&. Any password changes attempted sooner than this will be rejected\&. If not specified, 0 will be assumed (which disables the restriction)\&.
newusers.8:309:\fBUID_MAX\fR) is 1000 (resp\&. 60000)\&.
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
troff: backtrace: file '<stdin>':103
troff:<stdin>:103: warning: trailing space in the line
-.-.
There is no need to add a '\&' before a full stop (.) if it has a character
in fron of it!
-.-
More information about the Pkg-shadow-devel
mailing list