Should we use `symbol' or 'symbol' in Emacs change logs?

Should we use `symbol' or 'symbol' in Emacs change logs?

[Bastien]

Achim pointed to a recent change about quotes in the GNU coding
standards, and suggests that the change justifies using 'symbol'
instead of `symbol' in Emacs change logs.

http://www.gnu.org/prep/standards/standards.html#index-left-quote

To me, this is about the way GNU programs output the quote char,
not about conventions for symbols used within the program, so my
reading is that Emacs change logs should stick on using `symbol'
rather than 'symbol'.

This seems to be confirmed by the fact that lisp-mode.el still
highlight `symbol' with `font-lock-constant-face'.

Am I reading it wrong or am I correct that there is no change
in Emacs policy regarding the quotation of symbols in change logs
(and in docstrings)?

Thanks,

-- 
 Bastien

Re: Should we use `symbol' or 'symbol' in Emacs change logs?

[Stefan Monnier]

> Am I reading it wrong or am I correct that there is no change
> in Emacs policy regarding the quotation of symbols in change logs
> (and in docstrings)?

Indeed there's been no change in that policy.  To the extent that we
follow the GNU coding standard for the ChangeLogs, you could argue that
we should use 'foo' in ChangeLogs, but the `...' convention is so
pervasive inside Emacs that we'd then either have a mix of conventions
(one for the ChangeLog and another for most everything else) or a major
painful conversion ahead.


        Stefan

Re: Should we use `symbol' or 'symbol' in Emacs change logs?

[Bastien]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> Am I reading it wrong or am I correct that there is no change
>> in Emacs policy regarding the quotation of symbols in change logs
>> (and in docstrings)?
>
> Indeed there's been no change in that policy.  To the extent that we
> follow the GNU coding standard for the ChangeLogs, you could argue that
> we should use 'foo' in ChangeLogs, but the `...' convention is so
> pervasive inside Emacs that we'd then either have a mix of conventions
> (one for the ChangeLog and another for most everything else) or a major
> painful conversion ahead.

Okay, thanks for confirming!

-- 
 Bastien

Re: Should we use `symbol' or 'symbol' in Emacs change logs?

[Achim Gratz]

Stefan Monnier writes:
>> Am I reading it wrong or am I correct that there is no change
>> in Emacs policy regarding the quotation of symbols in change logs
>> (and in docstrings)?
>
> Indeed there's been no change in that policy.  To the extent that we
> follow the GNU coding standard for the ChangeLogs, you could argue that
> we should use 'foo' in ChangeLogs, but the `...' convention is so
> pervasive inside Emacs that we'd then either have a mix of conventions
> (one for the ChangeLog and another for most everything else) or a major
> painful conversion ahead.

Then you might want to document it somewhere and/or do something about:

https://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html

which suggests otherwise in the examples (including not using quotes
when there is no ambiguity).


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

SD adaptation for Waldorf rackAttack V1.04R1:
http://Synth.Stromeko.net/Downloads.html#WaldorfSDada

Re: Should we use `symbol' or 'symbol' in Emacs change logs?

[Glenn Morris]

Achim Gratz wrote:

> Then you might want to document it somewhere

Bam, done in trunk r117195.

(Personally I think "every existing ChangeLog in Emacs" was
documentation enough.)

Re: Should we use `symbol' or 'symbol' in Emacs change logs?

[Stefan Monnier]

> (Personally I think "every existing ChangeLog in Emacs" was
> documentation enough.)

Agreed.  And if someone happens to use 'foo' in a ChangeLog entry, the
world won't fall apart (at least, not immediately).


        Stefan

Re: Should we use `symbol' or 'symbol' in Emacs change logs?

[Bastien]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> Agreed.  And if someone happens to use 'foo' in a ChangeLog entry, the
> world won't fall apart (at least, not immediately).

Ah!  Cancelling my flight to Mars now.

-- 
 Bastien

Re: Should we use `symbol' or 'symbol' in Emacs change logs?

[Paul Eggert]

On 05/29/2014 01:26 PM, Stefan Monnier wrote:
> if someone happens to use 'foo' in a ChangeLog entry, the
> world won't fall apart (at least, not immediately).

'foo' is quite common in Emacs ChangeLogs nowadays.  For example, in 
src/ChangeLog's most recent ten entries that use single quotes, seven 
quote 'like this' and three quote `like this'.  We shouldn't insist on 
the latter style.

Re: Should we use `symbol' or 'symbol' in Emacs change logs?

[Achim Gratz]

Glenn Morris <rgm <at> gnu.org> writes:
> > Then you might want to document it somewhere
>
> Bam, done in trunk r117195.

Thanks.

> (Personally I think "every existing ChangeLog in Emacs" was
> documentation enough.)

If that was indeed so clear cut, I wouldn't have asked.


Regards,
Achim.