Hi!
John Darrington <j...@darrington.wattle.id.au> skribis:
> On Wed, Sep 14, 2016 at 04:42:11PM +0200, Ludovic Court??s wrote:
> John Darrington <j...@darrington.wattle.id.au> skribis:
>
> > On Tue, Sep 13, 2016 at 01:45:19PM +0200, Ludovic Court??s wrote:
> > John Darrington <j...@gnu.org> skribis:
> >
> > > +@item @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 --build-users-group=@var{group}
> 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’.
