Q: text-quoting-style -- is its value a string or a symbol?

Q: text-quoting-style -- is its value a string or a symbol?

[T.V Raman]

Reading the online documentation for text-quoting-style --- it's hard
to tell if the expected value is a string or a symbol.
-- 

-- 

Re: Q: text-quoting-style -- is its value a string or a symbol?

[Xue Fuqiao]

On Tue, Nov 24, 2015 at 7:40 AM, T.V Raman <raman@google.com> wrote:
> Reading the online documentation for text-quoting-style --- it's hard
> to tell if the expected value is a string or a symbol.

A symbol.

In (info "(elisp) Keys in Documentation"):

   To use the traditional `grave' style, put the line `(setq
   text-quoting-style 'grave)' into your `~/.emacs' file.

Re: Q: text-quoting-style -- is its value a string or a symbol?

[T.V Raman]

I did a describe-variable of text-quoting-style and got confused.

Xue Fuqiao writes:
 > On Tue, Nov 24, 2015 at 7:40 AM, T.V Raman <raman@google.com> wrote:
 > > Reading the online documentation for text-quoting-style --- it's hard
 > > to tell if the expected value is a string or a symbol.
 > 
 > A symbol.
 > 
 > In (info "(elisp) Keys in Documentation"):
 > 
 >    To use the traditional `grave' style, put the line `(setq
 >    text-quoting-style 'grave)' into your `~/.emacs' file.

-- 

-- 

Re: Q: text-quoting-style -- is its value a string or a symbol?

[Eli Zaretskii]

> From: raman@google.com (T.V Raman)
> Date: Mon, 23 Nov 2015 16:25:14 -0800
> Cc: emacs-devel@gnu.org, raman@google.com
> 
> I did a describe-variable of text-quoting-style and got confused.

Why was it confusing?  How do you expect to see strings vs symbols in
doc strings?

Re: Q: text-quoting-style -- is its value a string or a symbol?

[raman]

Eli Zaretskii <eliz@gnu.org> writes:

The quoting convention is confusing enough that at this point I just
want it to say "it's value is a symbol" or "it's value is a string".

Here, I am specifically refering to  what is shown in the help buffer
for describe-variable text-quoting-style>> From: raman@google.com (T.V Raman)
>> Date: Mon, 23 Nov 2015 16:25:14 -0800
>> Cc: emacs-devel@gnu.org, raman@google.com
>> 
>> I did a describe-variable of text-quoting-style and got confused.
>
> Why was it confusing?  How do you expect to see strings vs symbols in
> doc strings?

-- 

Re: Q: text-quoting-style -- is its value a string or a symbol?

[Eli Zaretskii]

> From: raman <raman@google.com>
> Cc: xfq.free@gmail.com,  emacs-devel@gnu.org
> Date: Mon, 23 Nov 2015 19:44:57 -0800
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> The quoting convention is confusing enough that at this point I just
> want it to say "it's value is a symbol" or "it's value is a string".

The question is, is something different about that particular doc
string as opposed to other doc strings which document symbol values?
If there's nothing different, you are supposed to have the same
problem with all the other doc strings, and we should either change
all of them, or none at all.

Re: Q: text-quoting-style -- is its value a string or a symbol?

[raman]

Eli Zaretskii <eliz@gnu.org> writes:
Let me ask you the question in reverse -- what in that *help* buffer
tells you that this is a string and not a symbol?

Also, this is not the first time a problem is being dismissed as "it
exists elsewhere so it's not a problem"  that in general is more likely
to turn away contributors to the project than anything else.
>> From: raman <raman@google.com>
>> Cc: xfq.free@gmail.com,  emacs-devel@gnu.org
>> Date: Mon, 23 Nov 2015 19:44:57 -0800
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> The quoting convention is confusing enough that at this point I just
>> want it to say "it's value is a symbol" or "it's value is a string".
>
> The question is, is something different about that particular doc
> string as opposed to other doc strings which document symbol values?
> If there's nothing different, you are supposed to have the same
> problem with all the other doc strings, and we should either change
> all of them, or none at all.

-- 

Re: Q: text-quoting-style -- is its value a string or a symbol?

[Eli Zaretskii]

> From: raman <raman@google.com>
> Cc: xfq.free@gmail.com,  emacs-devel@gnu.org
> Date: Tue, 24 Nov 2015 08:21:37 -0800
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> Let me ask you the question in reverse -- what in that *help* buffer
> tells you that this is a string and not a symbol?

It doesn't.  It tells me it's a symbol.  Why? because of the way it is
quoted: with single quotes, not double quotes.  Single quotes is how
we mark symbols in doc strings.

> Also, this is not the first time a problem is being dismissed as "it
> exists elsewhere so it's not a problem"  that in general is more likely
> to turn away contributors to the project than anything else.

I'm sorry, but where do you see a dismissal?  I was saying that if
there is a problem with that doc string, it exists with many more.

Re: Q: text-quoting-style -- is its value a string or a symbol?

[John Wiegley]

>>>>> Eli Zaretskii <eliz@gnu.org> writes:

> It doesn't. It tells me it's a symbol. Why? because of the way it is quoted:
> with single quotes, not double quotes. Single quotes is how we mark symbols
> in doc strings.

Raman, When you say "reading the online documentation" in your original
report, do you mean the *Help* text, or the HTML generated for the manual? I
want to be sure we're all talking about the same thing.

If you see `foo' written (for example, in *Help*), it is always a symbol
(using either those characters, or fancy Unicode single quotes). As Eli says,
double-quotes are used to denote strings.

John

Re: Q: text-quoting-style -- is its value a string or a symbol?

[T.V Raman]

John I meant the *Help* buffer text.

I guess I got confused because with the new quoting strategy I had a
hard time distinguishing the symbol vs string quoting styles ---
partly because of the way I've defined the mapping from various quote
characters to text-to-speech.
That the prose itself has the word "quote" appearing in it makes the
entire thing a completely confusing experience when you hear it
spoken:-) -- though some of that is understandably unavoidable.

