debuginfod-doc: PR27950 - Remove redanduncies in man page.

Create a new file, debuginfod-client-config.7, that holds all
environment variables and cache control files related info. Get rid of
repetitive definitions in three other files, instead, those files will
include the content of new file. Any future modification related to
environment variables and cache files will only require changes in one
file.

Signed-off-by: Alice Zhang <alizhang@redhat.com>
Signed-off-by: Frank Ch. Eigler <fche@redhat.com>

8 files changed, 161 insertions, 152 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 1822fc6b..77d1d705 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,15 @@
+2021-07-28  Alice Zhang <alizhang@redhat.com>
+
+	PR27950
+	* debuginfod-client-config.7: New file to store all cache config
+	infos.
+	* debuginfod-find.1: Removed redundant occurrences of environment
+	variables & cache control files.
+	* debuginfod.8: Likewise.
+	* debuginfod_find_debuginfo.3: Likewise.
+	* Makefile.am: Updated to include debuginfod-client-config.7
+	* man3, man7: Symlinks for source tree man page testing.
+
 2021-07-26  Noah Sanci <nsanci@redhat.com>
 
 	PR27982
diff --git a/doc/Makefile.am b/doc/Makefile.am
index ef66fb88..7979be4d 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -19,14 +19,17 @@
 EXTRA_DIST = COPYING-GFDL README
 dist_man1_MANS=readelf.1 elfclassify.1
 notrans_dist_man3_MANS=elf_update.3 elf_getdata.3 elf_clone.3 elf_begin.3
+notrans_dist_man7_MANS=
 notrans_dist_man8_MANS=
 notrans_dist_man1_MANS=
 
 if DEBUGINFOD
+notrans_dist_man7_MANS += debuginfod-client-config.7
 notrans_dist_man8_MANS += debuginfod.8
 endif
 
 if LIBDEBUGINFOD
+notrans_dist_man7_MANS += debuginfod-client-config.7
 notrans_dist_man3_MANS += debuginfod_add_http_header.3
 notrans_dist_man3_MANS += debuginfod_begin.3
 notrans_dist_man3_MANS += debuginfod_end.3
