[patch] nscd.conf.5: describe reloading, clarifications

[patch] nscd.conf.5: describe reloading, clarifications

[Greg Banks]

- Added a subsection of NOTES describing nscd's reloading behavior
  and providing advice on how to configure it.
- Clarifications for the threads, reload-count, positive-time-to-live,
  check-files, and shared attributes.

Derived by reading the nscd, libresolv and glibc source and some painful experience.

diff --git a/man5/nscd.conf.5 b/man5/nscd.conf.5
index 7356bf7c2..52f7051d5 100644
--- a/man5/nscd.conf.5
+++ b/man5/nscd.conf.5
@@ -1,5 +1,6 @@
 .\" Copyright (c) 1999, 2000 SuSE GmbH Nuernberg, Germany
 .\" Author: Thorsten Kukuk <kukuk@suse.de>
+.\" Updates by Greg Banks <gbanks@linkedin.com> Copyright (c) 2021 Microsoft Corp.
 .\"
 .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
 .\" This program is free software; you can redistribute it and/or
@@ -53,9 +54,12 @@ The default is 0.
 .B threads
 .I number
 .RS
-This is the number of threads that are started to wait for
+This is the initial number of threads that are started to wait for
 requests.
-At least five threads will always be created.
+At least five threads will always be created.  The number of threads
+may increase dynamically up to
+.B max\-threads
+in response to demand from clients, but never decreases.
 .RE
 .PP
 .B max\-threads
@@ -83,9 +87,15 @@ Specifies the user who is allowed to request statistics.
 unlimited |
 .I number
 .RS
-Limit on the number of times a cached entry gets reloaded without being used
-before it gets removed.
-The default is 5.
+Sets a limit on the number of times a cached entry gets reloaded without being used
+before it gets removed.  The limit can take values ranging from 0
+to 254; values 255 or higher behave the same as
+.BR unlimited .
+Limit values can be specified in either decimal or hexadecimal with a
+"0x" prefix.  The special value
+.B unlimited
+is case-insensitive.  The default limit is 5.  A limit of 0 turns off the reloading
+feature.  See NOTES below for further discussion of reloading.
 .RE
 .PP
 .B paranoia
@@ -128,6 +138,9 @@ in the specified cache for
 is in seconds.
 Larger values increase cache hit rates and reduce mean
 response times, but increase problems with cache coherence.
+Note that for some name services (including specifically DNS)
+the TTL returned from the name service is used and this attribute
+is ignored.
 .RE
 .PP
 .B negative\-time\-to\-live
@@ -166,6 +179,7 @@ The files are
 .IR /etc/passwd ,
 .IR /etc/group ,
 .IR /etc/hosts ,
+.IR /etc/resolv.conf ,
 .IR /etc/services ,
 and
 .IR /etc/netgroup .
@@ -194,6 +208,8 @@ is shared with the clients so
 that they can directly search in them instead of having to ask the
 daemon over the socket each time a lookup is performed.
 The default is no.
+Note that a cache miss will still result in asking the daemon over
+the socket.
 .RE
 .PP
 .B max\-db\-size
@@ -230,12 +246,82 @@ and
 .IR group .
 .RE
 .SH NOTES
+.PP
 The default values stated in this manual page originate
 from the source code of
 .BR nscd (8)
 and are used if not overridden in the configuration file.
 The default values used in the configuration file of
 your distribution might differ.
