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

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

[Ben Kohler]

Signed-off-by: Ben Kohler <bkohler@gentoo.org>
---
 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.
-- 
2.23.0

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

[William Hubbs]

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

On Fri, Sep 06, 2019 at 12:27:25PM -0500, Ben Kohler wrote:
> Signed-off-by: Ben Kohler <bkohler@gentoo.org>
> ---
>  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.
> -- 
> 2.23.0

lgtm. :-)

William


[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

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

[Michael Everitt]

[-- Attachment #1.1: Type: text/plain, Size: 1538 bytes --]

On 06/09/19 18:27, Ben Kohler wrote:
> Signed-off-by: Ben Kohler <bkohler@gentoo.org>
> ---
>  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?


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 801 bytes --]

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@veremit.xyz> wrote:
>
> On 06/09/19 18:27, Ben Kohler wrote:
> > Signed-off-by: Ben Kohler <bkohler@gentoo.org>
> > ---
> >  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.

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

[Georgy Yakovlev]

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

On Friday, September 6, 2019 11:52:53 AM PDT Michael Everitt wrote:
> On 06/09/19 18:27, Ben Kohler wrote:
> 
> 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?

Command itself is already added by magic awk, Ben just removing duplicates.

for example, desktop eclass man page right now

make_desktop_entry make_desktop_entry(<command>, [name], [icon], [type]...

after the change

make_desktop_entry (<command>, [name], [icon], [type], [fields])



check app-doc/eclass-manpages awk magic file how the pages are generated.

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Michael Everitt]

[-- Attachment #1.1: Type: text/plain, Size: 1096 bytes --]

On 06/09/19 20:00, Georgy Yakovlev wrote:
> On Friday, September 6, 2019 11:52:53 AM PDT Michael Everitt wrote:
>> On 06/09/19 18:27, Ben Kohler wrote:
>>
>> 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?
> Command itself is already added by magic awk, Ben just removing duplicates.
>
> for example, desktop eclass man page right now
>
> make_desktop_entry make_desktop_entry(<command>, [name], [icon], [type]...
>
> after the change
>
> make_desktop_entry (<command>, [name], [icon], [type], [fields])
>
>
>
> check app-doc/eclass-manpages awk magic file how the pages are generated.
Thanks for that, Georgy!

Perhaps I should re-word the request to remove the awk magic from the
eclass-manpages, so that the original source makes sense when reading it
without external tools ? Thoughts?!


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 801 bytes --]

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

[Kent Fredric]

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

On Fri, 6 Sep 2019 20:02:05 +0100
Michael Everitt <gentoo@veremit.xyz> wrote:

>  so that the original source makes sense when reading it
> without external tools ? Thoughts?

The source still makes sense without external tools.

You just need to understand the syntax :p

- @FUNCTION @USAGE

And @FUNCTION is *right there* ;)

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

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

[Michael Everitt]

[-- Attachment #1.1: Type: text/plain, Size: 454 bytes --]

On 06/09/19 20:09, Kent Fredric wrote:
> On Fri, 6 Sep 2019 20:02:05 +0100
> Michael Everitt <gentoo@veremit.xyz> wrote:
>
>>  so that the original source makes sense when reading it
>> without external tools ? Thoughts?
> The source still makes sense without external tools.
>
> You just need to understand the syntax :p
>
> - @FUNCTION @USAGE
>
> And @FUNCTION is *right there* ;)
psh .. my organic parser is deficient, clearly .. :P



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 801 bytes --]