But the fact remains, the distinction is subtle -- and if it's not
obvious to someone who has used Emacs for 20 years, then it's not
going to be obvious to at least some number of users. From that
perspective, I find the response "that  is how it is everywhere -- get
used to it -- or alternatively first go change it everywhere else" somewhat unproductive.


I'll attach the *help* buffer text as it shows in my running Emacs-25
session so we are all talking of the same thing.

And now that I've set it to the symbol 'grave, notice how it shows in
the *help* buffer -- at least as I hear it, it's got no quotes around
it whatsoever. So there is asymmetry here with respect to how one sees
a symbol value displayed in the help buffer vs how a symbol value is
documented in the help-buffer text.

If you read it by itself, you'll still not know how to distinguish
symbols from strings in  the *HElp* buffer unless you bring up Help
for two separate variables, one that takes a string value  and the
other a symbol-value -- and then display the *help* buffer for each
side-by-side. 

Help-Buffer text follows:

text-quoting-style is a variable defined in `C source code'.
Its value is grave

Documentation:
Style to use for single quotes when generating text.
`curve' means quote with curved single quotes ‘like this’.
`straight' means quote with straight apostrophes 'like this'.
`grave' means quote with grave accent and apostrophe `like this'.
The default value nil acts like `curve' if curved single quotes are
displayable, and like `grave' otherwise.

[back]

