Re: master 95e8c7d 1/2: ; Fix typos

Re: master 95e8c7d 1/2: ; Fix typos

[Robert Pluim]

>>>>> On Fri,  9 Oct 2020 09:42:51 -0400 (EDT), stefankangas@gmail.com (Stefan Kangas) said:

    Stefan>  (defmacro semantic-parse-tree-unparseable ()
    Stefan> -  "Indicate that the current buffer is unparseable.
    Stefan> +  "Indicate that the current buffer is unparsable.
    Stefan>  It is also true that the parse tree will need either updating or
    Stefan>  a rebuild.  This state will be changed when the user edits the buffer."
    Stefan>    '(setq semantic-parse-tree-state 'unparseable))
 
    Stefan>  (defmacro semantic-parse-tree-unparseable-p ()
    Stefan> -  "Return non-nil if the current buffer has been marked unparseable."
    Stefan> +  "Return non-nil if the current buffer has been marked unparsable."
    Stefan>    '(eq semantic-parse-tree-state 'unparseable))

The highly accurate method of googling both and comparing the counts
is not in favour of this change. The principle of making the
documentation and the code align is *definitely* not in favour of this
change.

Robert
-- 

Re: master 95e8c7d 1/2: ; Fix typos

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Date: Fri, 09 Oct 2020 15:57:35 +0200
> Cc: Stefan Kangas <stefan@marxist.se>
> 
> >>>>> On Fri,  9 Oct 2020 09:42:51 -0400 (EDT), stefankangas@gmail.com (Stefan Kangas) said:
> 
>     Stefan>  (defmacro semantic-parse-tree-unparseable ()
>     Stefan> -  "Indicate that the current buffer is unparseable.
>     Stefan> +  "Indicate that the current buffer is unparsable.
>     Stefan>  It is also true that the parse tree will need either updating or
>     Stefan>  a rebuild.  This state will be changed when the user edits the buffer."
>     Stefan>    '(setq semantic-parse-tree-state 'unparseable))
>  
>     Stefan>  (defmacro semantic-parse-tree-unparseable-p ()
>     Stefan> -  "Return non-nil if the current buffer has been marked unparseable."
>     Stefan> +  "Return non-nil if the current buffer has been marked unparsable."
>     Stefan>    '(eq semantic-parse-tree-state 'unparseable))
> 
> The highly accurate method of googling both and comparing the counts
> is not in favour of this change. The principle of making the
> documentation and the code align is *definitely* not in favour of this
> change.

See also

  https://en.wiktionary.org/wiki/parsable

Re: master 95e8c7d 1/2: ; Fix typos

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>>     Stefan>  (defmacro semantic-parse-tree-unparseable-p ()
>>     Stefan> -  "Return non-nil if the current buffer has been marked unparseable."
>>     Stefan> +  "Return non-nil if the current buffer has been marked unparsable."
>>     Stefan>    '(eq semantic-parse-tree-state 'unparseable))
>>
>> The highly accurate method of googling both and comparing the counts
>> is not in favour of this change. The principle of making the
>> documentation and the code align is *definitely* not in favour of this
>> change.
>
> See also
>
>   https://en.wiktionary.org/wiki/parsable

From that link:

    Both the spellings parsable and parseable are widely used with
    similar frequency; the spelling parsable (without the ‘e’) is
    preferred in formal usage, according to the rule:

    “Verbs drop silent final -e except after c and g (e.g. movable but
    changeable)”

    as mentioned in the OED, and used in World Wide Web Consortium
    standards.

But it is true that it would be preferable if the code matched the
documentation.  In the interest of consistency we are better off
sticking to one spelling.  Note that we already had around 40 other
instances of "parsable" in our source tree.

This is obviously extremely minor.  Personally I'd rather fix the names
of those two macros to match the docstring.  IIUC, an obsolete function
alias would do the job.

RE: master 95e8c7d 1/2: ; Fix typos

[Drew Adams]

> But it is true that it would be preferable if the code matched the
> documentation.  In the interest of consistency we are better off
> sticking to one spelling.  Note that we already had around 40 other
> instances of "parsable" in our source tree.
> 
> This is obviously extremely minor.  Personally I'd rather fix the names
> of those two macros to match the docstring.  IIUC, an obsolete function
> alias would do the job.

My 2 cents: Unless the code you want to rename
is brand new - never been released as part of
an Emacs release, please don't change the names
in the code.  And when you refer to those code
names in the doc, use the actual code names.

If you otherwise use the _word_ then use whatever you want.

This kind of gratuitous name change is anathema.
It's all the more silly since both names are
acceptable as English words.

Code names should be understandable.  Other
things being equal they should also be relatively
consistent.  But they need not correspond exactly,
in general, with natural language words.

The main point is not to break existing code.
Especially gratuitously.

Re: master 95e8c7d 1/2: ; Fix typos

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Fri, 9 Oct 2020 21:01:42 +0000
> Cc: emacs-devel@gnu.org
> 
> But it is true that it would be preferable if the code matched the
> documentation.  In the interest of consistency we are better off
> sticking to one spelling.  Note that we already had around 40 other
> instances of "parsable" in our source tree.

Since renaming symbols involves some pain, do we really need to be
100% consistent here?

Re: master 95e8c7d 1/2: ; Fix typos

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> But it is true that it would be preferable if the code matched the
>> documentation.  In the interest of consistency we are better off
>> sticking to one spelling.  Note that we already had around 40 other
>> instances of "parsable" in our source tree.
>
> Since renaming symbols involves some pain, do we really need to be
> 100% consistent here?

I personally don't have a very strong opinion either way, FWIW.

Re: master 95e8c7d 1/2: ; Fix typos

[Robert Pluim]

>>>>> On Sat, 10 Oct 2020 01:14:40 -0700, Stefan Kangas <stefan@marxist.se> said:

    Stefan> Eli Zaretskii <eliz@gnu.org> writes:
    >>> But it is true that it would be preferable if the code matched the
    >>> documentation.  In the interest of consistency we are better off
    >>> sticking to one spelling.  Note that we already had around 40 other
    >>> instances of "parsable" in our source tree.
    >> 
    >> Since renaming symbols involves some pain, do we really need to be
    >> 100% consistent here?

    Stefan> I personally don't have a very strong opinion either way, FWIW.

I think I prefer consistency between the docstrings and the associated
code to global consistency, and changing code is always risky, so Iʼd
prefer if the docstrings were changed back.

Robert
-- 

Re: master 95e8c7d 1/2: ; Fix typos

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: Eli Zaretskii <eliz@gnu.org>,  emacs-devel@gnu.org
> Date: Mon, 12 Oct 2020 10:19:34 +0200
> 
>     >> Since renaming symbols involves some pain, do we really need to be
>     >> 100% consistent here?
> 
>     Stefan> I personally don't have a very strong opinion either way, FWIW.
> 
> I think I prefer consistency between the docstrings and the associated
> code to global consistency, and changing code is always risky, so Iʼd
> prefer if the docstrings were changed back.

I tend to agree.

Re: master 95e8c7d 1/2: ; Fix typos

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>>     >> Since renaming symbols involves some pain, do we really need to be
>>     >> 100% consistent here?
>>
>>     Stefan> I personally don't have a very strong opinion either way, FWIW.
>>
>> I think I prefer consistency between the docstrings and the associated
>> code to global consistency, and changing code is always risky, so Iʼd
>> prefer if the docstrings were changed back.
>
> I tend to agree.

OK, I've now reverted that part on master.