From mboxrd@z Thu Jan 1 00:00:00 1970 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 Message-ID: <20160921182923.GA25698@jocasta.intra> References: <1473535083-5326-1-git-send-email-jmd@gnu.org> <1473535083-5326-2-git-send-email-jmd@gnu.org> <87bmzs6n1s.fsf@gnu.org> <20160913135330.GA24267@jocasta.intra> <87a8fapmpo.fsf@gnu.org> Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="/9DWx/yDrRhgMJTb" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:35182) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bmmH1-0002xK-ID for guix-devel@gnu.org; Wed, 21 Sep 2016 14:29:36 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bmmGy-0006Fk-Uv for guix-devel@gnu.org; Wed, 21 Sep 2016 14:29:34 -0400 Content-Disposition: inline In-Reply-To: <87a8fapmpo.fsf@gnu.org> List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: "Guix-devel" To: Ludovic Court??s Cc: guix-devel@gnu.org --/9DWx/yDrRhgMJTb Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Wed, Sep 14, 2016 at 04:42:11PM +0200, Ludovic Court??s wrote: John Darrington skribis: =20 > 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 meta= syntactic=20 > variable is something that stands for another piece of text. For = example, you > should use a metasyntactic variable in the documentation of a fun= ction to=20 > describe the arguments that are passed to that function. > > Do not use @var for the names of normal variables in computer pr= ograms. These > are specific names, so @code is correct for them (@code). For ex= ample, the=20 > Emacs Lisp variable texinfo-tex-command is not a metasyntactic va= riable; it=20 > is properly formatted using @code. > > Or have I got it wrong? =20 Dunno, my interpretation is that ???nfs-utils??? here denotes the valu= e of the ???nfs-utils??? variable, so it ???stands for another piece of tex= t???, 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 va= lue are both called=20 "nfs-utils" - but that is another issue). The first instance of @code{nfs-utils} is the name of the parameter. It do= es not stand for something else. That is what it is really called. Similarly, the second i= nstance (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=3D@var{group} Take users from @var{group} to run build processes=20 This is correct usage of @var, because here "group" is a metasyntactical va= riable. That is to say we don't intend the user to literally type "group" --- we mean him to substitu= te it with whatever group name he has chosen for his builders. However, here is a different example: @example =20 (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 =20 In the example above, @var{hello} is defined in a module of its own, @code{(gnu packages hello)}. =20 =20 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 shou= ld 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 wi= thin Guix and be consistent with other projects which use Texinfo. If you like I can che= ckin a change to fixup the current inconsistencies. J' =20 =20 --=20 Avoid eavesdropping. Send strong encrypted email. PGP Public key ID: 1024D/2DE827B3=20 fingerprint =3D 8797 A26D 0854 2EAB 0285 A290 8A67 719C 2DE8 27B3 See http://sks-keyservers.net or any PGP keyserver for public key. --/9DWx/yDrRhgMJTb Content-Type: application/pgp-signature; name="signature.asc" Content-Description: Digital signature -----BEGIN PGP SIGNATURE----- Version: GnuPG v1 iEYEARECAAYFAlfi0YMACgkQimdxnC3oJ7OQFwCgiiTXQtQRKljkXtUGtvOoww+v N3YAni38ALMJLiXXlizXRdgKM5DuKZrl =aw7s -----END PGP SIGNATURE----- --/9DWx/yDrRhgMJTb--