Bug#1052265: ldap.conf.5: some remarks and editorial changes for this man page
Bjarni Ingi Gislason
bjarniig at simnet.is
Tue Sep 19 19:13:42 BST 2023
Package: libldap-common
Version: 2.5.13+dfsg-5
Severity: minor
Tags: patch
Dear Maintainer,
here are some notes and editorial fixes for the manual.
The patch is in the attachment.
-.-
The difference between the formatted outputs can be seen with:
nroff -man -t <file1> > <out1>
nroff -man -t <file2> > <out2>
diff -u <out1> <out2>
and for groff, using
"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -man -Z -t - "
instead of "nroff -man"
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 -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-.
Output from "mandoc -T lint ldap.conf.5":
mandoc: ldap.conf.5:1:2: ERROR: skipping insecure request: lf
mandoc: ldap.conf.5:30:2: WARNING: skipping paragraph macro: PP empty
mandoc: ldap.conf.5:69:61: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:71:58: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:72:58: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:75:61: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:104:9: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:107:10: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:118:9: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:121:65: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:122:65: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:125:1: WARNING: tab in filled text
mandoc: ldap.conf.5:129:1: WARNING: tab in filled text
mandoc: ldap.conf.5:162:2: WARNING: line scope broken: TP breaks TP
mandoc: ldap.conf.5:166:9: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:214:75: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:255:46: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:283:20: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:291:20: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:299:24: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:305:87: STYLE: input text line longer than 80 bytes: Do not perform rever...
mandoc: ldap.conf.5:308:88: STYLE: input text line longer than 80 bytes: The channel-binding ...
mandoc: ldap.conf.5:310:94: STYLE: input text line longer than 80 bytes: If OpenLDAP is built...
mandoc: ldap.conf.5:363:57: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:382:67: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:384:28: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:411:83: STYLE: input text line longer than 80 bytes: This parameter is ig...
mandoc: ldap.conf.5:417:83: STYLE: input text line longer than 80 bytes: This parameter is ig...
mandoc: ldap.conf.5:475:71: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:479:104: STYLE: input text line longer than 80 bytes: parameter to be set....
mandoc: ldap.conf.5:530:2: ERROR: skipping insecure request: lf
mandoc: ldap.conf.5:535:62: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:536:2: ERROR: skipping insecure request: lf
-.-.
Input file is ldap.conf.5.
Remove space characters at the end of lines.
69:conventionally written in uppercase, although not required),
71:The value starts with the first non-blank character after
72:the option's name, and terminates at the end of the line,
75:for that option, if any. Quoting values that contain blanks
104:.I LDAP
107:.B ldaps
118:.B name
121:is required, nor allowed; note that directory separators must be
122:URL-encoded, like any other characters that are special to URLs;
166:.I LDAP
214:may still apply any server-side limit on the amount of entries that can be
255:Specifies Cyrus SASL security properties. The
283:.B minssf=<factor>
291:.B maxssf=<factor>
299:.B maxbufsize=<factor>
363:<cipher-suite-spec> should be a cipher specification for
382:With GnuTLS the available specs can be found in the manual page of
384:(see the description of the
475:Specifies if the Certificate Revocation List (CRL) of the CA should be
535:is derived from the University of Michigan LDAP 3.3 Release.
-.-.
Use "\e" to print the escape character instead of "\\" (which gets
interpreted in copy mode).
89: BASE ou=IT staff,o=Example\\2C Inc,c=US
-.-.
Wrong distance between sentences.
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.
N.B
The number of lines affected is too large to be in the patch.
143:Specifies how alias dereferencing is done when performing a search. The
149:Aliases are never dereferenced. This is the default.
177:before TCP starts sending keepalive probes. Linux only.
181:before dropping the connection. Linux only.
219:Multiple IP addresses must be space separated. Only one valid IPv4
255:Specifies Cyrus SASL security properties. The
305:Do not perform reverse DNS lookups to canonicalize SASL host names. The default is off.
308:The channel-binding type to use, see also LDAP_OPT_X_SASL_CBINDING. The default is none.
319:should be used. The default is off.
324:attribute of the targets RootDSE entry. The default is off.
338:certificates in separate individual files. The
357:file. Currently, the private key must not be protected with a password, so
411:This parameter is ignored with GnuTLS. On Debian openldap is linked against GnuTLS.
415:not available. Generally set to the name of the EGD/PRNGD socket.
417:This parameter is ignored with GnuTLS. On Debian openldap is linked against GnuTLS.
430:The server certificate is requested. If a bad certificate is provided, it will
434:The server certificate is requested. If a bad certificate is provided,
446:name against the specified hostname of the server. The
455:The SAN is checked against the specified hostname. If a SAN is
461:The SAN is checked against the specified hostname. If no SAN is present
463:is used. If a SAN is present but doesn't match the specified hostname,
464:the session is immediately terminated. This setting may be preferred
468:These keywords are equivalent. The SAN is checked against the specified
469:hostname. If no SAN is present in the server certificate, or no SANs
470:match, the session is immediately terminated. This setting should be
476:used to verify if the server certificates have not been revoked. This
479:parameter to be set. This parameter is ignored with GnuTLS. On Debian openldap is linked against GnuTLS.
496:to verify if the server certificates have not been revoked. This
-.-.
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.
ldap.conf.5: line 305 length 87
Do not perform reverse DNS lookups to canonicalize SASL host names. The default is off.
ldap.conf.5: line 308 length 88
The channel-binding type to use, see also LDAP_OPT_X_SASL_CBINDING. The default is none.
ldap.conf.5: line 310 length 94
If OpenLDAP is built with Generic Security Services Application Programming Interface support,
ldap.conf.5: line 389 length 83
\-\-priority, you can obtain the \(em more limited \(em list of ciphers by calling:
ldap.conf.5: line 411 length 83
This parameter is ignored with GnuTLS. On Debian openldap is linked against GnuTLS.
ldap.conf.5: line 417 length 83
This parameter is ignored with GnuTLS. On Debian openldap is linked against GnuTLS.
ldap.conf.5: line 479 length 104
parameter to be set. This parameter is ignored with GnuTLS. On Debian openldap is linked against GnuTLS.
-.-.
Use \(en for a dash (en-dash) between space characters, not a minus
(\-) or a hyphen (-), except in the NAME section.
ldap.conf.5:80: # Wrong - erroneous quotes:
ldap.conf.5:83: # Right - space-separated list of URIs, without quotes:
ldap.conf.5:86: # Right - DN syntax needs quoting for Example, Inc:
ldap.conf.5:91: # Wrong - comment on same line as option:
-.-.
Split a punctuation mark from a single argument for a two-font macro
196:.BR URI.
-.-.
The name of a man page is typeset in bold and the section in roman
(see man-pages(7)).
188:Specifies the timeout (in seconds) after which the poll(2)/select(2)
189:following a connect(2) returns in case of no activity.
-.-.
Split a punctuation from a single argument, if a two-font macro is meant
341:.B TLS_CACERTDIR.
-.-.
[ "test-groff" is a developmental version of "groff" ]
Input file is ./ldap.conf.5
Output from "test-groff -b -mandoc -dAD=l -rF0 -rHY=0 -t -w w -z -rCHECKSTYLE=0":
troff: backtrace: file 'stdin':68
troff:stdin:68: warning: trailing space in the line
troff: backtrace: file 'stdin':70
troff:stdin:70: warning: trailing space in the line
troff: backtrace: file 'stdin':71
troff:stdin:71: warning: trailing space in the line
troff: backtrace: file 'stdin':74
troff:stdin:74: warning: trailing space in the line
troff: backtrace: file 'stdin':120
troff:stdin:120: warning: trailing space in the line
troff: backtrace: file 'stdin':121
troff:stdin:121: warning: trailing space in the line
troff: backtrace: file 'stdin':213
troff:stdin:213: warning: trailing space in the line
troff: backtrace: file 'stdin':254
troff:stdin:254: warning: trailing space in the line
troff: backtrace: file 'stdin':362
troff:stdin:362: warning: trailing space in the line
troff: backtrace: file 'stdin':381
troff:stdin:381: warning: trailing space in the line
troff: backtrace: file 'stdin':383
troff:stdin:383: warning: trailing space in the line
troff: backtrace: file 'stdin':474
troff:stdin:474: warning: trailing space in the line
troff: backtrace: file './../Project':5
troff:./../Project:5: warning: trailing space in the line
-.-.
Additional: use "tbl" to make a table, which preserves lineup of columns
in the troff-mode.
Add a first line with information for "man" to preprocess the file with
"tbl".
-.-
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (990, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.4.13-1 (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)
-- no debconf information
-------------- next part --------------
The difference between the formatted outputs can be seen with:
nroff -man <file1> > <out1>
nroff -man <file2> > <out2>
diff -u <out1> <out2>
and for groff, using
"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -man -Z - "
instead of "nroff -man"
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 -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-.
Output from "mandoc -T lint ldap.conf.5":
mandoc: ldap.conf.5:1:2: ERROR: skipping insecure request: lf
mandoc: ldap.conf.5:30:2: WARNING: skipping paragraph macro: PP empty
mandoc: ldap.conf.5:69:61: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:71:58: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:72:58: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:75:61: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:104:9: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:107:10: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:118:9: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:121:65: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:122:65: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:125:1: WARNING: tab in filled text
mandoc: ldap.conf.5:129:1: WARNING: tab in filled text
mandoc: ldap.conf.5:162:2: WARNING: line scope broken: TP breaks TP
mandoc: ldap.conf.5:166:9: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:214:75: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:255:46: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:283:20: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:291:20: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:299:24: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:305:87: STYLE: input text line longer than 80 bytes: Do not perform rever...
mandoc: ldap.conf.5:308:88: STYLE: input text line longer than 80 bytes: The channel-binding ...
mandoc: ldap.conf.5:310:94: STYLE: input text line longer than 80 bytes: If OpenLDAP is built...
mandoc: ldap.conf.5:363:57: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:382:67: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:384:28: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:411:83: STYLE: input text line longer than 80 bytes: This parameter is ig...
mandoc: ldap.conf.5:417:83: STYLE: input text line longer than 80 bytes: This parameter is ig...
mandoc: ldap.conf.5:475:71: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:479:104: STYLE: input text line longer than 80 bytes: parameter to be set....
mandoc: ldap.conf.5:530:2: ERROR: skipping insecure request: lf
mandoc: ldap.conf.5:535:62: STYLE: whitespace at end of input line
mandoc: ldap.conf.5:536:2: ERROR: skipping insecure request: lf
-.-.
Input file is ldap.conf.5.
Remove space characters at the end of lines.
69:conventionally written in uppercase, although not required),
71:The value starts with the first non-blank character after
72:the option's name, and terminates at the end of the line,
75:for that option, if any. Quoting values that contain blanks
104:.I LDAP
107:.B ldaps
118:.B name
121:is required, nor allowed; note that directory separators must be
122:URL-encoded, like any other characters that are special to URLs;
166:.I LDAP
214:may still apply any server-side limit on the amount of entries that can be
255:Specifies Cyrus SASL security properties. The
283:.B minssf=<factor>
291:.B maxssf=<factor>
299:.B maxbufsize=<factor>
363:<cipher-suite-spec> should be a cipher specification for
382:With GnuTLS the available specs can be found in the manual page of
384:(see the description of the
475:Specifies if the Certificate Revocation List (CRL) of the CA should be
535:is derived from the University of Michigan LDAP 3.3 Release.
-.-.
Use "\e" to print the escape character instead of "\\" (which gets
interpreted in copy mode).
89: BASE ou=IT staff,o=Example\\2C Inc,c=US
-.-.
Test nr. 18:
Wrong distance between sentences.
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.
N.B
The number of lines affected is too large to be in the patch.
143:Specifies how alias dereferencing is done when performing a search. The
149:Aliases are never dereferenced. This is the default.
177:before TCP starts sending keepalive probes. Linux only.
181:before dropping the connection. Linux only.
219:Multiple IP addresses must be space separated. Only one valid IPv4
255:Specifies Cyrus SASL security properties. The
305:Do not perform reverse DNS lookups to canonicalize SASL host names. The default is off.
308:The channel-binding type to use, see also LDAP_OPT_X_SASL_CBINDING. The default is none.
319:should be used. The default is off.
324:attribute of the targets RootDSE entry. The default is off.
338:certificates in separate individual files. The
357:file. Currently, the private key must not be protected with a password, so
411:This parameter is ignored with GnuTLS. On Debian openldap is linked against GnuTLS.
415:not available. Generally set to the name of the EGD/PRNGD socket.
417:This parameter is ignored with GnuTLS. On Debian openldap is linked against GnuTLS.
430:The server certificate is requested. If a bad certificate is provided, it will
434:The server certificate is requested. If a bad certificate is provided,
446:name against the specified hostname of the server. The
455:The SAN is checked against the specified hostname. If a SAN is
461:The SAN is checked against the specified hostname. If no SAN is present
463:is used. If a SAN is present but doesn't match the specified hostname,
464:the session is immediately terminated. This setting may be preferred
468:These keywords are equivalent. The SAN is checked against the specified
469:hostname. If no SAN is present in the server certificate, or no SANs
470:match, the session is immediately terminated. This setting should be
476:used to verify if the server certificates have not been revoked. This
479:parameter to be set. This parameter is ignored with GnuTLS. On Debian openldap is linked against GnuTLS.
496:to verify if the server certificates have not been revoked. This
-.-.
Test nr. 32:
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.
ldap.conf.5: line 305 length 87
Do not perform reverse DNS lookups to canonicalize SASL host names. The default is off.
ldap.conf.5: line 308 length 88
The channel-binding type to use, see also LDAP_OPT_X_SASL_CBINDING. The default is none.
ldap.conf.5: line 310 length 94
If OpenLDAP is built with Generic Security Services Application Programming Interface support,
ldap.conf.5: line 389 length 83
\-\-priority, you can obtain the \(em more limited \(em list of ciphers by calling:
ldap.conf.5: line 411 length 83
This parameter is ignored with GnuTLS. On Debian openldap is linked against GnuTLS.
ldap.conf.5: line 417 length 83
This parameter is ignored with GnuTLS. On Debian openldap is linked against GnuTLS.
ldap.conf.5: line 479 length 104
parameter to be set. This parameter is ignored with GnuTLS. On Debian openldap is linked against GnuTLS.
-.-.
Use \(en for a dash (en-dash) between space characters, not a minus
(\-) or a hyphen (-), except in the NAME section.
ldap.conf.5:80: # Wrong - erroneous quotes:
ldap.conf.5:83: # Right - space-separated list of URIs, without quotes:
ldap.conf.5:86: # Right - DN syntax needs quoting for Example, Inc:
ldap.conf.5:91: # Wrong - comment on same line as option:
-.-.
Split a punctuation mark from a single argument for a two-font macro
196:.BR URI.
-.-.
Test nr. 42:
The name of a man page is typeset in bold and the section in roman
(see man-pages(7)).
188:Specifies the timeout (in seconds) after which the poll(2)/select(2)
189:following a connect(2) returns in case of no activity.
-.-.
Split a punctuation from a single argument, if a two-font macro is meant
341:.B TLS_CACERTDIR.
-.-.
[ "test-groff" is a developmental version of "groff" ]
Input file is ./ldap.conf.5
Output from "test-groff -b -mandoc -dAD=l -rF0 -rHY=0 -t -w w -z -rCHECKSTYLE=0":
troff: backtrace: file 'stdin':68
troff:stdin:68: warning: trailing space in the line
troff: backtrace: file 'stdin':70
troff:stdin:70: warning: trailing space in the line
troff: backtrace: file 'stdin':71
troff:stdin:71: warning: trailing space in the line
troff: backtrace: file 'stdin':74
troff:stdin:74: warning: trailing space in the line
troff: backtrace: file 'stdin':120
troff:stdin:120: warning: trailing space in the line
troff: backtrace: file 'stdin':121
troff:stdin:121: warning: trailing space in the line
troff: backtrace: file 'stdin':213
troff:stdin:213: warning: trailing space in the line
troff: backtrace: file 'stdin':254
troff:stdin:254: warning: trailing space in the line
troff: backtrace: file 'stdin':362
troff:stdin:362: warning: trailing space in the line
troff: backtrace: file 'stdin':381
troff:stdin:381: warning: trailing space in the line
troff: backtrace: file 'stdin':383
troff:stdin:383: warning: trailing space in the line
troff: backtrace: file 'stdin':474
troff:stdin:474: warning: trailing space in the line
troff: backtrace: file './../Project':5
troff:./../Project:5: warning: trailing space in the line
-.-.
Additional: use "tbl" to make a table, which preserves lineup of columns
in the troff-mode.
Add a first line with information for "man" to preprocess the file with
"tbl".
-.-
More information about the Pkg-openldap-devel
mailing list