John Wiegley writes:
 > >>>>> Eli Zaretskii <eliz@gnu.org> writes:
 > 
 > > It doesn't. It tells me it's a symbol. Why? because of the way it is quoted:
 > > with single quotes, not double quotes. Single quotes is how we mark symbols
 > > in doc strings.
 > 
 > Raman, When you say "reading the online documentation" in your original
 > report, do you mean the *Help* text, or the HTML generated for the manual? I
 > want to be sure we're all talking about the same thing.
 > 
 > If you see `foo' written (for example, in *Help*), it is always a symbol
 > (using either those characters, or fancy Unicode single quotes). As Eli says,
 > double-quotes are used to denote strings.
 > 
 > John

-- 

--

Re: Q: text-quoting-style -- is its value a string or a symbol?

[Paul Eggert]

On 11/24/2015 03:38 PM, T.V Raman wrote:
> I'll attach the*help*  buffer text as it shows in my running Emacs-25
> session so we are all talking of the same thing.

The current emacs-25 should show a slightly different help buffer. 
Assuming your (setq text-quoting-style 'grave), the help buffer should 
look like this:


text-quoting-style is a variable defined in `C source code'.
Its value is grave

Documentation:
Style to use for single quotes in help and messages.
Its value should be a symbol.
`curve' means quote with curved single quotes ‘like this’.
`straight' means quote with straight apostrophes 'like this'.
`grave' means quote with grave accent and apostrophe `like this'.
The default value nil acts like `curve' if curved single quotes are
displayable, and like `grave' otherwise.

[back]


I didn't quite follow your email, but are you suggesting that the second 
line should look like this instead?


Its value is `grave'


and that would suffice to fix the problem that you see?  If so, this 
should be easy to arrange.

Re: Q: text-quoting-style -- is its value a string or a symbol?

[T.V Raman]

This is much better -- me going away happy. Thanks Paul!


Paul Eggert writes:
 > On 11/24/2015 03:38 PM, T.V Raman wrote:
 > > I'll attach the*help*  buffer text as it shows in my running Emacs-25
 > > session so we are all talking of the same thing.
 > 
 > The current emacs-25 should show a slightly different help buffer. 
 > Assuming your (setq text-quoting-style 'grave), the help buffer should 
 > look like this:
 > 
 > 
 > text-quoting-style is a variable defined in `C source code'.
 > Its value is grave
 > 
 > Documentation:
 > Style to use for single quotes in help and messages.
 > Its value should be a symbol.
 > `curve' means quote with curved single quotes ‘like this’.
 > `straight' means quote with straight apostrophes 'like this'.
 > `grave' means quote with grave accent and apostrophe `like this'.
 > The default value nil acts like `curve' if curved single quotes are
 > displayable, and like `grave' otherwise.
 > 
 > [back]
 > 
 > 
 > I didn't quite follow your email, but are you suggesting that the second 
 > line should look like this instead?
 > 
 > 
 > Its value is `grave'
 > 
 > 
 > and that would suffice to fix the problem that you see?  If so, this 
 > should be easy to arrange.

-- 

--

Re: Q: text-quoting-style -- is its value a string or a symbol?

[T.V Raman]

p.S. Re the asymmetry thought:

I was pointing out that if the reader was to  derive the fact that it
is a symbol from looking at how the quotes are displayed, then we need
to be symmetric in how we display a symbol value --- at least in the
case of this particular variable which is already pretty nuanced with
respect to what it does.

Your having fixed the original issue by adding "it's value is a
symbol" fixes things for me, so the symmetry/asymmetry is a nit at
this point.

Paul Eggert writes:
 > On 11/24/2015 03:38 PM, T.V Raman wrote:
 > > I'll attach the*help*  buffer text as it shows in my running Emacs-25
 > > session so we are all talking of the same thing.
 > 
 > The current emacs-25 should show a slightly different help buffer. 
 > Assuming your (setq text-quoting-style 'grave), the help buffer should 
 > look like this:
 > 
 > 
 > text-quoting-style is a variable defined in `C source code'.
 > Its value is grave
 > 
 > Documentation:
 > Style to use for single quotes in help and messages.
 > Its value should be a symbol.
 > `curve' means quote with curved single quotes ‘like this’.
 > `straight' means quote with straight apostrophes 'like this'.
 > `grave' means quote with grave accent and apostrophe `like this'.
 > The default value nil acts like `curve' if curved single quotes are
 > displayable, and like `grave' otherwise.
 > 
 > [back]
 > 
 > 
 > I didn't quite follow your email, but are you suggesting that the second 
 > line should look like this instead?
 > 
 > 
 > Its value is `grave'
 > 
 > 
 > and that would suffice to fix the problem that you see?  If so, this 
 > should be easy to arrange.

-- 

--

Re: Q: text-quoting-style -- is its value a string or a symbol?

[Paul Eggert]

On 11/24/2015 07:54 AM, Eli Zaretskii wrote:
> is something different about that particular doc
> string as opposed to other doc strings which document symbol values?
Yes, that particular doc string is talking about quoting, so it's 
reasonable for the doc string to go into greater lengths and to say when 
it's quoting symbols as opposed to strings, to help avoid the kind of 
confusion that started this thread. Doc strings that talk about other 
issues don't need to be so careful.

Re: Q: text-quoting-style -- is its value a string or a symbol?

[T.V Raman]

Paul, Thank you for being the essence of sanity as usual -- :-)

Paul Eggert writes:
 > On 11/24/2015 07:54 AM, Eli Zaretskii wrote:
 > > is something different about that particular doc
 > > string as opposed to other doc strings which document symbol values?
 > Yes, that particular doc string is talking about quoting, so it's 
 > reasonable for the doc string to go into greater lengths and to say when 
 > it's quoting symbols as opposed to strings, to help avoid the kind of 
 > confusion that started this thread. Doc strings that talk about other 
 > issues don't need to be so careful.

-- 

-- 

RE: Q: text-quoting-style -- is its value a string or a symbol?

[Drew Adams]

> > Reading the online documentation for text-quoting-style --- it's hard
> > to tell if the expected value is a string or a symbol.
> 
> A symbol.
> 
> In (info "(elisp) Keys in Documentation"):
> 
>    To use the traditional `grave' style, put the line `(setq
>    text-quoting-style 'grave)' into your `~/.emacs' file.

1. Why is this in the node that is about "Substituting Key
   Bindings in Documentation"?  IIUC, this variable is not
   about that topic.  Just because you might make use of this
   variable in the implementation of `substitute-command-keys',
   that is no reason to document it here.

