Re: [PATCH 2/2] gnu: Add GSSD and Pipefs services (Usage of @var)
Hi!
John Darrington skribis:
> On Wed, Sep 14, 2016 at 04:42:11PM +0200, Ludovic Court??s wrote:
> John Darrington skribis:
>
> > On Tue, Sep 13, 2016 at 01:45:19PM +0200, Ludovic Court??s wrote:
> > John Darrington 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’.
Re: [PATCH 2/2] gnu: Add GSSD and Pipefs services (Usage of @var)
On Wed, Sep 14, 2016 at 04:42:11PM +0200, Ludovic Court??s wrote:
John Darrington skribis:
> On Tue, Sep 13, 2016 at 01:45:19PM +0200, Ludovic Court??s wrote:
> John Darrington 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.
No big deal, but we should settle on a single convention and so far
we???ve used @var in such cases.
Well looking at other sections I see that we have been far from consistent.
Some have used @code
and others have used @var.
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.
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. It refers litererally to the text "hello" and we should
put it in @code
to indicate that it is a fragment of code. It is a variable which is part of
guix.
I think the passage from the Texinfo manual which I quoted is quite clear.
But I agree that we need to be consistent. We should be consistent both within
Guix and
be consistent with other projects which use Texinfo. If you like I can checkin
a change
to fixup the current inconsistencies.
J'
--
Avoid eavesdropping. Send strong encrypted email.
PGP Public key ID: 1024D/2DE827B3
fingerprint = 8797 A26D 0854 2EAB 0285 A290 8A67 719C 2DE8 27B3
See http://sks-keyservers.net or any PGP keyserver for public key.
signature.asc
Description: Digital signature
Re: [PATCH 2/2] gnu: Add GSSD and Pipefs services (Usage of @var)
John Darrington skribis:
> On Tue, Sep 13, 2016 at 01:45:19PM +0200, Ludovic Court??s wrote:
> John Darrington 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") …).
No big deal, but we should settle on a single convention and so far
we’ve used @var in such cases.
Ludo’.
Re: [PATCH 2/2] gnu: Add GSSD and Pipefs services (Usage of @var)
On Tue, Sep 13, 2016 at 01:45:19PM +0200, Ludovic Court??s wrote:
John Darrington 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?
J'
--
Avoid eavesdropping. Send strong encrypted email.
PGP Public key ID: 1024D/2DE827B3
fingerprint = 8797 A26D 0854 2EAB 0285 A290 8A67 719C 2DE8 27B3
See http://sks-keyservers.net or any PGP keyserver for public key.
signature.asc
Description: Digital signature
