Bug#1052265: ldap.conf.5: some remarks and editorial changes for this man page

[Ryan Tandy]

Control: tag -1 moreinfo

Hello Bjarni, thank you for your contribution.

The man page is maintained upstream. May I ask you to submit your 
changes directly to the OpenLDAP project? (It's better if you can do so 
yourself, than if I do it on your behalf.)

There is a guide for contributors: 
<https://openldap.org/devel/contributing.html>. They will probably ask 
you to format your patch as unified diff (diff -u) or a git branch.

Thanks again,
Ryan

On Tue, Sep 19, 2023 at 06:13:42PM +0000, Bjarni Ingi Gislason wrote:
>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

>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".
>
>-.-

>_______________________________________________
>Pkg-openldap-devel mailing list
>Pkg-openldap-devel at alioth-lists.debian.net
>https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/pkg-openldap-devel