elementary: how to display a ' in a docstring

elementary: how to display a ' in a docstring

[Uwe Brauer]

Hello

Sorry for this elementary question
But I would like to modify a doc string of a variable such that it
displays:

Please set
vc-hg-symbolic-revision-styles to '("{rev}").

So I tried

"Please set
`vc-hg-symbolic-revision-styles' to '(\"{rev}\"))), please note the `''."

But when I use describe variable, the ' of  '(\"{rev}\"))) is not
correctly displayed.

What shall I do? 
thanks

Uwe Brauer 

Re: elementary: how to display a ' in a docstring

[Paul Eggert]

Uwe Brauer wrote:
> "Please set `vc-hg-symbolic-revision-styles' to '(\"{rev}\"))), please note the `''."

To get the effect you asked for, quote the apostrophes like this: "Please set
`vc-hg-symbolic-revision-styles' to \\='(\"{rev}\"))), please note the `\\=''."
See the text-quoting-style documentation in the Elisp manual.

By the way, the effect you asked for is not the recommended style in Emacs
documentation strings. When discussing a Lisp value, the usual style is to give
the value instead of Lisp code that would evaluate to the value. The
abovementioned doc string could be reworded to something like "Please set
`vc-hg-symbolic-revision-styles' to the list (\"{rev}\")."

Re: elementary: how to display a ' in a docstring

[Uwe Brauer]

>>> "Paul" == Paul Eggert <eggert@cs.ucla.edu> writes:

   > Uwe Brauer wrote:
   >> "Please set `vc-hg-symbolic-revision-styles' to '(\"{rev}\"))),
   >> please note the `''."

   > To get the effect you asked for, quote the apostrophes like this:
   > "Please set `vc-hg-symbolic-revision-styles' to \\='(\"{rev}\"))),
   > please note the `\\=''." See the text-quoting-style documentation
   > in the Elisp manual.

thanks


   > By the way, the effect you asked for is not the recommended style in Emacs
   > documentation strings. When discussing a Lisp value, the usual style is to give
   > the value instead of Lisp code that would evaluate to the value. The
   > abovementioned doc string could be reworded to something like "Please set
   > `vc-hg-symbolic-revision-styles' to the list (\"{rev}\")."

I am now confused. Are you saying that the setting


(setq  vc-hg-symbolic-revision-styles '("{rev}"))

Is incorrect?

What would be then correct? I am not sure that I understand your
proposed wording.

(setq  vc-hg-symbolic-revision-styles (list '("{rev}")))

Is not correct. So I am puzzled.

Re: elementary: how to display a ' in a docstring

[Paul Eggert]

Uwe Brauer wrote:

> Are you saying that the setting
> 
> (setq  vc-hg-symbolic-revision-styles '("{rev}"))
> 
> Is incorrect?

No, because that setq form is a Lisp expression, and in Lisp the expression 'V
yields the value V, which means that the form sets the variable
vc-hg-symbolic-revision-styles to the value ("{rev}").

Quoting works for any value in Lisp code. Although there are common special
cases (e.g., integers) where the single-quote is not needed, in Lisp a
single-quote is the easiest way to quote an arbitrary value.

Re: elementary: how to display a ' in a docstring

[Uwe Brauer]

   > Uwe Brauer wrote:

   > No, because that setq form is a Lisp expression, and in Lisp the expression 'V
   > yields the value V, which means that the form sets the variable
   > vc-hg-symbolic-revision-styles to the value ("{rev}").

   > Quoting works for any value in Lisp code. Although there are common special
   > cases (e.g., integers) where the single-quote is not needed, in Lisp a
   > single-quote is the easiest way to quote an arbitrary value.

Ok but you complained, or seemed to complained that it is not good
style. So what is the recommended setting in the case I mentioned?

Re: elementary: how to display a ' in a docstring

[Paul Eggert]

Uwe Brauer wrote:
> Ok but you complained, or seemed to complained that it is not good
> style. So what is the recommended setting in the case I mentioned?

If the suggested value is the singleton list ("{rev}"), then (setq
vc-hg-symbolic-revision-styles '("{rev}")) is a Lisp expression that sets the
variable to the suggested value. As that is the expression you already
mentioned, your code should be OK already.

My quibble was with the doc string you suggested. In a doc string generally the
simplest way to discuss a cons value like ("{rev}") is to write the value
without quoting it. In the rare cases where this is unclear, you can quote the
value the same way you would quote a symbol or any other piece of Lisp code in a
doc string, namely by surrounding it with ` and '.