Re: [PATCH 2/2] gnu: Add GSSD and Pipefs services (Usage of @var)

[Ludovic Courtès]

Hi!

John Darrington <address@hidden> skribis:

> On Wed, Sep 14, 2016 at 04:42:11PM +0200, Ludovic Court??s wrote:
>      John Darrington <address@hidden> skribis:
>      
>      > On Tue, Sep 13, 2016 at 01:45:19PM +0200, Ludovic Court??s wrote:
>      >      John Darrington <address@hidden> skribis:
>      >
>      >      > address@hidden @code{nfs-utils} (default: @code{nfs-utils})
>      >                                          ^^^^^
>      >      Should be @var, because here we???re talking about the value of 
> the
>      >      ???nfs-utils??? global variable.
>      >
>      > I think you are mistaken here.  Quoting from the Texinfo manual:
>      >
>      >     Use the @var command to indicate metasyntactic variables. A 
> metasyntactic 
>      >    variable is something that stands for another piece of text. For 
> example, you
>      >    should use a metasyntactic variable in the documentation of a 
> function to 
>      >    describe the arguments that are passed to that function.
>      >
>      >     Do not use @var for the names of normal variables in computer 
> programs. These
>      >    are specific names, so @code is correct for them (@code).  For 
> example, the 
>      >    Emacs Lisp variable texinfo-tex-command is not a metasyntactic 
> variable; it 
>      >    is properly formatted using @code.
>      >
>      > Or have I got it wrong?
>      
>      Dunno, my interpretation is that ???nfs-utils??? here denotes the value 
> of
>      the ???nfs-utils??? variable, so it ???stands for another piece of 
> text???,
>      which is (package (name "nfs-utils") ???).
>
>
> I don't understand what you are saying.  The text says:
>
>   This type has the following parameters:
>   @item @code{nfs-utils} (default: @code{nfs-utils})
>
> (I think it's a little confusing that both the parameter and its default 
> value are both called 
> "nfs-utils" - but that is another issue).
>
> The first instance of @code{nfs-utils} is the name of the parameter.  It does 
> not stand for
> something else.  That is what it is really called.  Similarly, the second 
> instance
> (default: @code{nfs-utils})  also does not stand for something else.  It is 
> literally the default
> value of the parameter.

The 2nd instance means “the value of the ‘nfs-utils’ global variable.”

> Now here is an example from the manual where we have correctly used @var:
>
>    The following command-line options are supported:
>
>    @item address@hidden
>    Take users from @var{group} to run build processes 
>
> This is correct usage of @var, because here "group" is a metasyntactical 
> variable.  That is to say we
> don't intend the user to literally type "group" --- we mean him to substitute 
> it with whatever
> group name he has chosen for his builders.

Agreed.

> However, here is a different example:
>
>     @example
>     
>     (define-public hello
>       (package
>         (name "hello")
>         (version "2.10")
>         (source (origin
>                   (method url-fetch)
>                   (uri (string-append "mirror://gnu/hello/hello-" version
>                                       ".tar.gz"))
>                   (sha256
>                    (base32
>                     "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
>         (build-system gnu-build-system)
>         (home-page "http://www.gnu.org/software/hello/";)
>         (license gpl3+)))
>     @end example
>     
>     In the example above, @var{hello} is defined in a module of its own,
>     @code{(gnu packages hello)}.  
>     
>
> This, as I understand it, is incorrect use of @var because "hello" does not 
> stand
> for something else.

Oh, I finally got it, thanks for persevering.  :-)

Regarding the pipefs patch, you can safely ignore my comment.

OK, so I think you’re right and my understanding of @var was flawed.  So
forget my initial comment.  We should eventually fix invalid uses, but
no rush here.

Thanks,
Ludo’.