2. What does this mean?

   "the style used to generate text quotes."

   Generate text quotes?  What are "text quotes"?  What
   generates them?  This means nothing, to me.

   And the doc string says something quite different, but
   just as incomprehensible:

   "Style to use for single quotes when generating text."

   Generating text or generating "text quotes" (whatever
   they might be)?  And what or who does this generating?
   And when?  And where is does the generated result
   (whatever it might be) end up?

   The doc for this variable is quite unclear.

3. Why is this not a _user option_, instead of an internal
   variable?  Doesn't it affect what a user sees?  Judging
   by the instructions for a user about how to change the
   behavior, it seems to be something a user can use, to
   change how quoted thingies (whatever the thingies might
   be) are quoted.

   If it should be a user option, please make it so.
   And then please document it in the _Emacs_ manual.  And
   then change the instructions for modifying the behavior
   to mention using Customize, instead of telling users
   to put (setq ...) in their init files.

Re: Q: text-quoting-style -- is its value a string or a symbol?

[Paul Eggert]

Drew Adams wrote:

> 1. Just because you might make use of this
>     variable in the implementation of `substitute-command-keys',
>     that is no reason to document it here.

Where should it be documented?

> 2. What does this mean?

I changed that wording just now to try to clarify it a bit.

> 3. Why is this not a _user option_, instead of an internal
>     variable?

Stefan asked that it not be a custom var; see:

https://lists.gnu.org/archive/html/emacs-devel/2015-08/msg01020.html

Seemed reasonable to me, too. Users who care about this sort of thing tend to be 
experts who don't need handholding.

RE: Q: text-quoting-style -- is its value a string or a symbol?

[Drew Adams]

> > 1. Just because you might make use of this
> >     variable in the implementation of `substitute-command-keys',
> >     that is no reason to document it here.
> 
> Where should it be documented?

In the Emacs manual, IMO.  Where, I don't know.  Perhaps
somewhere where we discuss help display, or whatever this
variable affects.