diff --git a/doc/debuginfod-client-config.7 b/doc/debuginfod-client-config.7
new file mode 100644
index 00000000..1cc19215
--- /dev/null
+++ b/doc/debuginfod-client-config.7
@@ -0,0 +1,129 @@
+'\"! tbl | nroff \-man
+'\" t macro stdmacro
+.if \n(zZ=1 .ig zZ
+
+.TH DEBUGINFOD-CLIENT-CONFIG 7
+.SH NAME
+debuginfod-client-config \- debuginfod client environment variables, cache control files and etc.
+
+.SH SYNOPSIS
+Several environment variables and control files control the behaviour of debuginfod client applications.
+
+.\" The preceding section permits this man page to be viewed as if self-contained.
+.zZ
+.\" The following section (only) gets included into other man pages via .so
+
+
+.SH ENVIRONMENT VARIABLES
+.TP
+.B $TMPDIR
+This environment variable points to a file system to be used for
+temporary files.  The default is /tmp.
+
+.TP
+.B $DEBUGINFOD_URLS
+This environment variable contains a list of URL prefixes for trusted
+debuginfod instances.  Alternate URL prefixes are separated by space.
+Avoid referential loops that cause a server to contact itself, directly
+or indirectly - the results would be hilarious.
+
+.TP
+.B $DEBUGINFOD_CACHE_PATH
+This environment variable governs the location of the cache where
+downloaded files and cache-control files are kept.  The default
+directory is chosen based on other environment variables, see below.
+
+.TP
+.B $DEBUGINFOD_PROGRESS
+This environment variable governs the default progress function.  If
+set, and if a progressfn is not explicitly set, then the library will
+configure a default progressfn.  This function will append a simple
+progress message periodically to stderr.  The default is no progress
+function output.
+
+.TP
+.B $DEBUGINFOD_VERBOSE
+This environment variable governs the default file descriptor for
+verbose output.  If set, and if a verbose fd is not explicitly set,
+then the verbose output will be produced on STDERR_FILENO.
+
+.TP
+.B $DEBUGINFOD_RETRY_LIMIT
+This environment variable governs the default limit of retry attempts. If a
+query failed with errno other than ENOENT, will initiate several attempts
+within the limit.
+
+.TP
+.B $DEBUGINFOD_TIMEOUT
+This environment variable governs the download \fIcommencing\fP
+timeout for each debuginfod HTTP connection.  A server that fails to
+provide at least 100K of data within this many seconds is skipped. The
+default is 90 seconds.  (Zero or negative means "no timeout".)
+
+.TP
+.B $DEBUGINFOD_MAXTIME
+This environment variable dictates how long the client will wait to
+\fIcomplete\fP the download a file found on a server in seconds. It is best
+used to ensure that a file is downloaded quickly or be rejected. The
+default is 0 (infinite time).
+
+.TP
+.B $DEBUGINFOD_MAXSIZE
+This environment variable dictates the maximum size of a file to
+download in bytes. This is best used if the user would like to ensure
+only small files are downloaded. A value of 0 causes no consideration
+for size, and the client may attempt to download a file of any size.
+The default is 0 (infinite size).
+
+.SH CACHE
+
+Before each query, the debuginfod client library checks for a need to
+clean the cache.  If it's time to clean, the library traverses the
+cache directory and removes downloaded debuginfo-related artifacts and
+newly empty directories, if they have not been accessed recently.
+
+Control files are located directly under the cache directory.  They
+contain simple decimal numbers to set cache-related configuration
+parameters.  If the files do not exist, the client library creates the
+files with the default parameter values as content.
+
+After each query, the debuginfod client library deposits newly
+received files into a directory & file that is named based on the
+build-id.  A failed query is also cached by a special file.  The
+naming convention used for these artifacts is deliberately
+\fBundocumented\fP.
+
+.TP
+.B $XDG_CACHE_HOME/debuginfod_client/
+Default cache directory, if $XDG_CACHE_HOME is set.
+.PD
+
+.TP
+.B $HOME/.cache/debuginfod_client/
+Default cache directory, if $XDG_CACHE_HOME is not set.
+.PD
+
+.TP
+.B $HOME/.debuginfod_client_cache/
+Deprecated cache directory, used only if preexisting.
+.PD
+
+.TP
+.B cache_clean_interval_s
+This control file gives the interval between cache cleaning rounds, in
+seconds.  The default is 86400, one day.  0 means "immediately".
+
+.TP
+.B max_unused_age_s
+This control file sets how long unaccessed debuginfo-related files
+are retained, in seconds.  The default is 604800, one week.  0 means
+"immediately".
+
+.TP
+.B cache_miss_s
+This control file sets how long to remember a query failure, in
+seconds.  New queries for the same artifacts within this time window
+are short-circuited (returning an immediate failure instead of sending
+a new query to servers).  This accelerates queries that probably would
+still fail.  The default is 600, 10 minutes.  0 means "forget
+immediately".
diff --git a/doc/debuginfod-find.1 b/doc/debuginfod-find.1
index 482a8ae7..a61673f5 100644
--- a/doc/debuginfod-find.1
+++ b/doc/debuginfod-find.1
@@ -125,50 +125,8 @@ for the basic plaintext \%\fIhttp[s]://userid:password@hostname/\fP style.
 (The debuginfod server does not perform authentication, but a front-end
 proxy server could.)
 
-.SH "ENVIRONMENT VARIABLES"
-
-.TP 21
-.B DEBUGINFOD_URLS
-This environment variable contains a list of URL prefixes for trusted
-debuginfod instances.  Alternate URL prefixes are separated by space.
-
-.TP 21
-.B DEBUGINFOD_TIMEOUT
-This environment variable governs the timeout for each debuginfod HTTP
-connection.  A server that fails to provide at least 100K of data
-within this many seconds is skipped. The default is 90 seconds.  (Zero
-or negative means "no timeout".)
-
-.TP 21
-.B DEBUGINFOD_CACHE_PATH
-This environment variable governs the location of the cache where
-downloaded files are kept.  It is cleaned periodically as this program
-is reexecuted.  Cache management parameters may be set by files under
-this directory: see the \fBdebuginfod_find_debuginfo(3)\fP man page
-for details.  The default is $HOME/.debuginfod_client_cache.
-
-.TP 21
-.B DEBUGINFOD_MAXTIME
-This environment variable dictates how long the client will wait to
-download a file found on a server in seconds. It is best used to ensure
-that a file is downloaded quickly or be rejected. The default is
-0 (infinite time).
-
-.TP 21
-.B DEBUGINFOD_MAXSIZE
-This environment variable dictates the maximum size of a file to
-download in bytes. This is best used if the user would like to ensure
-only small files are downloaded. A value of 0 causes no consideration
-for size, and the client may attempt to download a file of any size.
-The default is 0 (infinite size).
-
-.SH "FILES"
-.LP
-.PD .1v
-.TP 20
-.B $HOME/.debuginfod_client_cache
-Default cache directory.
-.PD
+.nr zZ 1
+.so man7/debuginfod-client-config.7
 
 .SH "SEE ALSO"
 .I "debuginfod(8)"
diff --git a/doc/debuginfod.8 b/doc/debuginfod.8
index f70af625..3e791b62 100644
--- a/doc/debuginfod.8
+++ b/doc/debuginfod.8
@@ -12,7 +12,6 @@
 .fi
 .RE
 ..
-
 .TH DEBUGINFOD 8
 .SH NAME
 debuginfod \- debuginfo-related http file-server daemon
@@ -418,53 +417,15 @@ rather than HTTPS, the network should be trustworthy.  Authentication
 information through the internal \fIlibcurl\fP library is not currently
 enabled.
 
+.nr zZ 1
+.so man7/debuginfod-client-config.7
 
-.SH "ENVIRONMENT VARIABLES"
-
-.TP
-.B TMPDIR
-This environment variable points to a file system to be used for
-temporary files.  The default is /tmp.
-
-.TP
-.B DEBUGINFOD_URLS
-This environment variable contains a list of URL prefixes for trusted
-debuginfod instances.  Alternate URL prefixes are separated by space.
-Avoid referential loops that cause a server to contact itself, directly
-or indirectly - the results would be hilarious.
-
+.SH ADDITIONAL FILES
 .TP
-.B DEBUGINFOD_TIMEOUT
-This environment variable governs the timeout for each debuginfod HTTP
-connection.  A server that fails to provide at least 100K of data
-within this many seconds is skipped. The default is 90 seconds.  (Zero
-or negative means "no timeout".)
-
-
-.TP
-.B DEBUGINFOD_CACHE_PATH
-This environment variable governs the location of the cache where
-downloaded files are kept.  It is cleaned periodically as this
-program is reexecuted. If XDG_CACHE_HOME is set then
-$XDG_CACHE_HOME/debuginfod_client is the default location, otherwise
-$HOME/.cache/debuginfod_client is used. For more information regarding
-the client cache see \fIdebuginfod_find_debuginfo(3)\fP.
-
-.SH FILES
-.LP
-.PD .1v
-.TP 20
 .B $HOME/.debuginfod.sqlite
 Default database file.
 .PD
 
-.TP 20
-.B $XDG_CACHE_HOME/debuginfod_client
-Default cache directory for content from upstream debuginfods.
-If XDG_CACHE_HOME is not set then \fB$HOME/.cache/debuginfod_client\fP
-is used.
-.PD
-
 
 .SH "SEE ALSO"
 .I "debuginfod-find(1)"
diff --git a/doc/debuginfod_find_debuginfo.3 b/doc/debuginfod_find_debuginfo.3
index 7730dd32..30cef3c1 100644
--- a/doc/debuginfod_find_debuginfo.3
+++ b/doc/debuginfod_find_debuginfo.3
@@ -198,19 +198,6 @@ By default, the library adds a descriptive \fIUser-Agent:\fP
 header to outgoing requests.  If the client application adds
 a header with the same name, this default is suppressed.
 
-.SH "CACHE"
-If the query is successful, the \fBdebuginfod_find_*\fP() functions save
-the target file to a local cache. The location of the cache is controlled
-by the \fB$DEBUGINFOD_CACHE_PATH\fP environment variable (see below).
-Cleaning of the cache is controlled by the \fIcache_clean_interval_s\fP
-and \fImax_unused_age_s\fP files, which are found in the
-\fB$DEBUGINFOD_CACHE_PATH\fP directory. \fIcache_clean_interval_s\fP controls
-how frequently the cache is traversed for cleaning and \fImax_unused_age_s\fP
-controls how long a file can go unused (fstat(2) atime) before it's
-removed from the cache during cleaning. These files should contain only an
-ASCII decimal integer representing the interval or max unused age in seconds.
-The default is one day and one week, respectively.  Values of zero mean "immediately".
-
 .SH "MACROS"
 
 .SS "DEBUGINFOD_SONAME"
@@ -241,48 +228,6 @@ for the basic plaintext \%\fIhttp[s]://userid:password@hostname/\fP style.
 (The debuginfod server does not perform authentication, but a front-end
 proxy server could.)
 
-.SH "ENVIRONMENT VARIABLES"
-
-.TP 21
-.B DEBUGINFOD_URLS
-This environment variable contains a list of URL prefixes for trusted
-debuginfod instances.  Alternate URL prefixes are separated by space.
-
-.TP 21
-.B DEBUGINFOD_TIMEOUT
-This environment variable governs the timeout for each debuginfod HTTP
-connection.  A server that fails to provide at least 100K of data
-within this many seconds is skipped. The default is 90 seconds.  (Zero
-or negative means "no timeout".)
-
-.TP 21
-.B DEBUGINFOD_PROGRESS
-This environment variable governs the default progress function.  If
-set, and if a progressfn is not explicitly set, then the library will
-configure a default progressfn.  This function will append a simple
-progress message periodically to stderr.  The default is no progress
-function output.
-
-.TP 21
-.B DEBUGINFOD_VERBOSE
-This environment variable governs the default file descriptor for
-verbose output.  If set, and if a verbose fd is not explicitly set,
-then the verbose output will be produced on STDERR_FILENO.
-
-.TP 21
-.B DEBUGINFOD_CACHE_PATH
-This environment variable governs the location of the cache where
-downloaded files are kept.  It is cleaned periodically as this
-program is reexecuted. If XDG_CACHE_HOME is set then
-$XDG_CACHE_HOME/debuginfod_client is the default location, otherwise
-$HOME/.cache/debuginfod_client is used.
-
-.TP 21
-.B DEBUGINFOD_RETRY_LITMIT
-This environment variable governs the default limit of retry attempts. If a
-query failed with errno other than ENOENT, will initiate several attempts
-within the limit.
-
 .SH "ERRORS"
 The following list is not comprehensive. Error codes may also
 originate from calls to various C Library functions.
@@ -338,17 +283,16 @@ System is unable to allocate resources.
 
 .TP
 .BR ETIME
-Query failed due to timeout. \fB$DEBUGINFOD_TIMEOUT\fP controls
-the timeout duration. See debuginfod(8) for more information.
-
-.SH "FILES"
-.LP
-.PD .1v
-.TP 20
-.B $HOME/.debuginfod_client_cache
-Default cache directory. If XDG_CACHE_HOME is not set then
-\fB$HOME/.cache/debuginfod_client\fP is used.
-.PD
+Query failed due to timeout. \fB$DEBUGINFOD_TIMEOUT\fP and
+\fB$DEBUGINFOD_MAXTIME\fP control this.
+
+.TP
+.BR EF2BIG
+Query aborted due to the file requested being too big.  The
+\fB$DEBUGINFOD_MAXSIZE\fP controls this.
+
+.nr zZ 1
+.so man7/debuginfod-client-config.7
 
 .SH "SEE ALSO"
 .I "debuginfod(8)"
diff --git a/doc/man3 b/doc/man3
new file mode 120000
index 00000000..945c9b46
--- /dev/null
+++ b/doc/man3
@@ -0,0 +1 @@
+.
\ No newline at end of file
diff --git a/doc/man7 b/doc/man7
new file mode 120000
index 00000000..945c9b46
--- /dev/null
+++ b/doc/man7
@@ -0,0 +1 @@
+.
\ No newline at end of file