diff mbox series

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

Message ID 20210728194230.298903-1-alizhang@redhat.com
State Superseded
Headers show
Series debuginfod-doc: PR27950 - Remove redanduncies in man page. | expand

Commit Message

Alice Zhang July 28, 2021, 7:42 p.m. UTC
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>
---
 doc/ChangeLog                   | 10 +++++
 doc/debuginfod-client-config.7  | 68 +++++++++++++++++++++++++++++++++
 doc/debuginfod-find.1           | 30 +--------------
 doc/debuginfod.8                | 49 +-----------------------
 doc/debuginfod_find_debuginfo.3 | 51 +------------------------
 5 files changed, 81 insertions(+), 127 deletions(-)
 create mode 100644 doc/debuginfod-client-config.7

Comments

Mark Wielaard July 29, 2021, 2:24 p.m. UTC | #1
Hi Alice,

On Wed, 2021-07-28 at 15:42 -0400, Alice Zhang via Elfutils-devel wrote:
> 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.
> 
> +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.

I like the idea, but I am unclear how this works. That might just be my
limited knowledge of man/troff.

Is debuginfod-client-config.7 intended to be installed? If so it should
be added to notrans_dist_man7_MANS in doc/Makefile.am, otherwise it
should be added to EXTRA_DIST to indicate it is a file part of the
(source) distribution.

I assume it should not be installed because it looks like a fragment of
a man page. At least it doesn't seem to render correctly when displayed
by man for me.

If it isn't intended to be installed, maybe give it a different suffix
so it isn't confused to be a standalone man page?

> +.so ./debuginfod-client-config.7

So this is intended to include the fragment into the man page?
That also doesn't seem to work for me. How/when does it do the
lookup/inclusion?

Please feel free to point me to the automake/man documentation if that
explains it all.

Thanks,

Mark
Frank Ch. Eigler July 29, 2021, 2:36 p.m. UTC | #2
Hi -

> Is debuginfod-client-config.7 intended to be installed? If so it should
> be added to notrans_dist_man7_MANS in doc/Makefile.am, [...]

Yeah.

> If it isn't intended to be installed, maybe give it a different suffix
> so it isn't confused to be a standalone man page?
> 
> > +.so ./debuginfod-client-config.7
> 
> So this is intended to include the fragment into the man page?
> That also doesn't seem to work for me. How/when does it do the
> lookup/inclusion?

man/nroff executes the .so directive during rendering, i.e., searches
for content in the installed $MANPATH at run time.  It is used on
other fedora man pages e.g. for command aliases.

If we look at man1/builtins.1 and man1/bash.1, they show a bit of this
pattern.  And actually bash.1 has some conditional inclusion tricks to
let the bash.1 page be includable as well as standalone.  That same
trick could be done within the new debuginfod-client-config.7 file.
See the refs to ".ig zZ" and ".zZ", ".nr zZ 1" in the file that
contains the .so directive.

- FChE
Mark Wielaard July 30, 2021, 12:26 p.m. UTC | #3
Hi Frank,

On Thu, 2021-07-29 at 10:36 -0400, Frank Ch. Eigler via Elfutils-devel wrote:
> Is debuginfod-client-config.7 intended to be installed? If so it should
> > be added to notrans_dist_man7_MANS in doc/Makefile.am, [...]
> 
> Yeah.
> 
> > If it isn't intended to be installed, maybe give it a different suffix
> > so it isn't confused to be a standalone man page?
> > 
> > > +.so ./debuginfod-client-config.7
> > 
> > So this is intended to include the fragment into the man page?
> > That also doesn't seem to work for me. How/when does it do the
> > lookup/inclusion?
> 
> man/nroff executes the .so directive during rendering, i.e., searches
> for content in the installed $MANPATH at run time.  It is used on
> other fedora man pages e.g. for command aliases.

