Package: libldap-common
Version: 2.6.9+dfsg-1
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 ' $' -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:68: warning: trailing space in the line
troff:stdin:70: warning: trailing space in the line
troff:stdin:71: warning: trailing space in the line
troff:stdin:74: warning: trailing space in the line
troff:stdin:120: warning: trailing space in the line
troff:stdin:121: warning: trailing space in the line
an.tmac:stdin:162: warning: cannot nest .TP or .TQ inside .TP; supply a tag
an.tmac:stdin:195: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
troff:stdin:213: warning: trailing space in the line
troff:stdin:254: warning: trailing space in the line
troff:stdin:363: warning: trailing space in the line
troff:stdin:382: warning: trailing space in the line
troff:stdin:384: warning: trailing space in the line
troff:stdin:475: warning: trailing space in the line
troff:./../Project:5: 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.12-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)
-- no debconf information
Input file is ldap.conf.5
Output from "mandoc -T lint ldap.conf.5": (shortened list)
1 input text line longer than 80 bytes: Do not perform rever...
1 input text line longer than 80 bytes: If OpenLDAP is built...
1 input text line longer than 80 bytes: The channel-binding ...
1 line scope broken: TP breaks TP
3 skipping insecure request: lf
1 skipping paragraph macro: PP empty
20 whitespace at end of input line
-.-.
Output from "test-groff -mandoc -t -ww -z ldap.conf.5": (shortened list)
1 Use macro '.B' for one argument or split argument.
1 .BR is for at least 2 arguments, got 1
1 cannot nest .TP or .TQ inside .TP; supply a tag
13 trailing space in the line
-.-.
Remove space characters (whitespace) at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
Number of lines affected is
20
-.-.
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 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 "\&".
Some sentences (etc.) do not begin on a new line.
N.B.
The number of lines affected can be too large to be in a 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. Multiple directories may
358:file. Currently, the private key must not be protected with a password, so
416:not available. Generally set to the name of the EGD/PRNGD socket.
431:The server certificate is requested. If a bad certificate is provided, it
will
435:The server certificate is requested. If a bad certificate is provided,
447:name against the specified hostname of the server. The
456:The SAN is checked against the specified hostname. If a SAN is
462:The SAN is checked against the specified hostname. If no SAN is present
464:is used. If a SAN is present but doesn't match the specified hostname,
465:the session is immediately terminated. This setting may be preferred
469:These keywords are equivalent. The SAN is checked against the specified
470:hostname. If no SAN is present in the server certificate, or no SANs
471:match, the session is immediately terminated. This setting should be
477:used to verify if the server certificates have not been revoked. This
480:parameter to be set. This parameter is ignored with GnuTLS.
497: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.
Line 305, length 87
Do not perform reverse DNS lookups to canonicalize SASL host names. The default
is off.
Line 308, length 88
The channel-binding type to use, see also LDAP_OPT_X_SASL_CBINDING. The default
is none.
Line 310, length 94
If OpenLDAP is built with Generic Security Services Application Programming
Interface support,
Line 390, length 83
\-\-priority, you can obtain the \(em more limited \(em list of ciphers by
calling:
-.-.
Use \(en (en-dash) for a dash at the beginning (en) of a line,
or 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.
342:.B TLS_CACERTDIR.
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
ldap.conf.5:111:over IPC (UNIX domain sockets), respectively.
ldap.conf.5:116:port for the scheme is used (389 for ldap://, 636 for ldaps://).
ldap.conf.5:188:Specifies the timeout (in seconds) after which the
poll(2)/select(2)
ldap.conf.5:211:Specifies a size limit (number of entries) to use when
performing searches.
ldap.conf.5:223:Specifies a time limit (in seconds) to use when performing
searches.
ldap.conf.5:232:Specifies a timeout (in seconds) after which calls to
synchronous LDAP
ldap.conf.5:318:Specifies if GSSAPI encryption (GSS_C_INTEG_FLAG and
GSS_C_CONF_FLAG)
ldap.conf.5:329:is selected (by default or otherwise) or when the application
ldap.conf.5:365:the TLS library in use (OpenSSL or GnuTLS).
-.-.
Use thousand markers to make large numbers easy to read
301:size allowed. 0 disables security layers. The default is 65536.
-.-.
Remove quotes when there is a printable
but no space character between them
and the quotes are not for emphasis (markup),
for example as an argument to a macro.
2:.TH LDAP.CONF 5 "2024/11/26" "OpenLDAP 2.6.9+dfsg-1"
-.-.
Trailing space in a macro call.
104:.I LDAP
107:.B ldaps
118:.B name
166:.I LDAP
283:.B minssf=<factor>
291:.B maxssf=<factor>
299:.B maxbufsize=<factor>
-.-.
Section headings (.SH and .SS) do not need quoting.
499:.SH "ENVIRONMENT VARIABLES"
522:.SH "SEE ALSO"
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
troff:stdin:68: warning: trailing space in the line
troff:stdin:70: warning: trailing space in the line
troff:stdin:71: warning: trailing space in the line
troff:stdin:74: warning: trailing space in the line
troff:stdin:120: warning: trailing space in the line
troff:stdin:121: warning: trailing space in the line
an.tmac:stdin:162: warning: cannot nest .TP or .TQ inside .TP; supply a tag
an.tmac:stdin:195: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
troff:stdin:213: warning: trailing space in the line
troff:stdin:254: warning: trailing space in the line
troff:stdin:363: warning: trailing space in the line
troff:stdin:382: warning: trailing space in the line
troff:stdin:384: warning: trailing space in the line
troff:stdin:475: warning: trailing space in the line
troff:./../Project:5: warning: trailing space in the line
--- ldap.conf.5 2025-02-12 00:41:31.897139924 +0000
+++ ldap.conf.5.new 2025-02-12 01:51:47.869074311 +0000
@@ -1,5 +1,4 @@
-.lf 1 stdin
-.TH LDAP.CONF 5 "2024/11/26" "OpenLDAP 2.6.9+dfsg-1"
+.TH LDAP.CONF 5 2024/11/26 "OpenLDAP 2.6.9+dfsg-1"
.\" $OpenLDAP$
.\" Copyright 1998-2024 The OpenLDAP Foundation All Rights Reserved.
.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
@@ -28,7 +27,6 @@ The file
.I ldaprc
in the current working directory is also used.
.LP
-.LP
Additional configuration files can be specified using
the \fBLDAPCONF\fP and \fBLDAPRC\fP environment variables.
\fBLDAPCONF\fP may be set to the path of a configuration file. This
@@ -51,7 +49,7 @@ Thus the following files and variables a
.nf
variable $LDAPNOINIT, and if that is not set:
system file /etc/ldap/ldap.conf,
- user files $HOME/ldaprc, $HOME/.ldaprc, ./ldaprc,
+ user files $HOME/ldaprc, $HOME/.ldaprc, ./ldaprc,
system file $LDAPCONF,
user files $HOME/$LDAPRC, $HOME/.$LDAPRC, ./$LDAPRC,
variables $LDAP<uppercase option name>.
@@ -66,29 +64,29 @@ Blank lines are ignored.
Lines beginning with a hash mark (`#') are comments, and ignored.
.LP
Valid lines are made of an option's name (a sequence of non-blanks,
-conventionally written in uppercase, although not required),
+conventionally written in uppercase, although not required),
followed by a value.
-The value starts with the first non-blank character after
-the option's name, and terminates at the end of the line,
+The value starts with the first non-blank character after
+the option's name, and terminates at the end of the line,
or at the last sequence of blanks before the end of the line.
The tokenization of the value, if any, is delegated to the handler(s)
-for that option, if any. Quoting values that contain blanks
+for that option, if any. Quoting values that contain blanks
may be incorrect, as the quotes would become part of the value.
For example,
.nf
- # Wrong - erroneous quotes:
+ # Wrong \(en erroneous quotes:
URI "ldap:// ldaps://"
- # Right - space-separated list of URIs, without quotes:
+ # Right \(en space-separated list of URIs, without quotes:
URI ldap:// ldaps://
- # Right - DN syntax needs quoting for Example, Inc:
+ # Right \(en DN syntax needs quoting for Example, Inc:
BASE ou=IT staff,o="Example, Inc",c=US
# or:
- BASE ou=IT staff,o=Example\\2C Inc,c=US
+ BASE ou=IT staff,o=Example\e2C Inc,c=US
- # Wrong - comment on same line as option:
+ # Wrong \(en comment on same line as option:
DEREF never # Never follow aliases
.fi
.LP
@@ -101,10 +99,10 @@ The different configuration options are:
.TP
.B URI <ldap[si]://[name[:port]] ...>
Specifies the URI(s) of an LDAP server(s) to which the
-.I LDAP
+.I LDAP
library should connect. The URI scheme may be any of
.BR ldap ,
-.B ldaps
+.B ldaps
or
.BR ldapi ,
which refer to LDAP over TCP, LDAP over SSL (TLS) and LDAP
@@ -115,11 +113,11 @@ server's name can followed by a ':' and
server is listening on. If no port number is provided, the default
port for the scheme is used (389 for ldap://, 636 for ldaps://).
For LDAP over IPC,
-.B name
+.B name
is the name of the socket, and no
.B port
-is required, nor allowed; note that directory separators must be
-URL-encoded, like any other characters that are special to URLs;
+is required, nor allowed; note that directory separators must be
+URL-encoded, like any other characters that are special to URLs;
so the socket
/usr/local/var/ldapi
@@ -140,13 +138,15 @@ The bind DN must be specified as a Disti
.B This is a user-only option.
.TP
.B DEREF <when>
-Specifies how alias dereferencing is done when performing a search. The
+Specifies how alias dereferencing is done when performing a search.
+The
.B <when>
can be specified as one of the following keywords:
.RS
.TP
.B never
-Aliases are never dereferenced. This is the default.
+Aliases are never dereferenced.
+This is the default.
.TP
.B searching
Aliases are dereferenced in subordinates of the base object, but
@@ -160,10 +160,9 @@ Aliases are dereferenced both in searchi
of the search.
.RE
.TP
-.TP
.B HOST <name[:port] ...>
Specifies the name(s) of an LDAP server(s) to which the
-.I LDAP
+.I LDAP
library should connect. Each server's name can be specified as a
domain-style name or an IP address and optionally followed by a ':' and
the port number the ldap server is listening on. A space separated
@@ -174,26 +173,31 @@ is deprecated in favor of
.TP
.B KEEPALIVE_IDLE
Sets/gets the number of seconds a connection needs to remain idle
-before TCP starts sending keepalive probes. Linux only.
+before TCP starts sending keepalive probes.
+Linux only.
.TP
.B KEEPALIVE_PROBES
Sets/gets the maximum number of keepalive probes TCP should send
-before dropping the connection. Linux only.
+before dropping the connection.
+Linux only.
.TP
.B KEEPALIVE_INTERVAL
Sets/gets the interval in seconds between individual keepalive probes.
Linux only.
.TP
.B NETWORK_TIMEOUT <integer>
-Specifies the timeout (in seconds) after which the poll(2)/select(2)
-following a connect(2) returns in case of no activity.
+Specifies the timeout (in seconds) after which the
+.BR poll (2)/ select (2)
+following a
+.BR connect (2)
+returns in case of no activity.
.TP
.B PORT <port>
Specifies the default port used when connecting to LDAP servers(s).
The port may be specified as a number.
.B PORT
is deprecated in favor of
-.BR URI.
+.BR URI .
.TP
.B REFERRALS <on/true/yes/off/false/no>
Specifies if the client should automatically follow referrals returned
@@ -211,12 +215,13 @@ Note that the command line tools
Specifies a size limit (number of entries) to use when performing searches.
The number should be a non-negative integer. \fISIZELIMIT\fP of zero (0)
specifies a request for unlimited search size. Please note that the server
-may still apply any server-side limit on the amount of entries that can be
+may still apply any server-side limit on the amount of entries that can be
returned by a search operation.
.TP
.B SOCKET_BIND_ADDRESSES <IP>
Specifies the source bind IP to be used for connecting to target LDAP server.
-Multiple IP addresses must be space separated. Only one valid IPv4
+Multiple IP addresses must be space separated.
+Only one valid IPv4
address and/or one valid IPv6 address are allowed in the list.
.TP
.B TIMELIMIT <integer>
@@ -252,7 +257,8 @@ Specifies the proxy authorization identi
.B This is a user-only option.
.TP
.B SASL_SECPROPS <properties>
-Specifies Cyrus SASL security properties. The
+Specifies Cyrus SASL security properties.
+The
.B <properties>
can be specified as a comma-separated list of the following:
.RS
@@ -280,7 +286,7 @@ requires forward secrecy between session
requires mechanisms which pass client credentials (and allows
mechanisms which can pass credentials to do so).
.TP
-.B minssf=<factor>
+.B minssf=<factor>
specifies the minimum acceptable
.I security strength factor
as an integer approximate to effective key length used for
@@ -288,7 +294,7 @@ encryption. 0 (zero) implies no protect
protection only, 128 allows RC4, Blowfish and other similar ciphers,
256 will require modern ciphers. The default is 0.
.TP
-.B maxssf=<factor>
+.B maxssf=<factor>
specifies the maximum acceptable
.I security strength factor
as an integer (see
@@ -296,18 +302,21 @@ as an integer (see
description). The default is
.BR INT_MAX .
.TP
-.B maxbufsize=<factor>
+.B maxbufsize=<factor>
specifies the maximum security layer receive buffer
-size allowed. 0 disables security layers. The default is 65536.
+size allowed. 0 disables security layers. The default is 65,536.
.RE
.TP
.B SASL_NOCANON <on/true/yes/off/false/no>
-Do not perform reverse DNS lookups to canonicalize SASL host names. The
default is off.
+Do not perform reverse DNS lookups to canonicalize SASL host names.
+The default is off.
.TP
.B SASL_CBINDING <none/tls-unique/tls-endpoint>
-The channel-binding type to use, see also LDAP_OPT_X_SASL_CBINDING. The
default is none.
+The channel-binding type to use, see also LDAP_OPT_X_SASL_CBINDING.
+The default is none.
.SH GSSAPI OPTIONS
-If OpenLDAP is built with Generic Security Services Application Programming
Interface support,
+If OpenLDAP is built with Generic Security Services Application
+Programming Interface support,
there are more options you can specify.
.TP
.B GSSAPI_SIGN <on/true/yes/off/false/no>
@@ -316,12 +325,14 @@ The default is off.
.TP
.B GSSAPI_ENCRYPT <on/true/yes/off/false/no>
Specifies if GSSAPI encryption (GSS_C_INTEG_FLAG and GSS_C_CONF_FLAG)
-should be used. The default is off.
+should be used.
+The default is off.
.TP
.B GSSAPI_ALLOW_REMOTE_PRINCIPAL <on/true/yes/off/false/no>
Specifies if GSSAPI based authentication should try to form the
target principal name out of the ldapServiceName or dnsHostName
-attribute of the targets RootDSE entry. The default is off.
+attribute of the targets RootDSE entry.
+The default is off.
.SH TLS OPTIONS
If OpenLDAP is built with Transport Layer Security support, there
are more options you can specify. These options are used when an
@@ -335,11 +346,12 @@ Authorities the client will recognize.
.TP
.B TLS_CACERTDIR <path>
Specifies the path of directories that contain Certificate Authority
-certificates in separate individual files. Multiple directories may
+certificates in separate individual files.
+Multiple directories may
be specified, separated by a semi-colon. The
.B TLS_CACERT
is always used before
-.B TLS_CACERTDIR.
+.BR TLS_CACERTDIR .
.TP
.B TLS_CERT <filename>
Specifies the file that contains the client certificate.
@@ -355,13 +367,14 @@ chosen in the GnuTLS ciphersuite specifi
Specifies the file that contains the private key that matches the certificate
stored in the
.B TLS_CERT
-file. Currently, the private key must not be protected with a password, so
+file.
+Currently, the private key must not be protected with a password, so
it is of critical importance that the key file is protected carefully.
.B This is a user-only option.
.TP
.B TLS_CIPHER_SUITE <cipher-suite-spec>
Specifies acceptable cipher suite and preference order.
-<cipher-suite-spec> should be a cipher specification for
+<cipher-suite-spec> should be a cipher specification for
the TLS library in use (OpenSSL or GnuTLS).
Example:
.RS
@@ -380,10 +393,9 @@ To check what ciphers a given spec selec
openssl ciphers \-v <cipher-suite-spec>
.fi
-With GnuTLS the available specs can be found in the manual page of
+With GnuTLS the available specs can be found in the manual page of
.BR gnutls\-cli (1)
-(see the description of the
-option
+(see the description of the option
.BR \-\-priority ).
In older versions of GnuTLS, where gnutls\-cli does not support the option
@@ -413,7 +425,8 @@ This parameter is ignored with GnuTLS.
.TP
.B TLS_RANDFILE <filename>
Specifies the file to obtain random bits from when /dev/[u]random is
-not available. Generally set to the name of the EGD/PRNGD socket.
+not available.
+Generally set to the name of the EGD/PRNGD socket.
The environment variable RANDFILE can also be used to specify the filename.
This parameter is ignored with GnuTLS.
.TP
@@ -428,11 +441,13 @@ can be specified as one of the following
The client will not request or check any server certificate.
.TP
.B allow
-The server certificate is requested. If a bad certificate is provided, it will
+The server certificate is requested.
+If a bad certificate is provided, it will
be ignored and the session proceeds normally.
.TP
.B try
-The server certificate is requested. If a bad certificate is provided,
+The server certificate is requested.
+If a bad certificate is provided,
the session is immediately terminated.
.TP
.B demand | hard
@@ -444,7 +459,8 @@ This is the default setting.
.B TLS_REQSAN <level>
Specifies what checks to perform on the subjectAlternativeName
(SAN) extensions in a server certificate when validating the certificate
-name against the specified hostname of the server. The
+name against the specified hostname of the server.
+The
.B <level>
can be specified as one of the following keywords:
.RS
@@ -453,31 +469,39 @@ can be specified as one of the following
The client will not check any SAN in the certificate.
.TP
.B allow
-The SAN is checked against the specified hostname. If a SAN is
+The SAN is checked against the specified hostname.
+If a SAN is
present but none match the specified hostname, the SANs are ignored
and the usual check against the certificate DN is used.
This is the default setting.
.TP
.B try
-The SAN is checked against the specified hostname. If no SAN is present
+The SAN is checked against the specified hostname.
+If no SAN is present
in the server certificate, the usual check against the certificate DN
-is used. If a SAN is present but doesn't match the specified hostname,
-the session is immediately terminated. This setting may be preferred
+is used.
+If a SAN is present but doesn't match the specified hostname,
+the session is immediately terminated.
+This setting may be preferred
when a mix of certs with and without SANs are in use.
.TP
.B demand | hard
-These keywords are equivalent. The SAN is checked against the specified
-hostname. If no SAN is present in the server certificate, or no SANs
-match, the session is immediately terminated. This setting should be
+These keywords are equivalent.
+The SAN is checked against the specified hostname.
+If no SAN is present in the server certificate, or no SANs
+match, the session is immediately terminated.
+This setting should be
used when only certificates with SANs are in use.
.RE
.TP
.B TLS_CRLCHECK <level>
-Specifies if the Certificate Revocation List (CRL) of the CA should be
-used to verify if the server certificates have not been revoked. This
+Specifies if the Certificate Revocation List (CRL) of the CA should be
+used to verify if the server certificates have not been revoked.
+This
requires
.B TLS_CACERTDIR
-parameter to be set. This parameter is ignored with GnuTLS.
+parameter to be set.
+This parameter is ignored with GnuTLS.
.B <level>
can be specified as one of the following keywords:
.RS
@@ -494,9 +518,10 @@ Check the CRL for a whole certificate ch
.TP
.B TLS_CRLFILE <filename>
Specifies the file containing a Certificate Revocation List to be used
-to verify if the server certificates have not been revoked. This
+to verify if the server certificates have not been revoked.
+This
parameter is only supported with GnuTLS.
-.SH "ENVIRONMENT VARIABLES"
+.SH ENVIRONMENT VARIABLES
.TP
LDAPNOINIT
disable all defaulting
@@ -519,7 +544,7 @@ user ldap configuration file
.TP
.I $CWD/ldaprc
local ldap configuration file
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR ldap (3),
.BR ldap_set_option (3),
.BR ldap_result (3),
@@ -528,10 +553,8 @@ local ldap configuration file
.SH AUTHOR
Kurt Zeilenga, The OpenLDAP Project
.SH ACKNOWLEDGEMENTS
-.lf 1 ./../Project
.\" Shared Project Acknowledgement Text
.B "OpenLDAP Software"
is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>.
.B "OpenLDAP Software"
-is derived from the University of Michigan LDAP 3.3 Release.
-.lf 531 stdin
+is derived from the University of Michigan LDAP 3.3 Release.
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 -d -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 -d -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)
-.-