If this is truly something that programmers of Elisp need to
know, why are we telling them they can change the value by
using `setq' in their init files?  An Elisp programmer knows
how to set a variable value.  We don't make such statements
for other internal variables documentind in the Elisp manual.

But the mention of using `setq' in a users init file really
betrays the fact that this is a user setting, not a programmer
setting.  It should be a user option, IMO.

> > 2. What does this mean?
> 
> I changed that wording just now to try to clarify it a bit.
> 
> > 3. Why is this not a _user option_, instead of an internal
> >    variable?
> 
> Stefan asked that it not be a custom var; see:
> https://lists.gnu.org/archive/html/emacs-devel/2015-08/msg01020.html
> 
> Seemed reasonable to me, too. Users who care about this sort of thing tend
> to be experts who don't need handholding.

1. Customize is not only about non-experts, and it is not about
   hand-holding.  It's too bad that you apparently think it is.  And
   who's to say what "users who care about this" will "tend to be"?
   This is a new feature.  They might "tend to be" anyone.

2. If we are telling users how to change the behavior, by using
   `setq' in their init files, then I think this should be a user
   option.  Whether a user is an "expert" or not is irrelevant to
   our recommending Customize for user settings.

Re: Q: text-quoting-style -- is its value a string or a symbol?

[Paul Eggert]

Drew Adams wrote:
> If we are telling users how to change the behavior, by using
>     `setq' in their init files, then I think this should be a user
>     option.

True, discussing setq is overkill here.  I removed it.  Personally I'd rather 
not have the variable at all (not even for experts), but having a variable is OK 
as a compromise.

RE: Q: text-quoting-style -- is its value a string or a symbol?

[Drew Adams]

> > If we are telling users how to change the behavior, by using
> > `setq' in their init files, then I think this should be a user
> > option.
> 
> True, discussing setq is overkill here.

The point is that mentioning `setq' is less desirable than
mentioning Customize.  The point is not that users do not need to
know how to turn this off.

Clearly, adding the mention of how to change the setting in your
init file was intended to address the need to let users know
about this variable and how they can change it.  That need does
not go away just because `setq' is not the best way to do that.

> I removed it.

A half measure that makes only things worse, if nothing is
added to the user manual to tell users how to change the
behavior.

> Personally I'd rather not have the variable at all (not even
> for experts), but having a variable is OK as a compromise.

A compromise between what you'd "personally" prefer and what
really helps users?  Doesn't sound great, to me "personally".

New, incompatible behavior was introduced.  And some users
have already questioned it or expressed dislike.  We should
give all users, including non-"experts", an easy way to
choose the behavior they prefer.  This calls for making the
variable a user option.  Easy to do.

Re: Q: text-quoting-style -- is its value a string or a symbol?

[Paul Eggert]

On 11/24/2015 06:39 AM, Drew Adams wrote:
> A compromise between what you'd "personally" prefer and what
> really helps users?  Doesn't sound great, to me "personally".
I was merely saying that I agree with Stefan.  You're of course free to 
disagree.

Re: Q: text-quoting-style -- is its value a string or a symbol?

[Eli Zaretskii]

> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Mon, 23 Nov 2015 19:23:54 -0800
> Cc: Emacs-devel <emacs-devel@gnu.org>
> 
> Drew Adams wrote:
> 
> > 1. Just because you might make use of this
> >     variable in the implementation of `substitute-command-keys',
> >     that is no reason to document it here.
> 
> Where should it be documented?

I think it should be a defcustom, and documented in the user manual.

> > 3. Why is this not a _user option_, instead of an internal
> >     variable?
> 
> Stefan asked that it not be a custom var; see:
> 
> https://lists.gnu.org/archive/html/emacs-devel/2015-08/msg01020.html

He also said he hoped we'll delete the variable, so it's not
surprising he didn't want to document it.

Lots of water under the bridge since then, so I think we are not where
we were back then, and the variable cannot be left in its obscurity.