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.
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
