Re: [gentoo-dev] [PATCH] tmpfiles.eclass: fix @USAGE to not include function name

[Mike Gilbert]

On Fri, Sep 6, 2019 at 2:52 PM Michael Everitt <gentoo@×××××××.xyz> wrote:
>
> On 06/09/19 18:27, Ben Kohler wrote:
> > Signed-off-by: Ben Kohler <bkohler@g.o>
> > ---
> >  eclass/tmpfiles.eclass | 6 +++---
> >  1 file changed, 3 insertions(+), 3 deletions(-)
> >
> > diff --git a/eclass/tmpfiles.eclass b/eclass/tmpfiles.eclass
> > index 68478ffbcd6..360c5e3b816 100644
> > --- a/eclass/tmpfiles.eclass
> > +++ b/eclass/tmpfiles.eclass
> > @@ -63,7 +63,7 @@ esac
> >  RDEPEND="virtual/tmpfiles"
> >
> >  # @FUNCTION: dotmpfiles
> > -# @USAGE: dotmpfiles <tmpfiles.d_file> ...
> > +# @USAGE: <tmpfiles.d_file> ...
> >  # @DESCRIPTION:
> >  # Install one or more tmpfiles.d files into /usr/lib/tmpfiles.d.
> >  dotmpfiles() {
> > @@ -84,7 +84,7 @@ dotmpfiles() {
> >  }
> >
> >  # @FUNCTION: newtmpfiles
> > -# @USAGE: newtmpfiles <old-name> <new-name>.conf
> > +# @USAGE: <old-name> <new-name>.conf
> >  # @DESCRIPTION:
> >  # Install a tmpfiles.d file in /usr/lib/tmpfiles.d under a new name.
> >  newtmpfiles() {
> > @@ -102,7 +102,7 @@ newtmpfiles() {
> >  }
> >
> >  # @FUNCTION: tmpfiles_process
> > -# @USAGE: tmpfiles_process <filename> <filename> ...
> > +# @USAGE: <filename> <filename> ...
> >  # @DESCRIPTION:
> >  # Call a tmpfiles.d implementation to create new volatile and temporary
> >  # files and directories.
> This series seems super counter-intuitive to me .. surely all usage
> examples (in Linux/etc in general) utilise the command itself to provide
> context of how to invoke the function/etc ?? or am I [once again] mistaken?
>
> Perhaps the series should be to *add* the function across the tree, rather
> than remove it?
>

Having the function name in the @USAGE block results in duplicate
output in the resulting man page.

FUNCTIONS
       dotmpfiles dotmpfiles <tmpfiles.d_file> ...
              Install one or more tmpfiles.d files into /usr/lib/tmpfiles.d.

       newtmpfiles newtmpfiles <old-name> <new-name>.conf
              Install a tmpfiles.d file in /usr/lib/tmpfiles.d under a new name.

       tmpfiles_process tmpfiles_process <filename> <filename> ...
              Call a tmpfiles.d implementation to create new volatile
and temporary files and di‐
              rectories.