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

[John Darrington <john@darrington.wattle.id.au>]

[-- Attachment #1: Type: text/plain, Size: 4407 bytes --]

On Wed, Sep 14, 2016 at 04:42:11PM +0200, Ludovic Court??s wrote:
     John Darrington <john@darrington.wattle.id.au> skribis:
     
     > On Tue, Sep 13, 2016 at 01:45:19PM +0200, Ludovic Court??s wrote:
     >      John Darrington <jmd@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.


[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 181 bytes --]