From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 8767 invoked by alias); 1 Sep 2007 07:56:36 -0000 Received: (qmail 8759 invoked by uid 22791); 1 Sep 2007 07:56:35 -0000 X-Spam-Check-By: sourceware.org Received: from nitzan.inter.net.il (HELO nitzan.inter.net.il) (213.8.233.22) by sourceware.org (qpsmtpd/0.31) with ESMTP; Sat, 01 Sep 2007 07:56:30 +0000 Received: from HOME-C4E4A596F7 (IGLD-80-230-59-157.inter.net.il [80.230.59.157]) by nitzan.inter.net.il (MOS 3.7.3a-GA) with ESMTP id HRL23220 (AUTH halo1); Sat, 1 Sep 2007 10:53:41 +0300 (IDT) Date: Sat, 01 Sep 2007 07:56:00 -0000 Message-Id: From: Eli Zaretskii To: Vladimir Prus CC: gdb-patches@sources.redhat.com In-reply-to: <200708312252.47584.ghost@cs.msu.su> (message from Vladimir Prus on Fri, 31 Aug 2007 22:52:47 +0400) Subject: Re: -var-info-path-expression Reply-to: Eli Zaretskii References: <200708221523.32773.ghost@cs.msu.su> <200708311357.04490.ghost@cs.msu.su> <200708312252.47584.ghost@cs.msu.su> X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2007-09/txt/msg00000.txt.bz2 > From: Vladimir Prus > Date: Fri, 31 Aug 2007 22:52:47 +0400 > Cc: gdb-patches@sources.redhat.com > > > > +For example, if @var{a} is an array, and variable object > > > +@var{A} was created for @var{a}, then we'll get this output: > > > > It's wrong to use @var in this context: here, `a' and `A' are literal > > symbols, they do not stand for something else. So you should use > > @code, not @var. > > So, @var is not for programming language variables (like docbook's varname), > but rather a placeholder (like docbook's replaceable)? Yes, it's a placeholder. It's for the cases when you want to say things like frobnicate FILE and FILE is to be replaced by an actual filename when this command is used. There's one borderline case where @var is used, although you could have said that its argument is not a placeholder: when you describe a prototype of a function: int foo (char *bar, struct something *baz); (This example is for C/C++, but similar examples exist in other languages that support functions with arguments.) The Texinfo @def* constructs render the arguments in the @var typeface, for example. In these cases, we will give "bar" and "baz" the @var markup, because they are formal parameters of the function, and will be replaced by something else when the function is actually called. The tricky aspect of this is that when you describe the parameters from _outside_ of the function, e.g. tell someone how to call it, you should use @var, while for the description of the _inside_, like when you tell how it works and cite certain parts of its code, those same symbols should be in @code, because inside the function they are literal symbols. It is these borderline cases, as well as the name of the markup (which mentally reminds you of the word "variable"), which cause confusion about its usage.