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

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
  

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
  

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
  

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
  

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
  

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