+.SS Reloading
+.PP
+.BR nscd (8)
+has a feature called reloading whose behavior can be surprising.
+.PP
+Reloading is enabled when the
+.B reload-count
+attribute has a non-zero value.  The default value in the source
+code enables reloading, although your distribution may differ.
+.PP
+When
+reloading is enabled, positive cached entries (the results of
+successful queries) do not simply expire when their TTL is up.  Instead,
+at the expiry time
+.B nscd
+will "reload", i.e. re-issue the same name service query that created the cached
+entry, to get a new value to cache.  Depending on
+.B /etc/nsswitch.conf
+this may mean that a DNS, LDAP or NIS request is made.  If the new query
+is successful reloading will repeat
+when the new value would expire, until
+.B reload-count
+reloads have happened for the entry, and only then will it actually be removed
+from the cache.  A request from a client which hits the entry will reset
+the reload counter on the entry.  Purging the cache using the
+.B \-i
+command line option overrides the reload logic and removes the entry.
+.PP
+Reloading has the effect of extending cache entry TTLs without compromising
+on cache coherency, at the cost of additional load on the backing name service.
+Whether this is a good idea on your system depends on details of
+your applications' behavior, your name service, and the effective TTL values of
+your cache entries.  (Note that for some name services (for example, DNS), the
+effective TTL is the value returned from the name service and
+.I not
+the value of the
+.B positive\-time\-to\-live
+attribute.)  Please consider the following advice carefully:
+.IP \(bu
+If your application will make a second request for the same name, after
+more then 1 TTL but before
+.B reload\-count
+TTLs, and is sensitive to the latency of a cache miss, then reloading may be
+a good idea for you.
+.IP \(bu
+If your name service is configured to return very short TTLs, and your
+applications only make requests rarely under normal circumstances, then
+reloading may result in additional load on your backing name service
+without any benefit to applications, which is probably a bad idea for you.
+.IP \(bu
+If your name service capacity is limited, reloading may have the
+surprising effect of increasing load on your name service instead of
+reducing it, and may be a bad idea for you.
+.IP \(bu
+Setting
+.B reload\-count
+to
+.B unlimited
+is almost never a good idea, as it will result in a cache that never expires
+entries and puts never-ending additional load on the backing name service.
+.PP
+Note also that some distributions have an init script for nscd with a "reload"
+command which has the effect of purging
+.BR nscd 's
+caches using the
+.B \-i
+commandline option.  That use of the word "reload" is
+.I entirely different
+from the "reloading" described here.
 .SH SEE ALSO
 .BR nscd (8)
 .\" .SH AUTHOR

Re: [patch] nscd.conf.5: describe reloading, clarifications

[Alejandro Colomar (man-pages)]

Hello Greg,

On 7/28/21 12:09 AM, Greg Banks wrote:
> - Added a subsection of NOTES describing nscd's reloading behavior
>    and providing advice on how to configure it.
> - Clarifications for the threads, reload-count, positive-time-to-live,
>    check-files, and shared attributes.
> 
> Derived by reading the nscd, libresolv and glibc source and some painful experience.

Thanks for the patch.

Please see some comments below.

Thanks,

Alex

> 
> diff --git a/man5/nscd.conf.5 b/man5/nscd.conf.5
> index 7356bf7c2..52f7051d5 100644
> --- a/man5/nscd.conf.5
> +++ b/man5/nscd.conf.5
> @@ -1,5 +1,6 @@
>   .\" Copyright (c) 1999, 2000 SuSE GmbH Nuernberg, Germany
>   .\" Author: Thorsten Kukuk <kukuk@suse.de>
> +.\" Updates by Greg Banks <gbanks@linkedin.com> Copyright (c) 2021 Microsoft Corp.
>   .\"
>   .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
>   .\" This program is free software; you can redistribute it and/or
> @@ -53,9 +54,12 @@ The default is 0.
>   .B threads
>   .I number
>   .RS
> -This is the number of threads that are started to wait for
> +This is the initial number of threads that are started to wait for
>   requests.
> -At least five threads will always be created.
> +At least five threads will always be created.  The number of threads
> +may increase dynamically up to
> +.B max\-threads
> +in response to demand from clients, but never decreases.
>   .RE
>   .PP
>   .B max\-threads
> @@ -83,9 +87,15 @@ Specifies the user who is allowed to request statistics.
>   unlimited |
>   .I number
>   .RS
> -Limit on the number of times a cached entry gets reloaded without being used
> -before it gets removed.
> -The default is 5.
> +Sets a limit on the number of times a cached entry gets reloaded without being used


See the following extract from man-pages(7):

$ man 7 man-pages | sed -n '/Use semantic newlines/,/^$/p';
    Use semantic newlines
        In the source of a manual page,  new  sentences  should  be
        started  on new lines, and long sentences should split into
        lines at clause breaks (commas, semicolons, colons, and  so
        on).   This  convention,  sometimes known as "semantic new‐
        lines", makes it easier to see the effect of patches, which
        often  operate at the level of individual sentences or sen‐
        tence clauses.

> +before it gets removed.  The limit can take values ranging from 0
> +to 254; values 255 or higher behave the same as
> +.BR unlimited .
> +Limit values can be specified in either decimal or hexadecimal with a
> +"0x" prefix.  The special value
> +.B unlimited
> +is case-insensitive.  The default limit is 5.  A limit of 0 turns off the reloading
> +feature.  See NOTES below for further discussion of reloading.
>   .RE
>   .PP
>   .B paranoia
> @@ -128,6 +138,9 @@ in the specified cache for
>   is in seconds.
>   Larger values increase cache hit rates and reduce mean
>   response times, but increase problems with cache coherence.
> +Note that for some name services (including specifically DNS)
> +the TTL returned from the name service is used and this attribute
> +is ignored.
>   .RE
>   .PP
>   .B negative\-time\-to\-live
> @@ -166,6 +179,7 @@ The files are
>   .IR /etc/passwd ,
>   .IR /etc/group ,
>   .IR /etc/hosts ,
> +.IR /etc/resolv.conf ,
>   .IR /etc/services ,
>   and
>   .IR /etc/netgroup .
> @@ -194,6 +208,8 @@ is shared with the clients so
>   that they can directly search in them instead of having to ask the
>   daemon over the socket each time a lookup is performed.
>   The default is no.
> +Note that a cache miss will still result in asking the daemon over
> +the socket.
>   .RE
>   .PP
>   .B max\-db\-size
> @@ -230,12 +246,82 @@ and
>   .IR group .
>   .RE
>   .SH NOTES
> +.PP
>   The default values stated in this manual page originate
>   from the source code of
>   .BR nscd (8)
>   and are used if not overridden in the configuration file.
>   The default values used in the configuration file of
>   your distribution might differ.
> +.SS Reloading
> +.PP
> +.BR nscd (8)
> +has a feature called reloading whose behavior can be surprising.
> +.PP
> +Reloading is enabled when the
> +.B reload-count
> +attribute has a non-zero value.  The default value in the source
> +code enables reloading, although your distribution may differ.
> +.PP
> +When
> +reloading is enabled, positive cached entries (the results of
> +successful queries) do not simply expire when their TTL is up.  Instead,
> +at the expiry time
> +.B nscd
> +will "reload", i.e. re-issue the same name service query that created the cached
> +entry, to get a new value to cache.  Depending on
> +.B /etc/nsswitch.conf

Also from man-pages(7):

    Formatting conventions (general)
[...]

        Filenames  (whether  pathnames,  or  references  to  header
        files) are always in italics (e.g., <stdio.h>),  except  in
        the  SYNOPSIS  section,  where  included  files are in bold
        (e.g., #include <stdio.h>).  When referring to  a  standard
        header  file include, specify the header file surrounded by
        angle brackets, in the usual C way (e.g., <stdio.h>).


> +this may mean that a DNS, LDAP or NIS request is made.  If the new query
> +is successful reloading will repeat
> +when the new value would expire, until
> +.B reload-count
> +reloads have happened for the entry, and only then will it actually be removed
> +from the cache.  A request from a client which hits the entry will reset
> +the reload counter on the entry.  Purging the cache using the
> +.B \-i

Also from man-pages(7):

        Complete commands should, if long, be  written  as  an  in‐
        dented  line on their own, with a blank line before and af‐
        ter the command, for example

            man 7 man-pages

        If the command is short, then it can be included inline  in
        the  text,  in italic format, for example, man 7 man‐pages.
        In this case, it may  be  worth  using  nonbreaking  spaces
        ("\ ")  at suitable places in the command.  Command options
        should be written in italics (e.g., -l).


> +command line option overrides the reload logic and removes the entry.
> +.PP
> +Reloading has the effect of extending cache entry TTLs without compromising
> +on cache coherency, at the cost of additional load on the backing name service.
> +Whether this is a good idea on your system depends on details of
> +your applications' behavior, your name service, and the effective TTL values of
> +your cache entries.  (Note that for some name services (for example, DNS), the
> +effective TTL is the value returned from the name service and
> +.I not
> +the value of the
> +.B positive\-time\-to\-live
> +attribute.)  Please consider the following advice carefully:
> +.IP \(bu
> +If your application will make a second request for the same name, after
> +more then 1 TTL but before
> +.B reload\-count
> +TTLs, and is sensitive to the latency of a cache miss, then reloading may be
> +a good idea for you.
> +.IP \(bu
> +If your name service is configured to return very short TTLs, and your
> +applications only make requests rarely under normal circumstances, then
> +reloading may result in additional load on your backing name service
> +without any benefit to applications, which is probably a bad idea for you.
> +.IP \(bu
> +If your name service capacity is limited, reloading may have the
> +surprising effect of increasing load on your name service instead of
> +reducing it, and may be a bad idea for you.
> +.IP \(bu
> +Setting
> +.B reload\-count
> +to
> +.B unlimited
> +is almost never a good idea, as it will result in a cache that never expires
> +entries and puts never-ending additional load on the backing name service.
> +.PP
> +Note also that some distributions have an init script for nscd with a "reload"
> +command which has the effect of purging
> +.BR nscd 's
> +caches using the
> +.B \-i
> +commandline option.  That use of the word "reload" is
> +.I entirely different
> +from the "reloading" described here.
>   .SH SEE ALSO
>   .BR nscd (8)
>   .\" .SH AUTHOR
> 


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

nonbreaking spaces (was: [patch] nscd.conf.5: describe reloading, clarifications)

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 1627 bytes --]

Hi, Alex!

At 2021-07-28T22:31:26+0200, Alejandro Colomar (man-pages) wrote:
> Also from man-pages(7):
[...]
>        If the command is short, then it can be included inline  in
>        the  text,  in italic format, for example, man 7 man‐pages.
>        In this case, it may  be  worth  using  nonbreaking  spaces
>        ("\ ")  at suitable places in the command.  Command options
>        should be written in italics (e.g., -l).

I'd like to note that \~ is a superior escape sequence to use for this
purpose in most siutations.  The problem is that "\ " does, or rather
doesn't do, two things: it doesn't break and it doesn't adjust (that
is, it doesn't participate in widening when a line is justified to both
the left and right margins, a common typesetting practice).  It's also,
in my opinion, confusing to see and to write and speak about.

\~ is, admittedly, a groffism, but it is one that has been supported by
other actively maintained troff implementations and man page
rendererers.

Heirloom Doctools troff has supported it since its 2005-09-15
release[1].  mandoc has supported it since 2018-12-15[2], released
2019-03-10[3].

(Support in groff itself goes at least as far back as version 1.02, in
June 1991[4].)

What do you think about updating this guidance?

Regards,
Branden

[1] https://github.com/n-t-roff/heirloom-doctools/blob/master/CHANGES_GR#L1143
[2] https://cvsweb.bsd.lv/mandoc/mandoc.c.diff?r1=1.110&r2=1.111
[3] https://mandoc.bsd.lv/
[4] https://git.savannah.gnu.org/cgit/groff.git/tree/troff/input.c?id=351da0dcdf702cf243d26ffa998961bce2aa8653#n1270

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: nonbreaking spaces (was: [patch] nscd.conf.5: describe reloading, clarifications)

[Alejandro Colomar (man-pages)]

Hi Branden!

On 7/29/21 1:55 PM, G. Branden Robinson wrote:
> Hi, Alex!
> 
> At 2021-07-28T22:31:26+0200, Alejandro Colomar (man-pages) wrote:
>> Also from man-pages(7):
> [...]
>>         If the command is short, then it can be included inline  in
>>         the  text,  in italic format, for example, man 7 man‐pages.
>>         In this case, it may  be  worth  using  nonbreaking  spaces
>>         ("\ ")  at suitable places in the command.  Command options
>>         should be written in italics (e.g., -l).
> 
> I'd like to note that \~ is a superior escape sequence to use for this
> purpose in most siutations.  The problem is that "\ " does, or rather
> doesn't do, two things: it doesn't break and it doesn't adjust (that
> is, it doesn't participate in widening when a line is justified to both
> the left and right margins, a common typesetting practice).

Can you provide some examples of rendered output with '\ ' and '\~'?
I think I understand it, but a graphical example might be better.

>  It's also,
> in my opinion, confusing to see and to write and speak about.

I'm not sure I understood this sentence :)

> 
> \~ is, admittedly, a groffism, but it is one that has been supported by
> other actively maintained troff implementations and man page
> rendererers.
> 
> Heirloom Doctools troff has supported it since its 2005-09-15
> release[1].  mandoc has supported it since 2018-12-15[2], released
> 2019-03-10[3].
> 
> (Support in groff itself goes at least as far back as version 1.02, in
> June 1991[4].)

Support looks good.

> 
> What do you think about updating this guidance?

I'm not sure I understood the difference completely,
I'll comment about it when you provide some examples.

Kind regards,

Alex

> 
> Regards,
> Branden
> 
> [1] https://github.com/n-t-roff/heirloom-doctools/blob/master/CHANGES_GR#L1143
> [2] https://cvsweb.bsd.lv/mandoc/mandoc.c.diff?r1=1.110&r2=1.111
> [3] https://mandoc.bsd.lv/
> [4] https://git.savannah.gnu.org/cgit/groff.git/tree/troff/input.c?id=351da0dcdf702cf243d26ffa998961bce2aa8653#n1270
> 


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: nonbreaking spaces (was: [patch] nscd.conf.5: describe reloading, clarifications)

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 2286 bytes --]

Hi, Alex!

At 2021-07-29T14:18:30+0200, Alejandro Colomar (man-pages) wrote:
> On 7/29/21 1:55 PM, G. Branden Robinson wrote:
> Can you provide some examples of rendered output with '\ ' and '\~'?
> I think I understand it, but a graphical example might be better.

Sure.  Here you go.

[[
demo(1)                     General Commands Manual                    demo(1)

Name
       demo - an illustration

Description
       Observe  the  distinction  between the handling of the “\ ” (backslash-
       space) and \^ (backslash-tilde) escapes.

       Today I was troubleshooting a segmentation fault and  had  occasion  to
       run    the    “ps -fC troff”    command.     I    also   had   to   run
       “gdb  ./build/troff  ./build/core”.   Here  is  some   filler:   XXXXXX
       Mandatory  for  this  illustration  is the filling and adjusting of the
       previous line.

nonce 1.0                         2021-07-29                           demo(1)
]]

In the foregoing, the spaces in "ps -fC troff" do not participate in
adjustment, which leads to somewhat jarringly large inter-word gaps on
the rest of the line.

> > It's also, in my opinion, confusing to see and to write and speak
> > about.
> 
> I'm not sure I understood this sentence :)

I mean that it "\ " can be difficult to recognize in practice; you
_have_ to quote it or describe it somehow or the syntactically
significant space (to roff) gets lots among the regular word-separating
spaces in prose.

> I'm not sure I understood the difference completely, I'll comment
> about it when you provide some examples.

Sure.  I hope the above helps.  Here's the source of the example.

.TH demo 1 2021-07-29 "nonce 1.0"
.SH Name
demo \- an illustration
.SH Description
Observe the distinction between the handling of the
.RB \[lq] \[rs]\~ \[rq]
(backslash-space) and
.B \[rs]\[ha]
(backslash-tilde) escapes.
.P
Today I was troubleshooting a segmentation fault and had occasion to run
the
.RB \[lq] ps\ -fC\ troff \[rq]
command.
I also had to run
.RB \[lq] gdb\~./build/troff\~./build/core \[rq].
.
Here is some filler:
XXXXXX
\%Mandatory for this illustration is the filling and adjusting of the
previous line.

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: nonbreaking spaces (was: [patch] nscd.conf.5: describe reloading, clarifications)

[Alejandro Colomar (man-pages)]

On 7/29/21 3:58 PM, G. Branden Robinson wrote:
> Hi, Alex!
> 
> At 2021-07-29T14:18:30+0200, Alejandro Colomar (man-pages) wrote:
>> On 7/29/21 1:55 PM, G. Branden Robinson wrote:
>> Can you provide some examples of rendered output with '\ ' and '\~'?
>> I think I understand it, but a graphical example might be better.
> 
> Sure.  Here you go.
> 
> [[
> demo(1)                     General Commands Manual                    demo(1)
> 
> Name
>         demo - an illustration
> 
> Description
>         Observe  the  distinction  between the handling of the “\ ” (backslash-
>         space) and \^ (backslash-tilde) escapes.

I guess \^ is just a typo and you meant here \~.

> 
>         Today I was troubleshooting a segmentation fault and  had  occasion  to
>         run    the    “ps -fC troff”    command.     I    also   had   to   run
>         “gdb  ./build/troff  ./build/core”.   Here  is  some   filler:   XXXXXX
>         Mandatory  for  this  illustration  is the filling and adjusting of the
>         previous line.
> 
> nonce 1.0                         2021-07-29                           demo(1)
> ]]

Yes, that's what I thought you were saying.  Thanks for confirming.

> 
> In the foregoing, the spaces in "ps -fC troff" do not participate in
> adjustment, which leads to somewhat jarringly large inter-word gaps on
> the rest of the line.
> 
>>> It's also, in my opinion, confusing to see and to write and speak
>>> about.
>>
>> I'm not sure I understood this sentence :)
> 
> I mean that it "\ " can be difficult to recognize in practice; you
> _have_ to quote it or describe it somehow or the syntactically
> significant space (to roff) gets lots among the regular word-separating
> spaces in prose.

Got it now.

> 
>> I'm not sure I understood the difference completely, I'll comment
>> about it when you provide some examples.
> 
> Sure.  I hope the above helps.  Here's the source of the example.

Yes.  Well, before seeing the example above, I thought that I preferred 
having a single space inside commands, as then the command itself is a 
bit more readable.  But since that slight increase in readability can 
come with a considerable decrease in readability of the surrounding 
text, I'm going to accept your proposal.

Would you mind sending a patch for man-pages(7)? :)

Thanks!

Alex

> 
> .TH demo 1 2021-07-29 "nonce 1.0"
> .SH Name
> demo \- an illustration
> .SH Description
> Observe the distinction between the handling of the
> .RB \[lq] \[rs]\~ \[rq]
> (backslash-space) and
> .B \[rs]\[ha]
> (backslash-tilde) escapes.
> .P
> Today I was troubleshooting a segmentation fault and had occasion to run
> the
> .RB \[lq] ps\ -fC\ troff \[rq]
> command.
> I also had to run
> .RB \[lq] gdb\~./build/troff\~./build/core \[rq].
> .
> Here is some filler:
> XXXXXX
> \%Mandatory for this illustration is the filling and adjusting of the
> previous line.
> 
> Regards,
> Branden
> 


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [patch] nscd.conf.5: describe reloading, clarifications

[Alejandro Colomar (man-pages)]

On 8/3/21 2:19 AM, Greg Banks wrote:
> ​Thanks Alejandro,
> 
> Here's v2 of the patch with your feedback applied.


Hi Greg,

Sorry, but the patch does not apply (see below).
Could you please fix it?

Thanks,

Alex

$ git am patches/recv/Re\:\ \[patch\]\ nscd.conf.5\:\ describe\ 
reloading\,\ clarifications.eml
warning: quoted CRLF detected
warning: quoted CRLF detected
Applying: nscd.conf.5: describe reloading, clarifications
error: patch failed: man5/nscd.conf.5:1
error: man5/nscd.conf.5: patch does not apply
Patch failed at 0001 nscd.conf.5: describe reloading, clarifications
hint: Use 'git am --show-current-patch=diff' to see the failed patch
When you have resolved this problem, run "git am --continue".
If you prefer to skip this patch, run "git am --skip" instead.
To restore the original branch and stop patching, run "git am --abort".


> 
> 
> 
> - Added a subsection of NOTES describing nscd's reloading behavior
>    and providing advice on how to configure it.
> - Clarifications for the threads, reload-count, positive-time-to-live,
>    check-files, and shared attributes.
> 
> Derived by reading the nscd, libresolv and glibc source and some painful 
> experience.
> 
> v2: review feedback
> 
> diff --git a/man5/nscd.conf.5 b/man5/nscd.conf.5
> index 7356bf7c2..a5c5e7bc3 100644
> --- a/man5/nscd.conf.5
> +++ b/man5/nscd.conf.5
> @@ -1,5 +1,6 @@
>   .\" Copyright (c) 1999, 2000 SuSE GmbH Nuernberg, Germany
>   .\" Author: Thorsten Kukuk <kukuk@suse.de>
> +.\" Updates by Greg Banks <gbanks@linkedin.com> Copyright (c) 2021 
> Microsoft Corp.
>   .\"
>   .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
>   .\" This program is free software; you can redistribute it and/or
> @@ -53,9 +54,12 @@ The default is 0.
>   .B threads
>   .I number
>   .RS
> -This is the number of threads that are started to wait for
> +This is the initial number of threads that are started to wait for
>   requests.
>   At least five threads will always be created.
> +The number of threads may increase dynamically up to
> +.B max\-threads
> +in response to demand from clients, but never decreases.
>   .RE
>   .PP
>   .B max\-threads
> @@ -83,9 +87,18 @@ Specifies the user who is allowed to request statistics.
>   unlimited |
>   .I number
>   .RS
> -Limit on the number of times a cached entry gets reloaded without being 
> used
> +Sets a limit on the number of times a cached entry gets reloaded 
> without being used
>   before it gets removed.
> -The default is 5.
> +The limit can take values ranging from 0 to 254;
> +values 255 or higher behave the same as
> +.BR unlimited .
> +Limit values can be specified in either decimal or hexadecimal with a 
> "0x" prefix.
> +The special value
> +.B unlimited
> +is case-insensitive.
> +The default limit is 5.
> +A limit of 0 turns off the reloading feature.
> +See NOTES below for further discussion of reloading.
>   .RE
>   .PP
>   .B paranoia
> @@ -128,6 +141,9 @@ in the specified cache for
>   is in seconds.
>   Larger values increase cache hit rates and reduce mean
>   response times, but increase problems with cache coherence.
> +Note that for some name services (including specifically DNS)
> +the TTL returned from the name service is used and this attribute
> +is ignored.
>   .RE
>   .PP
>   .B negative\-time\-to\-live
> @@ -166,6 +182,7 @@ The files are
>   .IR /etc/passwd ,
>   .IR /etc/group ,
>   .IR /etc/hosts ,
> +.IR /etc/resolv.conf ,
>   .IR /etc/services ,
>   and
>   .IR /etc/netgroup .
> @@ -194,6 +211,8 @@ is shared with the clients so
>   that they can directly search in them instead of having to ask the
>   daemon over the socket each time a lookup is performed.
>   The default is no.
> +Note that a cache miss will still result in asking the daemon over
> +the socket.
>   .RE
>   .PP
>   .B max\-db\-size
> @@ -230,12 +249,88 @@ and
>   .IR group .
>   .RE
>   .SH NOTES
> +.PP
>   The default values stated in this manual page originate
>   from the source code of
>   .BR nscd (8)
>   and are used if not overridden in the configuration file.
>   The default values used in the configuration file of
>   your distribution might differ.
> +.SS Reloading
> +.PP
> +.BR nscd (8)
> +has a feature called reloading whose behavior can be surprising.
> +.PP
> +Reloading is enabled when the
> +.B reload-count
> +attribute has a non-zero value.
> +The default value in the source code enables reloading, although your 
> distribution may differ.
> +.PP
> +When reloading is enabled, positive cached entries (the results of
> +successful queries) do not simply expire when their TTL is up.
> +Instead, at the expiry time
> +.B nscd
> +will "reload", i.e. re-issue the same name service query that created 
> the cached
> +entry, to get a new value to cache.
> +Depending on
> +.I /etc/nsswitch.conf
> +this may mean that a DNS, LDAP or NIS request is made.
> +If the new query is successful reloading will repeat when the new value 
> would expire, until
> +.B reload-count
> +reloads have happened for the entry, and only then will it actually be 
> removed
> +from the cache.
> +A request from a client which hits the entry will reset the reload 
> counter on the entry.
> +Purging the cache using
> +.I nscd\ -i
> +overrides the reload logic and removes the entry.
> +.PP
> +Reloading has the effect of extending cache entry TTLs without compromising
> +on cache coherency, at the cost of additional load on the backing name 
> service.
> +Whether this is a good idea on your system depends on details of
> +your applications' behavior, your name service, and the effective TTL 
> values of
> +your cache entries.
> +(Note that for some name services (for example, DNS), the
> +effective TTL is the value returned from the name service and
> +.I not
> +the value of the
> +.B positive\-time\-to\-live
> +attribute.)
> +Please consider the following advice carefully:
> +.IP \(bu
> +If your application will make a second request for the same name,
> +after more then 1 TTL but before
> +.B reload\-count
> +TTLs,
> +and is sensitive to the latency of a cache miss,
> +then reloading may be a good idea for you.
> +.IP \(bu
> +If your name service is configured to return very short TTLs,
> +and your applications only make requests rarely under normal circumstances,
> +then reloading may result in additional load on your backing name service
> +without any benefit to applications,
> +which is probably a bad idea for you.
> +.IP \(bu
> +If your name service capacity is limited,
> +reloading may have the surprising effect of increasing load on your name
> +service instead of reducing it,
> +and may be a bad idea for you.
> +.IP \(bu
> +Setting
> +.B reload\-count
> +to
> +.B unlimited
> +is almost never a good idea,
> +as it will result in a cache that never expires entries and puts 
> never-ending
> +additional load on the backing name service.
> +.PP
> +Some distributions have an init script for
> +.BR nscd (8)
> +with a
> +.I reload
> +command which uses
> +.I nscd\ -i
> +to purge the cache.
> +That use of the word "reload" is entirely different from the 
> "reloading" described here.
>   .SH SEE ALSO
>   .BR nscd (8)
>   .\" .SH AUTHOR
> 
> ------------------------------------------------------------------------
> *From:* Alejandro Colomar (man-pages) <alx.manpages@gmail.com>
> *Sent:* Wednesday, July 28, 2021 16:31
> *To:* Greg Banks <gbanks@linkedin.com>
> *Cc:* Michael Kerrisk <mtk.manpages@gmail.com>; 
> libc-alpha@sourceware.org <libc-alpha@sourceware.org>; Petr Baudis 
> <pasky@suse.cz>; DJ Delorie <dj@redhat.com>; linux-man@vger.kernel.org 
> <linux-man@vger.kernel.org>
> *Subject:* Re: [patch] nscd.conf.5: describe reloading, clarifications
> Hello Greg,
> 
> On 7/28/21 12:09 AM, Greg Banks wrote:
>> - Added a subsection of NOTES describing nscd's reloading behavior
>>    and providing advice on how to configure it.
>> - Clarifications for the threads, reload-count, positive-time-to-live,
>>    check-files, and shared attributes.
>> 
>> Derived by reading the nscd, libresolv and glibc source and some painful experience.
> 
> Thanks for the patch.
> 
> Please see some comments below.
> 
> Thanks,
> 
> Alex
> 
>> 
>> diff --git a/man5/nscd.conf.5 b/man5/nscd.conf.5
>> index 7356bf7c2..52f7051d5 100644
>> --- a/man5/nscd.conf.5
>> +++ b/man5/nscd.conf.5
>> @@ -1,5 +1,6 @@
>>   .\" Copyright (c) 1999, 2000 SuSE GmbH Nuernberg, Germany
>>   .\" Author: Thorsten Kukuk <kukuk@suse.de>
>> +.\" Updates by Greg Banks <gbanks@linkedin.com> Copyright (c) 2021 Microsoft Corp.
>>   .\"
>>   .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
>>   .\" This program is free software; you can redistribute it and/or
>> @@ -53,9 +54,12 @@ The default is 0.
>>   .B threads
>>   .I number
>>   .RS
>> -This is the number of threads that are started to wait for
>> +This is the initial number of threads that are started to wait for
>>   requests.
>> -At least five threads will always be created.
>> +At least five threads will always be created.  The number of threads
>> +may increase dynamically up to
>> +.B max\-threads
>> +in response to demand from clients, but never decreases.
>>   .RE
>>   .PP
>>   .B max\-threads
>> @@ -83,9 +87,15 @@ Specifies the user who is allowed to request statistics.
>>   unlimited |
>>   .I number
>>   .RS
>> -Limit on the number of times a cached entry gets reloaded without being used
>> -before it gets removed.
>> -The default is 5.
>> +Sets a limit on the number of times a cached entry gets reloaded without being used
> 
> 
> See the following extract from man-pages(7):
> 
> $ man 7 man-pages | sed -n '/Use semantic newlines/,/^$/p';
>      Use semantic newlines
>          In the source of a manual page,  new  sentences  should  be
>          started  on new lines, and long sentences should split into
>          lines at clause breaks (commas, semicolons, colons, and  so
>          on).   This  convention,  sometimes known as "semantic new‐
>          lines", makes it easier to see the effect of patches, which
>          often  operate at the level of individual sentences or sen‐
>          tence clauses.
> 
>> +before it gets removed.  The limit can take values ranging from 0
>> +to 254; values 255 or higher behave the same as
>> +.BR unlimited .
>> +Limit values can be specified in either decimal or hexadecimal with a
>> +"0x" prefix.  The special value
>> +.B unlimited
>> +is case-insensitive.  The default limit is 5.  A limit of 0 turns off the reloading
>> +feature.  See NOTES below for further discussion of reloading.
>>   .RE
>>   .PP
>>   .B paranoia
>> @@ -128,6 +138,9 @@ in the specified cache for
>>   is in seconds.
>>   Larger values increase cache hit rates and reduce mean
>>   response times, but increase problems with cache coherence.
>> +Note that for some name services (including specifically DNS)
>> +the TTL returned from the name service is used and this attribute
>> +is ignored.
>>   .RE
>>   .PP
>>   .B negative\-time\-to\-live
>> @@ -166,6 +179,7 @@ The files are
>>   .IR /etc/passwd ,
>>   .IR /etc/group ,
>>   .IR /etc/hosts ,
>> +.IR /etc/resolv.conf ,
>>   .IR /etc/services ,
>>   and
>>   .IR /etc/netgroup .
>> @@ -194,6 +208,8 @@ is shared with the clients so
>>   that they can directly search in them instead of having to ask the
>>   daemon over the socket each time a lookup is performed.
>>   The default is no.
>> +Note that a cache miss will still result in asking the daemon over
>> +the socket.
>>   .RE
>>   .PP
>>   .B max\-db\-size
>> @@ -230,12 +246,82 @@ and
>>   .IR group .
>>   .RE
>>   .SH NOTES
>> +.PP
>>   The default values stated in this manual page originate
>>   from the source code of
>>   .BR nscd (8)
>>   and are used if not overridden in the configuration file.
>>   The default values used in the configuration file of
>>   your distribution might differ.
>> +.SS Reloading
>> +.PP
>> +.BR nscd (8)
>> +has a feature called reloading whose behavior can be surprising.
>> +.PP
>> +Reloading is enabled when the
>> +.B reload-count
>> +attribute has a non-zero value.  The default value in the source
>> +code enables reloading, although your distribution may differ.
>> +.PP
>> +When
>> +reloading is enabled, positive cached entries (the results of
>> +successful queries) do not simply expire when their TTL is up.  Instead,
>> +at the expiry time
>> +.B nscd
>> +will "reload", i.e. re-issue the same name service query that created the cached
>> +entry, to get a new value to cache.  Depending on
>> +.B /etc/nsswitch.conf
> 
> Also from man-pages(7):
> 
>      Formatting conventions (general)
> [...]
> 
>          Filenames  (whether  pathnames,  or  references  to  header
>          files) are always in italics (e.g., <stdio.h>),  except  in
>          the  SYNOPSIS  section,  where  included  files are in bold
>          (e.g., #include <stdio.h>).  When referring to  a  standard
>          header  file include, specify the header file surrounded by
>          angle brackets, in the usual C way (e.g., <stdio.h>).
> 
> 
>> +this may mean that a DNS, LDAP or NIS request is made.  If the new query
>> +is successful reloading will repeat
>> +when the new value would expire, until
>> +.B reload-count
>> +reloads have happened for the entry, and only then will it actually be removed
>> +from the cache.  A request from a client which hits the entry will reset
>> +the reload counter on the entry.  Purging the cache using the
>> +.B \-i
> 
> Also from man-pages(7):
> 
>          Complete commands should, if long, be  written  as  an  in‐
>          dented  line on their own, with a blank line before and af‐
>          ter the command, for example
> 
>              man 7 man-pages
> 
>          If the command is short, then it can be included inline  in
>          the  text,  in italic format, for example, man 7 man‐pages.
>          In this case, it may  be  worth  using  nonbreaking  spaces
>          ("\ ")  at suitable places in the command.  Command options
>          should be written in italics (e.g., -l).
> 
> 
>> +command line option overrides the reload logic and removes the entry.
>> +.PP
>> +Reloading has the effect of extending cache entry TTLs without compromising
>> +on cache coherency, at the cost of additional load on the backing name service.
>> +Whether this is a good idea on your system depends on details of
>> +your applications' behavior, your name service, and the effective TTL values of
>> +your cache entries.  (Note that for some name services (for example, DNS), the
>> +effective TTL is the value returned from the name service and
>> +.I not
>> +the value of the
>> +.B positive\-time\-to\-live
>> +attribute.)  Please consider the following advice carefully:
>> +.IP \(bu
>> +If your application will make a second request for the same name, after
>> +more then 1 TTL but before
>> +.B reload\-count
>> +TTLs, and is sensitive to the latency of a cache miss, then reloading may be
>> +a good idea for you.
>> +.IP \(bu
>> +If your name service is configured to return very short TTLs, and your
>> +applications only make requests rarely under normal circumstances, then
>> +reloading may result in additional load on your backing name service
>> +without any benefit to applications, which is probably a bad idea for you.
>> +.IP \(bu
>> +If your name service capacity is limited, reloading may have the
>> +surprising effect of increasing load on your name service instead of
>> +reducing it, and may be a bad idea for you.
>> +.IP \(bu
>> +Setting
>> +.B reload\-count
>> +to
>> +.B unlimited
>> +is almost never a good idea, as it will result in a cache that never expires
>> +entries and puts never-ending additional load on the backing name service.
>> +.PP
>> +Note also that some distributions have an init script for nscd with a "reload"
>> +command which has the effect of purging
>> +.BR nscd 's
>> +caches using the
>> +.B \-i
>> +commandline option.  That use of the word "reload" is
>> +.I entirely different
>> +from the "reloading" described here.
>>   .SH SEE ALSO
>>   .BR nscd (8)
>>   .\" .SH AUTHOR
>> 
> 
> 
> -- 
> Alejandro Colomar
> Linux man-pages comaintainer; 
> https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.kernel.org%2Fdoc%2Fman-pages%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C8af3ff31ed6546255b1c08d95206af85%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637631010951616695%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=fxB1Fv38SNeZOf42yE1ZCLVfJVBi8RtvSC7loYLLKC4%3D&amp;reserved=0 
> <https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.kernel.org%2Fdoc%2Fman-pages%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C8af3ff31ed6546255b1c08d95206af85%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637631010951616695%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=fxB1Fv38SNeZOf42yE1ZCLVfJVBi8RtvSC7loYLLKC4%3D&amp;reserved=0>
> https://nam06.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.alejandro-colomar.es%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C8af3ff31ed6546255b1c08d95206af85%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637631010951616695%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=gPrruohuthTCDA%2FW%2BR%2FgI2IWl2PEsZbXNk99Ax3pp38%3D&amp;reserved=0 
> <https://nam06.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.alejandro-colomar.es%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C8af3ff31ed6546255b1c08d95206af85%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637631010951616695%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=gPrruohuthTCDA%2FW%2BR%2FgI2IWl2PEsZbXNk99Ax3pp38%3D&amp;reserved=0>


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [patch] nscd.conf.5: describe reloading, clarifications

[Alejandro Colomar (man-pages)]

Hi Greg,

On 8/3/21 4:17 PM, Greg Banks wrote:
> Hi Alejandro,
> 
> I think you're a victim of the git bug described in 
> https://bugzilla.redhat.com/show_bug.cgi?id=1469098 
> <https://bugzilla.redhat.com/show_bug.cgi?id=1469098>  where git gets 
> confused about whitespace when decoding base64 encoded message bodies.  
> The workarounds are to use "git am --ignore-whitespace", or to manually 
> decode the base64 and adjust the MIME headers. I don't know of any way 
> to control the transfer encoding from this mail client, sorry.  FYI my 
> mail client has also "helpfully" stuck an annoying but harmless Unicode 
> U+200B ZERO WIDTH SPACE character at the start of the message.

Thanks for that info, it worked.

But, it has CRLF (Windows) endings, and v2 didn't reach the mailing list 
(but v1 did).  And v1 didn't have CRLF endings.  Could you please use 
the same method you used for sending v1 to send an v3?
Also, please see some comments below.

Thanks,

Alex

> 
> Greg.
> ------------------------------------------------------------------------
> *From:* Alejandro Colomar (man-pages) <alx.manpages@gmail.com>
> *Sent:* Tuesday, August 3, 2021 04:08
> *To:* Greg Banks <gbanks@linkedin.com>
> *Cc:* Michael Kerrisk <mtk.manpages@gmail.com>; 
> libc-alpha@sourceware.org <libc-alpha@sourceware.org>; Petr Baudis 
> <pasky@suse.cz>; DJ Delorie <dj@redhat.com>; linux-man@vger.kernel.org 
> <linux-man@vger.kernel.org>
> *Subject:* Re: [patch] nscd.conf.5: describe reloading, clarifications
> On 8/3/21 2:19 AM, Greg Banks wrote:
>> ​Thanks Alejandro,
>> 
>> Here's v2 of the patch with your feedback applied.
> 
> 
> Hi Greg,
> 
> Sorry, but the patch does not apply (see below).
> Could you please fix it?
> 
> Thanks,
> 
> Alex
> 
> $ git am patches/recv/Re\:\ \[patch\]\ nscd.conf.5\:\ describe\
> reloading\,\ clarifications.eml
> warning: quoted CRLF detected
> warning: quoted CRLF detected
> Applying: nscd.conf.5: describe reloading, clarifications
> error: patch failed: man5/nscd.conf.5:1
> error: man5/nscd.conf.5: patch does not apply
> Patch failed at 0001 nscd.conf.5: describe reloading, clarifications
> hint: Use 'git am --show-current-patch=diff' to see the failed patch
> When you have resolved this problem, run "git am --continue".
> If you prefer to skip this patch, run "git am --skip" instead.
> To restore the original branch and stop patching, run "git am --abort".
> 
> 
>> 
>> 
>> 
>> - Added a subsection of NOTES describing nscd's reloading behavior
>>    and providing advice on how to configure it.
>> - Clarifications for the threads, reload-count, positive-time-to-live,
>>    check-files, and shared attributes.
>> 
>> Derived by reading the nscd, libresolv and glibc source and some painful 
>> experience.
>> 
>> v2: review feedback
>> 
>> diff --git a/man5/nscd.conf.5 b/man5/nscd.conf.5
>> index 7356bf7c2..a5c5e7bc3 100644
>> --- a/man5/nscd.conf.5
>> +++ b/man5/nscd.conf.5
>> @@ -1,5 +1,6 @@
>>   .\" Copyright (c) 1999, 2000 SuSE GmbH Nuernberg, Germany
>>   .\" Author: Thorsten Kukuk <kukuk@suse.de>
>> +.\" Updates by Greg Banks <gbanks@linkedin.com> Copyright (c) 2021 
>> Microsoft Corp.
>>   .\"
>>   .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
>>   .\" This program is free software; you can redistribute it and/or
>> @@ -53,9 +54,12 @@ The default is 0.
>>   .B threads
>>   .I number
>>   .RS
>> -This is the number of threads that are started to wait for
>> +This is the initial number of threads that are started to wait for
>>   requests.
>>   At least five threads will always be created.
>> +The number of threads may increase dynamically up to
>> +.B max\-threads
>> +in response to demand from clients, but never decreases.
>>   .RE
>>   .PP
>>   .B max\-threads
>> @@ -83,9 +87,18 @@ Specifies the user who is allowed to request statistics.
>>   unlimited |
>>   .I number
>>   .RS
>> -Limit on the number of times a cached entry gets reloaded without being 
>> used
>> +Sets a limit on the number of times a cached entry gets reloaded 
>> without being used
>>   before it gets removed.
>> -The default is 5.
>> +The limit can take values ranging from 0 to 254;
>> +values 255 or higher behave the same as
>> +.BR unlimited .
>> +Limit values can be specified in either decimal or hexadecimal with a 
>> "0x" prefix.
>> +The special value
>> +.B unlimited
>> +is case-insensitive.
>> +The default limit is 5.
>> +A limit of 0 turns off the reloading feature.
>> +See NOTES below for further discussion of reloading.
>>   .RE
>>   .PP
>>   .B paranoia
>> @@ -128,6 +141,9 @@ in the specified cache for
>>   is in seconds.
>>   Larger values increase cache hit rates and reduce mean
>>   response times, but increase problems with cache coherence.
>> +Note that for some name services (including specifically DNS)
>> +the TTL returned from the name service is used and this attribute

Break just before (or after) "and" instead.

>> +is ignored.
>>   .RE
>>   .PP
>>   .B negative\-time\-to\-live
>> @@ -166,6 +182,7 @@ The files are
>>   .IR /etc/passwd ,
>>   .IR /etc/group ,
>>   .IR /etc/hosts ,
>> +.IR /etc/resolv.conf ,
>>   .IR /etc/services ,
>>   and
>>   .IR /etc/netgroup .
>> @@ -194,6 +211,8 @@ is shared with the clients so
>>   that they can directly search in them instead of having to ask the
>>   daemon over the socket each time a lookup is performed.
>>   The default is no.
>> +Note that a cache miss will still result in asking the daemon over

Break just after "in"

>> +the socket.
>>   .RE
>>   .PP
>>   .B max\-db\-size
>> @@ -230,12 +249,88 @@ and
>>   .IR group .
>>   .RE
>>   .SH NOTES
>> +.PP

That's not correct.  Did you copy that from another place?  If so, 
please tell me because I should fix it.

We use that between paragraphs, but not before the first one nor after 
the last one.

>>   The default values stated in this manual page originate
>>   from the source code of
>>   .BR nscd (8)
>>   and are used if not overridden in the configuration file.
>>   The default values used in the configuration file of
>>   your distribution might differ.
>> +.SS Reloading
>> +.PP

Nope.  Same reasons.

>> +.BR nscd (8)
>> +has a feature called reloading whose behavior can be surprising.
>> +.PP
>> +Reloading is enabled when the
>> +.B reload-count
>> +attribute has a non-zero value.
>> +The default value in the source code enables reloading, although your 

Break at the ',' instead.

>> distribution may differ.
>> +.PP
>> +When reloading is enabled, positive cached entries (the results of

idem.

>> +successful queries) do not simply expire when their TTL is up.

Break after ')'.

>> +Instead, at the expiry time
>> +.B nscd
>> +will "reload", i.e. re-issue the same name service query that created 
>> the cached
>> +entry, to get a new value to cache.

Break at the commas above.

>> +Depending on
>> +.I /etc/nsswitch.conf
>> +this may mean that a DNS, LDAP or NIS request is made.

Use a comma before "or" (Oxford comma).

>> +If the new query is successful reloading will repeat when the new value 

s/successful/successful,/

>> would expire, until

Break at the ',' instead.

>> +.B reload-count
>> +reloads have happened for the entry, and only then will it actually be 

idem.

>> removed
>> +from the cache.
>> +A request from a client which hits the entry will reset the reload 
>> counter on the entry.
>> +Purging the cache using
>> +.I nscd\ -i

Please, use \~ instead of "\ ".  (I know man-pages(7) recommends "\ ", 
but we're about to change that).

>> +overrides the reload logic and removes the entry.
>> +.PP
>> +Reloading has the effect of extending cache entry TTLs without compromising
>> +on cache coherency, at the cost of additional load on the backing name 
>> service.

In general, break at commas instead of random places.
The following regex should rarely match:

[,;:.] \+\w

>> +Whether this is a good idea on your system depends on details of
>> +your applications' behavior, your name service, and the effective TTL 
>> values of
>> +your cache entries.
>> +(Note that for some name services (for example, DNS), the
>> +effective TTL is the value returned from the name service and
>> +.I not
>> +the value of the
>> +.B positive\-time\-to\-live



>> +attribute.)
>> +Please consider the following advice carefully:
>> +.IP \(bu
>> +If your application will make a second request for the same name,
>> +after more then 1 TTL but before
>> +.B reload\-count
>> +TTLs,
>> +and is sensitive to the latency of a cache miss,
>> +then reloading may be a good idea for you.
>> +.IP \(bu
>> +If your name service is configured to return very short TTLs,
>> +and your applications only make requests rarely under normal circumstances,
>> +then reloading may result in additional load on your backing name service
>> +without any benefit to applications,
>> +which is probably a bad idea for you.
>> +.IP \(bu
>> +If your name service capacity is limited,
>> +reloading may have the surprising effect of increasing load on your name
>> +service instead of reducing it,
>> +and may be a bad idea for you.
>> +.IP \(bu
>> +Setting
>> +.B reload\-count
>> +to
>> +.B unlimited
>> +is almost never a good idea,
>> +as it will result in a cache that never expires entries and puts 
>> never-ending
>> +additional load on the backing name service.
>> +.PP
>> +Some distributions have an init script for
>> +.BR nscd (8)
>> +with a
>> +.I reload
>> +command which uses
>> +.I nscd\ -i

\~

>> +to purge the cache.
>> +That use of the word "reload" is entirely different from the 
>> "reloading" described here.
>>   .SH SEE ALSO
>>   .BR nscd (8)
>>   .\" .SH AUTHOR
>> 
>> ------------------------------------------------------------------------
>> *From:* Alejandro Colomar (man-pages) <alx.manpages@gmail.com>
>> *Sent:* Wednesday, July 28, 2021 16:31
>> *To:* Greg Banks <gbanks@linkedin.com>
>> *Cc:* Michael Kerrisk <mtk.manpages@gmail.com>; 
>> libc-alpha@sourceware.org <libc-alpha@sourceware.org>; Petr Baudis 
>> <pasky@suse.cz>; DJ Delorie <dj@redhat.com>; linux-man@vger.kernel.org 
>> <linux-man@vger.kernel.org>
>> *Subject:* Re: [patch] nscd.conf.5: describe reloading, clarifications
>> Hello Greg,
>> 
>> On 7/28/21 12:09 AM, Greg Banks wrote:
>>> - Added a subsection of NOTES describing nscd's reloading behavior
>>>    and providing advice on how to configure it.
>>> - Clarifications for the threads, reload-count, positive-time-to-live,
>>>    check-files, and shared attributes.
>>> 
>>> Derived by reading the nscd, libresolv and glibc source and some painful experience.
>> 
>> Thanks for the patch.
>> 
>> Please see some comments below.
>> 
>> Thanks,
>> 
>> Alex
>> 
>>> 
>>> diff --git a/man5/nscd.conf.5 b/man5/nscd.conf.5
>>> index 7356bf7c2..52f7051d5 100644
>>> --- a/man5/nscd.conf.5
>>> +++ b/man5/nscd.conf.5
>>> @@ -1,5 +1,6 @@
>>>   .\" Copyright (c) 1999, 2000 SuSE GmbH Nuernberg, Germany
>>>   .\" Author: Thorsten Kukuk <kukuk@suse.de>
>>> +.\" Updates by Greg Banks <gbanks@linkedin.com> Copyright (c) 2021 Microsoft Corp.
>>>   .\"
>>>   .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
>>>   .\" This program is free software; you can redistribute it and/or
>>> @@ -53,9 +54,12 @@ The default is 0.
>>>   .B threads
>>>   .I number
>>>   .RS
>>> -This is the number of threads that are started to wait for
>>> +This is the initial number of threads that are started to wait for
>>>   requests.
>>> -At least five threads will always be created.
>>> +At least five threads will always be created.  The number of threads
>>> +may increase dynamically up to
>>> +.B max\-threads
>>> +in response to demand from clients, but never decreases.
>>>   .RE
>>>   .PP
>>>   .B max\-threads
>>> @@ -83,9 +87,15 @@ Specifies the user who is allowed to request statistics.
>>>   unlimited |
>>>   .I number
>>>   .RS
>>> -Limit on the number of times a cached entry gets reloaded without being used
>>> -before it gets removed.
>>> -The default is 5.
>>> +Sets a limit on the number of times a cached entry gets reloaded without being used
>> 
>> 
>> See the following extract from man-pages(7):
>> 
>> $ man 7 man-pages | sed -n '/Use semantic newlines/,/^$/p';
>>      Use semantic newlines
>>          In the source of a manual page,  new  sentences  should  be
>>          started  on new lines, and long sentences should split into
>>          lines at clause breaks (commas, semicolons, colons, and  so
>>          on).   This  convention,  sometimes known as "semantic new‐
>>          lines", makes it easier to see the effect of patches, which
>>          often  operate at the level of individual sentences or sen‐
>>          tence clauses.
>> 
>>> +before it gets removed.  The limit can take values ranging from 0
>>> +to 254; values 255 or higher behave the same as
>>> +.BR unlimited .
>>> +Limit values can be specified in either decimal or hexadecimal with a
>>> +"0x" prefix.  The special value
>>> +.B unlimited
>>> +is case-insensitive.  The default limit is 5.  A limit of 0 turns off the reloading
>>> +feature.  See NOTES below for further discussion of reloading.
>>>   .RE
>>>   .PP
>>>   .B paranoia
>>> @@ -128,6 +138,9 @@ in the specified cache for
>>>   is in seconds.
>>>   Larger values increase cache hit rates and reduce mean
>>>   response times, but increase problems with cache coherence.
>>> +Note that for some name services (including specifically DNS)
>>> +the TTL returned from the name service is used and this attribute
>>> +is ignored.
>>>   .RE
>>>   .PP
>>>   .B negative\-time\-to\-live
>>> @@ -166,6 +179,7 @@ The files are
>>>   .IR /etc/passwd ,
>>>   .IR /etc/group ,
>>>   .IR /etc/hosts ,
>>> +.IR /etc/resolv.conf ,
>>>   .IR /etc/services ,
>>>   and
>>>   .IR /etc/netgroup .
>>> @@ -194,6 +208,8 @@ is shared with the clients so
>>>   that they can directly search in them instead of having to ask the
>>>   daemon over the socket each time a lookup is performed.
>>>   The default is no.
>>> +Note that a cache miss will still result in asking the daemon over
>>> +the socket.
>>>   .RE
>>>   .PP
>>>   .B max\-db\-size
>>> @@ -230,12 +246,82 @@ and
>>>   .IR group .
>>>   .RE
>>>   .SH NOTES
>>> +.PP
>>>   The default values stated in this manual page originate
>>>   from the source code of
>>>   .BR nscd (8)
>>>   and are used if not overridden in the configuration file.
>>>   The default values used in the configuration file of
>>>   your distribution might differ.
>>> +.SS Reloading
>>> +.PP
>>> +.BR nscd (8)
>>> +has a feature called reloading whose behavior can be surprising.
>>> +.PP
>>> +Reloading is enabled when the
>>> +.B reload-count
>>> +attribute has a non-zero value.  The default value in the source
>>> +code enables reloading, although your distribution may differ.
>>> +.PP
>>> +When
>>> +reloading is enabled, positive cached entries (the results of
>>> +successful queries) do not simply expire when their TTL is up.  Instead,
>>> +at the expiry time
>>> +.B nscd
>>> +will "reload", i.e. re-issue the same name service query that created the cached
>>> +entry, to get a new value to cache.  Depending on
>>> +.B /etc/nsswitch.conf
>> 
>> Also from man-pages(7):
>> 
>>      Formatting conventions (general)
>> [...]
>> 
>>          Filenames  (whether  pathnames,  or  references  to  header
>>          files) are always in italics (e.g., <stdio.h>),  except  in
>>          the  SYNOPSIS  section,  where  included  files are in bold
>>          (e.g., #include <stdio.h>).  When referring to  a  standard
>>          header  file include, specify the header file surrounded by
>>          angle brackets, in the usual C way (e.g., <stdio.h>).
>> 
>> 
>>> +this may mean that a DNS, LDAP or NIS request is made.  If the new query
>>> +is successful reloading will repeat
>>> +when the new value would expire, until
>>> +.B reload-count
>>> +reloads have happened for the entry, and only then will it actually be removed
>>> +from the cache.  A request from a client which hits the entry will reset
>>> +the reload counter on the entry.  Purging the cache using the
>>> +.B \-i
>> 
>> Also from man-pages(7):
>> 
>>          Complete commands should, if long, be  written  as  an  in‐
>>          dented  line on their own, with a blank line before and af‐
>>          ter the command, for example
>> 
>>              man 7 man-pages
>> 
>>          If the command is short, then it can be included inline  in
>>          the  text,  in italic format, for example, man 7 man‐pages.
>>          In this case, it may  be  worth  using  nonbreaking  spaces
>>          ("\ ")  at suitable places in the command.  Command options
>>          should be written in italics (e.g., -l).
>> 
>> 
>>> +command line option overrides the reload logic and removes the entry.
>>> +.PP
>>> +Reloading has the effect of extending cache entry TTLs without compromising
>>> +on cache coherency, at the cost of additional load on the backing name service.
>>> +Whether this is a good idea on your system depends on details of
>>> +your applications' behavior, your name service, and the effective TTL values of
>>> +your cache entries.  (Note that for some name services (for example, DNS), the
>>> +effective TTL is the value returned from the name service and
>>> +.I not
>>> +the value of the
>>> +.B positive\-time\-to\-live
>>> +attribute.)  Please consider the following advice carefully:
>>> +.IP \(bu
>>> +If your application will make a second request for the same name, after
>>> +more then 1 TTL but before
>>> +.B reload\-count
>>> +TTLs, and is sensitive to the latency of a cache miss, then reloading may be
>>> +a good idea for you.
>>> +.IP \(bu
>>> +If your name service is configured to return very short TTLs, and your
>>> +applications only make requests rarely under normal circumstances, then
>>> +reloading may result in additional load on your backing name service
>>> +without any benefit to applications, which is probably a bad idea for you.
>>> +.IP \(bu
>>> +If your name service capacity is limited, reloading may have the
>>> +surprising effect of increasing load on your name service instead of
>>> +reducing it, and may be a bad idea for you.
>>> +.IP \(bu
>>> +Setting
>>> +.B reload\-count
>>> +to
>>> +.B unlimited
>>> +is almost never a good idea, as it will result in a cache that never expires
>>> +entries and puts never-ending additional load on the backing name service.
>>> +.PP
>>> +Note also that some distributions have an init script for nscd with a "reload"
>>> +command which has the effect of purging
>>> +.BR nscd 's
>>> +caches using the
>>> +.B \-i
>>> +commandline option.  That use of the word "reload" is
>>> +.I entirely different
>>> +from the "reloading" described here.
>>>   .SH SEE ALSO
>>>   .BR nscd (8)
>>>   .\" .SH AUTHOR
>>> 
>> 
>> 
>> -- 
>> Alejandro Colomar
>> Linux man-pages comaintainer; 
>> https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.kernel.org%2Fdoc%2Fman-pages%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C2e234f99d76a404167c408d95655f1d7%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637635750019288026%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=E1e7YGUZhDDpr8av9wG1WPa%2B33YOe64%2F7%2BZdfMmRUoM%3D&amp;reserved=0 
> <https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.kernel.org%2Fdoc%2Fman-pages%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C2e234f99d76a404167c408d95655f1d7%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637635750019288026%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=E1e7YGUZhDDpr8av9wG1WPa%2B33YOe64%2F7%2BZdfMmRUoM%3D&amp;reserved=0> 
> 
>> <https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.kernel.org%2Fdoc%2Fman-pages%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C2e234f99d76a404167c408d95655f1d7%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637635750019288026%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=E1e7YGUZhDDpr8av9wG1WPa%2B33YOe64%2F7%2BZdfMmRUoM%3D&amp;reserved=0 
> <https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.kernel.org%2Fdoc%2Fman-pages%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C2e234f99d76a404167c408d95655f1d7%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637635750019288026%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=E1e7YGUZhDDpr8av9wG1WPa%2B33YOe64%2F7%2BZdfMmRUoM%3D&amp;reserved=0>>
>> https://nam06.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.alejandro-colomar.es%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C2e234f99d76a404167c408d95655f1d7%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637635750019288026%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=jznPum1MSudWgDiUuW9DJnI%2BiOi6dKwGpAG9PR8phKc%3D&amp;reserved=0 
> <https://nam06.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.alejandro-colomar.es%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C2e234f99d76a404167c408d95655f1d7%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637635750019288026%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=jznPum1MSudWgDiUuW9DJnI%2BiOi6dKwGpAG9PR8phKc%3D&amp;reserved=0> 
> 
>> <https://nam06.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.alejandro-colomar.es%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C2e234f99d76a404167c408d95655f1d7%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637635750019288026%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=jznPum1MSudWgDiUuW9DJnI%2BiOi6dKwGpAG9PR8phKc%3D&amp;reserved=0 
> <https://nam06.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.alejandro-colomar.es%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C2e234f99d76a404167c408d95655f1d7%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637635750019288026%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=jznPum1MSudWgDiUuW9DJnI%2BiOi6dKwGpAG9PR8phKc%3D&amp;reserved=0>>
> 
> 
> -- 
> Alejandro Colomar
> Linux man-pages comaintainer; 
> https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.kernel.org%2Fdoc%2Fman-pages%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C2e234f99d76a404167c408d95655f1d7%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637635750019288026%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=E1e7YGUZhDDpr8av9wG1WPa%2B33YOe64%2F7%2BZdfMmRUoM%3D&amp;reserved=0 
> <https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.kernel.org%2Fdoc%2Fman-pages%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C2e234f99d76a404167c408d95655f1d7%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637635750019288026%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=E1e7YGUZhDDpr8av9wG1WPa%2B33YOe64%2F7%2BZdfMmRUoM%3D&amp;reserved=0>
> https://nam06.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.alejandro-colomar.es%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C2e234f99d76a404167c408d95655f1d7%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637635750019288026%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=jznPum1MSudWgDiUuW9DJnI%2BiOi6dKwGpAG9PR8phKc%3D&amp;reserved=0 
> <https://nam06.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.alejandro-colomar.es%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C2e234f99d76a404167c408d95655f1d7%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637635750019288026%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=jznPum1MSudWgDiUuW9DJnI%2BiOi6dKwGpAG9PR8phKc%3D&amp;reserved=0>


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [patch] nscd.conf.5: describe reloading, clarifications

[Alejandro Colomar (man-pages)]

CC += Branden


Hi Greg,

On 8/4/21 3:40 PM, Greg Banks wrote:
> Hi Alejandro,
> 
>  > Could you please use the same method you used for sending v1 to send 
> an v3? \
> 
> I did but apparently the email stack at my end insists on adding some 
> randomness to its behavior.  I'm going to try and step outside this 
> email text damage drama and send a pull request separately.

Hmm, not good.

The worst part is that as your emails are not plain text, they don't 
reach the mailing list (only the first one did).  If you can't solve it 
(I suggest using git-send-email(1), to avoid that randomness), I suggest 
that you send the email anyway as good as you can (better send it both 
inline and as an attachment, so that it is more likely that one of them 
will apply), and if it applies to my tree, I'll apply it and also 
forward it to the list as plain text.

> 
>> Also, please see some comments below.
> 
> Applied, thanks.
> 
>> >> +.PP
>> 
>> That's not correct.  Did you copy that from another place?  If so, 
>> please tell me because I should fix it.
> 
> No, it's a habit left over from the last time I contributed to this 
> project (in 2008).  It seems the rules have changed.
> 
>> We use that between paragraphs, but not before the first one nor after
>> the last one.
> 
> Ok, sure, but in that case the description of .PP in man(7) is wrong
> 
>         .PP      Begin a new paragraph and reset prevailing indent.

That's something that I had pending to address from Branden.  That page 
is a mix of things that should go into man-pages(7), groff_man_style(7), 
and groff_man(7), and then man(7) should be removed and replaced by a 
link page to groff_man(7).

For now,
You can read groff_man(7) (provided by the groff package), which tells 
us that .SH already does what .PP does (start a clean paragraph) (and it 
does more things, of course).  The thing is that if you add .PP after 
.SH you will have a blank line (and this an exercise of my mental groff, 
which I hope doesn't fail me this time), and it would be a bit weird to 
have a blank line after the section title.


Thanks,

Alex

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [patch] nscd.conf.5: describe reloading, clarifications

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 5186 bytes --]

Hi Alex,

At 2021-08-05T08:58:33+0200, Alejandro Colomar (man-pages) wrote:
[...]
> > > >> +.PP
> > > 
> > > That's not correct.  Did you copy that from another place?  If so,
> > > please tell me because I should fix it.
> > 
> > No, it's a habit left over from the last time I contributed to this
> > project (in 2008).  It seems the rules have changed.
> > 
> > > We use that between paragraphs, but not before the first one nor
> > > after the last one.
> > 
> > Ok, sure, but in that case the description of .PP in man(7) is wrong
> > 
> >         .PP      Begin a new paragraph and reset prevailing indent.
> 
> That's something that I had pending to address from Branden.  That
> page is a mix of things that should go into man-pages(7),
> groff_man_style(7), and groff_man(7), and then man(7) should be
> removed and replaced by a link page to groff_man(7).

I should emphasize that the foregoing is something I _proposed_ for
discussion.  I don't have any reason to suspect that it is something
that has wide buy-in yet.  I'm particularly interested in Michael's
opinion.

> For now, You can read groff_man(7) (provided by the groff package),
> which tells us that .SH already does what .PP does (start a clean
> paragraph) (and it does more things, of course).  The thing is that if
> you add .PP after .SH you will have a blank line (and this an exercise
> of my mental groff, which I hope doesn't fail me this time),

Sorry to disappoint you.  :-O

A PP (or LP, or P) call immediately after a SH call[1] will not add
vertical space because the SH macro definition puts *roff into what is
called "no-space mode"; vertical spacing is suppressed until turned back
on manually, or glyphs[2] are sent to the output.

> and it would be a bit weird to have a blank line after the section
> title.

Yes--as style advice I think this is quite sound and solidly
precedented.

To develop your *roff intuition, I suggest using groff as a REPL.  Yes,
it can be done!  For instance, while composing this mail, even though I
am familiar with the man(7) package sources, I attempted to protect
myself from the embarrassment of making an incorrect claim by testing
my knowledge with this short shell session[3].

$ nroff -man
.TH foo 1
.SH Name
.PP
Foobar.
foo(1)                      General Commands Manual                     foo(1)

Name
       Foobar.

                                                                        foo(1)

This quickly verified to me that I was right about no-space mode.

I so strongly advocate this method of familiarizing oneself with *roff
that I recently added a section about it to groff(1).

   Using groff as a REPL
       Those with a programmer’s bent may be pleased to know  that  they
       can use groff in a read-evaluate-print loop (REPL).  Doing so can
       be handy to verify one’s understanding of the formatter’s  behav‐
       ior  and/or  the syntax it accepts.  Turning on all warnings with
       -ww can aid this goal.

       $ groff -ww -Tutf8
       \# This is a comment. Let's define a register.
       .nr a 1
       \# Do integer arithmetic with operators evaluated left-to-right.
       .nr b \n[a]+5/2
       \# Let's get the result on the standard error stream.
       .tm \n[b]
       3
       \# Now we'll define a string.
       .ds name Leslie\" This is another form of comment.
       .nr b (\n[a] + (7/2))
       \# Center the next two text input lines.
       .ce 2
       Hi, \*[name].
       Your secret number is \n[b].
       \# We will see that the division rounded toward zero.
       It is
       \# Here's an if-else control structure.
       .ie (\n[b] % 2) odd.
       .el even.
       \# This trick sets the page length to the current vertical
       \# position, so that blank lines don't spew when we're done.
       .pl \n[nl]u
       <Control-D>
                                  Hi, Leslie.
                           Your secret number is 4.
       It is even.

The above example gets into many *roff concepts that man page authors
typically need not worry about.  Nevertheless the technique works with
macro packages, too, as shown earlier.  Macro packages often need to be
initialized.  man(7) is no exception.  If you do not call man's "TH" as
the first macro in the input, it will be unhappy.  That is why I had the
".TH foo 1" line.[4]

Regards,
Branden

[1] with arguments, technically--most people do not use the other legal
    form of calling SH input trap, which accepts input in the next line
[2] or drawing commands, but that's mostly irrelevant to man pages
[3] Full disclosure: my command input fibs above.  I actually used, not
    "nroff", but a shell alias of mine called "tgu", which runs a
    bleeding edge groff from a working tree, since I'm a groff
    developer.  After alias expansion, what I ran was
        ./build/test-groff -b -ww -Tutf8
    but that's not very useful to people who don't have a shell window
    that lives in a built groff working tree.
[4] A real man page would supply additional information to the macro.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]