aha, ok, I understand now. This makes testing in-tree a bit more
difficult. So the .so ./debuginfod-client-config.7 does work if you got
into the doc/ subdirectory, then man ./debuginfod-find.1 does show the
included chunks. But for the installed tree it should be .so man7
debuginfod-client-config.7 ?

> If we look at man1/builtins.1 and man1/bash.1, they show a bit of this
> pattern.  And actually bash.1 has some conditional inclusion tricks to
> let the bash.1 page be includable as well as standalone.  That same
> trick could be done within the new debuginfod-client-config.7 file.
> See the refs to ".ig zZ" and ".zZ", ".nr zZ 1" in the file that
> contains the .so directive.

That is interesting, then we could make debuginfod-client-config.7 into
a real man page and include only the actual contents. I am not
completely sure I understand how this works though. I hope there is
some man/troff documentation that explains this trick?

Thanks,

Mark
Frank Ch. Eigler July 30, 2021, 12:47 p.m. UTC | #4
Hi -

> aha, ok, I understand now. This makes testing in-tree a bit more
> difficult. So the .so ./debuginfod-client-config.7 does work if you got
> into the doc/ subdirectory, then man ./debuginfod-find.1 does show the
> included chunks. But for the installed tree it should be .so man7
> debuginfod-client-config.7 ?

It'd probably be ".so ../man7/debuginfod-client-config.7" or something.

> > If we look at man1/builtins.1 and man1/bash.1, they show a bit of this
> > pattern.  And actually bash.1 has some conditional inclusion tricks to
> > let the bash.1 page be includable as well as standalone.  That same
> > trick could be done within the new debuginfod-client-config.7 file.
> > See the refs to ".ig zZ" and ".zZ", ".nr zZ 1" in the file that
> > contains the .so directive.
> 
> That is interesting, then we could make debuginfod-client-config.7 into
> a real man page and include only the actual contents. I am not
> completely sure I understand how this works though. I hope there is
> some man/troff documentation that explains this trick?

Documentation?  Nah, let's reverse-engineer:

NROFF                           CPP

builtins.1:

.nr zZ 1                        #define zZ 1
.so bash.1                      #include <bash.1>

bash.1:

