[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: John Darrington
Subject: Re: [PATCH 2/2] gnu: Add GSSD and Pipefs services (Usage of @var)
Date: Wed, 21 Sep 2016 20:29:23 +0200
User-agent: Mutt/1.5.23 (2014-03-12)

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

However, here is a different example:

    (define-public hello
        (name "hello")
        (version "2.10")
        (source (origin
                  (method url-fetch)
                  (uri (string-append "mirror://gnu/hello/hello-" version
        (build-system gnu-build-system)
        (home-page "";)
        (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 
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 

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.

Avoid eavesdropping.  Send strong encrypted email.
PGP Public key ID: 1024D/2DE827B3 
fingerprint = 8797 A26D 0854 2EAB 0285  A290 8A67 719C 2DE8 27B3
See or any PGP keyserver for public key.

Attachment: signature.asc
Description: Digital signature

reply via email to

[Prev in Thread] Current Thread [Next in Thread]