.if \n(zZ=1 .ig zZ              #ifndef zZ
  [...]                            [...]
.zZ                             #else
  [...]                            [...]


- FChE
Mark Wielaard Aug. 4, 2021, 11:33 a.m. UTC | #5
Hi Frank,

On Fri, 2021-07-30 at 08:47 -0400, Frank Ch. Eigler wrote:
> > aha, ok, I understand now. This makes testing in-tree a bit more
> > difficult. So the .so ./debuginfod-client-config.7 does work if you
> > got
> > into the doc/ subdirectory, then man ./debuginfod-find.1 does show
> > the
> > included chunks. But for the installed tree it should be .so man7
> > debuginfod-client-config.7 ?
> 
> It'd probably be ".so ../man7/debuginfod-client-config.7" or
> something.

I cannot find the canonical documentation on this, but it looks like
the search path is the current directory plus MANPATH, so I am not sure
.. would work. man7 (and I think it should be space, not slash) should
work as long its parent is either the current directory or in the
MANPATH. But all this is a little fuzzy.

Maybe we need man1, man3, man7, etc subdirs in doc to make it also work
in-tree (but then buildir != srcdir probably is still borken). It might
be fine if it only works in the install tree though. Just don't know
how to write tests to double check things are fine.

> > That is interesting, then we could make debuginfod-client-config.7
> > into a real man page and include only the actual contents. I am not
> > completely sure I understand how this works though. I hope there is
> > some man/troff documentation that explains this trick?
> 
> Documentation?  Nah, let's reverse-engineer:
> 
> NROFF                           CPP
> 
> builtins.1:
> 
> .nr zZ 1                        #define zZ 1
> .so bash.1                      #include <bash.1>
> 
> bash.1:
> 
> .if \n(zZ=1 .ig zZ              #ifndef zZ
>   [...]                            [...]
> .zZ                             #else
>   [...]                            [...]

OK, that looks workable (although slightly ugly).

Alice, would you be able to rewrite the split man pages using the above
trickery? Please do feel to ask for more info and we'll try to figure
something out.

Thanks,

Mark
Mark Wielaard Aug. 5, 2021, 5:07 p.m. UTC | #6
Hi Alice,

(adding elfutils-devel back to CC so other know what we discussed)

On Wed, 2021-08-04 at 17:36 -0400, Alice Zhang wrote:
> Hi Mark, I made debuginfod-client-config.7 a relatively complete man page
> and include only the part we need into other files by using
> $.if \n(zZ=1 .ig zZ
> ...
> $.zZ
> ...
> I also changed .*so ./debuginfod-client-config.7* to *.so
> man7/debuginfod-client-config.7*, since I found some similar usage in
> debuginfod_get_url.3, like *$.so man3/debuginfod_find_debuginfo.3*.
> 
> The Attachment is the new patch, let me know if any other modifications are
> needed.

Very nice, you understood the include guards that were puzzling me.
This looks very nice. I think the only thing that is needed is actually
installing the new manpage with something like:

notrans_dist_man7_MANS = debuginfod-client-config.7

in doc/Makefile.am (probably under the if LIBDEBUGINFOD.

And then double check that man debuginfod-client-config and man
debuginfod_get_url etc. work when everything is installed.

e.g. If you
configure --prefix=/tmp/elfutils-install && make && make install
and then set MANPATH
export MANPATH=/tmp/elfutils-install
that man debuginfod-client-config and man debuginfod_find_debuginfo
product the correct results (show the includes).

Thanks,

Mark
diff mbox series

Patch

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 05fcd23d..4ace8771 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,13 @@ 
+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.
+
 2021-04-23  Frank Ch. Eigler <fche@redhat.com>
 
 	PR27701
diff --git a/doc/debuginfod-client-config.7 b/doc/debuginfod-client-config.7
new file mode 100644
index 00000000..81539dc2
--- /dev/null
+++ b/doc/debuginfod-client-config.7
@@ -0,0 +1,68 @@ 
+.SH ENVIRONMENT VARIABLES
+.TP 21
+.B TMPDIR
+This environment variable points to a file system to be used for
+temporary files.  The default is /tmp.
+
+.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.
+Avoid referential loops that cause a server to contact itself, directly
+or indirectly - the results would be hilarious.
+
+.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. 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.
+
+.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_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 FILES
+.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
+
+.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
diff --git a/doc/debuginfod-find.1 b/doc/debuginfod-find.1
index 12d4ec2d..ec357b38 100644
--- a/doc/debuginfod-find.1
+++ b/doc/debuginfod-find.1
@@ -125,35 +125,7 @@  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.
-
-.SH "FILES"
-.LP
-.PD .1v
-.TP 20
-.B $HOME/.debuginfod_client_cache
-Default cache directory.
-.PD
+.so ./debuginfod-client-config.7
 
 .SH "SEE ALSO"
 .I "debuginfod(8)"
diff --git a/doc/debuginfod.8 b/doc/debuginfod.8
index f70af625..35f4708b 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,7 @@  rather than HTTPS, the network should be trustworthy.  Authentication
 information through the internal \fIlibcurl\fP library is not currently
 enabled.
 
-
-.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_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
-
+.so ./debuginfod-client-config.7
 
 .SH "SEE ALSO"
 .I "debuginfod-find(1)"
diff --git a/doc/debuginfod_find_debuginfo.3 b/doc/debuginfod_find_debuginfo.3
index 7730dd32..60a69fd0 100644
--- a/doc/debuginfod_find_debuginfo.3
+++ b/doc/debuginfod_find_debuginfo.3
@@ -241,48 +241,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.
@@ -341,14 +299,7 @@  System is unable to allocate resources.
 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
+.so ./debuginfod-client-config.7
 
 .SH "SEE ALSO"
 .I "debuginfod(8)"