bug#6525: documentation of macro `with-silent-modifications' 1 typo + multi-horrid

bug#6525: documentation of macro `with-silent-modifications' 1 typo + multi-horrid

[MON KEY]

documentation of macro `with-silent-modifications' lisp/subr.el
current through Bzr-100654

There is a typo @ "... does not modifies the buffer."
should be "... does not modify the buffer."

More generally the docstring is bordering on non-sensical.

,---- (documentation 'with-silent-modifications)
|
| "Execute BODY, pretending it does not modifies the buffer.
| If BODY performs real modifications to the buffer's text, other than
| cosmetic ones, undo data may become corrupted.  Typically used
| around modifications of text-properties which do not really affect
| the buffer's content."
|
`----


Execute BODY, pretending it does not modifies the buffer.
^^^^^^^^^^^^^^|^^^^^^^^^^^^^^^^^^^^^ modify ^^^^^^|^^^^^
        what is a `pretend'                   which buffer?

If BODY performs real modifications to the buffer's text, other than
^^^^^^^^^^^^^^^^^|^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^|^^^^^^^^^^^^^^
    what is a non-real mod?                         ???

cosmetic ones, undo data may become corrupted.  Typically used
^^^|^^^^^^^^^^^^^^^^^^|^^^^^^^^^^^^^^^^^^^^^^^^^|^^^^^^^^^^^^^
what is non-cosmetic? |             what is an atypical usage?
                      |
         why not say `buffer-undo-list'?

around modifications of text-properties which do not really affect
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^|^^^^^^^^^^^^^^^^^^^^^^^^^
                         what is the affector txt-prop or the mod?
the buffer's content.
^^^^^^^^^^^^^|^^^^^^
   exactly what _is_ content - chars, tps, overlays, fields, faces?

--
/s_P\

bug#6525: documentation of macro `with-silent-modifications' 1 typo + multi-horrid

[Stefan Monnier]

> cosmetic ones, undo data may become corrupted.  Typically used
> ^^^|^^^^^^^^^^^^^^^^^^|^^^^^^^^^^^^^^^^^^^^^^^^^|^^^^^^^^^^^^^
> what is non-cosmetic? |             what is an atypical usage?
>                       |
>          why not say `buffer-undo-list'?

Docstrings should generally only document what the function/macro does,
rather than how they're used.  So the "typical uses" I put here is
actually a bad idea, tho it was just easier to do that than to try and
describe what the macro does, especially since it's really the use for
which it's designed.  I don't know what atypical uses might be, and
don't care about them (at least until they come complaining about some
undesirable part of the behavior).

> around modifications of text-properties which do not really affect
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^|^^^^^^^^^^^^^^^^^^^^^^^^^
>                          what is the affector txt-prop or the mod?

Some other code: the caller would presumably know.

> the buffer's content.
> ^^^^^^^^^^^^^|^^^^^^
>    exactly what _is_ content - chars, tps, overlays, fields, faces?

Can be any of it, depending on the case, because it's a conceptual
notion, rather than a technical one: typically "modify the buffer's
content" means "saving the buffer results in a different file".


        Stefan

bug#6525: documentation of macro `with-silent-modifications' 1 typo + multi-horrid

[MON KEY]

On Wed, Jun 30, 2010 at 9:10 PM, Stefan Monnier
<monnier@iro.umontreal.ca> wrote:

>> ,---- (documentation 'with-silent-modifications)
>> |
>> | "Execute BODY, pretending it does not modifies the buffer.
>> | If BODY performs real modifications to the buffer's text, other than
>> | cosmetic ones, undo data may become corrupted.  Typically used
>> | around modifications of text-properties which do not really affect
>> | the buffer's content."
>> |
>> `----

> Docstrings should generally only document what the function/macro
> does, rather than how they're used.  So the "typical uses" I put
> here is actually a bad idea, tho it was just easier to do that than
> to try and describe what the macro does, {...}

Indeed, this may be so, but it certainly isn't any easier for me to
understand what it does.

I absolutely can not understand what is meant by the docstring.

Though, really, I typically do pretend at understanding these types of
things unless the content is not other than cosmetic such that it can
not perform any real modifications affecting my perspective of these
things :-P

> I don't know what atypical uses might be, and don't care about them

If it has typical usage then it has atypical usage. Presumably that
the macro exists suggests that there is a typical usage.  The macro
would go away if it didn't have a typical usage. That it doesn't
suggests  _someone_ cares about partitioning the typical from the
atypical usage whether you do or not.

If such usage is typical enough so as to support creation of the macro
it would seem reasonable to expect a resasonable documentation of what
it should be expected to do -- and, it should say so without over
reliance on vacuous terms like `pretending', `really', `typically',
`cosmetic', `real modifications', `content' etc.

> (at least until they come complaining about some undesirable part of
> the behavior).

Thats a nice long rope you've given users.
Maybe they get lost at the outer regions of that tether in which case
they aren't likely to come complaining...

What behaviour would you expect them to complain about if they can not
deduce from the docstring what it is they should expect this macro to
do?

>> around modifications of text-properties which do not really affect
>> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^|^^^^^^^^^^^^^^^^^^^^^^^^^
>>                          what is the affector txt-prop or the mod?
>
> Some other code: the caller would presumably know.

How could a caller modify text-properties which do not _really_ affect
the buffer? They either do affect whehter the buffer is modified or
they don't.

More precisely, what are the text-properties that do not _really_
affect a/the buffer?

>> the buffer's content.
>> ^^^^^^^^^^^^^|^^^^^^
>>    exactly what _is_ content - chars, tps, overlays, fields, faces?
>
> Can be any of it, depending on the case, because it's a conceptual

Whose conceptual notion, the callers, yours, or Emacs' vis a vis
`buffer-modified-p'?

> notion, rather than a technical one: typically "modify the buffer's
> content" means "saving the buffer results in a different file".

The use of `content' here is not good. The term is too "conceptually"
overloaded to be of any use in the context of which it is used.

>        Stefan

---
/s_P

bug#6525: documentation of macro `with-silent-modifications' 1

[Stefan Monnier]

> I absolutely can not understand what is meant by the docstring.

Here's an another try:

  Run BODY normally, but don't count its buffer modifications as being
  buffer modifications.
  This affects things like buffer-modified-p, checking whether the file
  is locked by someone else, running buffer modification hooks, ...

> What behaviour would you expect them to complain about if they can not
> deduce from the docstring what it is they should expect this macro to
> do?

No idea.  They'd make up their own idea of what the macro does, then
find it doesn't perform as they expect it, and they complain.  That will
either let us fix the macro to better reflect their understanding, or
improve the docstring to avoid the confusion.

>>> the buffer's content.
>>> ^^^^^^^^^^^^^|^^^^^^
>>> exactly what _is_ content - chars, tps, overlays, fields, faces?
>> Can be any of it, depending on the case, because it's a conceptual
> Whose conceptual notion, the callers, yours, or Emacs' vis a vis
> `buffer-modified-p'?

The conceptual notion of the guy who decides to use this macro.
In a sense, the use of the macro is a way for the programmer to tell
Emacs what is "a real modification" (it does it by telling: anything
that happens within BODY is not "a real modification").


        Stefan

bug#6525: documentation of macro `with-silent-modifications' 1

[MON KEY]

On Sun, Jul 4, 2010 at 1:21 PM, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
>> I absolutely can not understand what is meant by the docstring.
>
> Here's an another try:
>
>  Run BODY normally, but don't count its buffer modifications as being
>  buffer modifications.
>  This affects things like buffer-modified-p, checking whether the file
>  is locked by someone else, running buffer modification hooks, ...
>

How about this:

Evaluate BODY with any changes which would otherwise set the buffer
as modified discarded such that buffer changes within BODY:
- will not satisfy the `buffer-modified-p' predicate;
- will not clobber the `buffer-undo-list';
- will not cause a mode-line update as per `set-buffer-modified-p';
- will not trigger running of modification-hooks which respond to
  buffer changes including `before-change-functions' and
  `after-change-functions';
- will not force redisplay around modifications of buffer text
  having text-property and overlay hooks;
- will not trigger buffer related file-locking and unlocking.

>> What behaviour would you expect them to complain about if they can not
>> deduce from the docstring what it is they should expect this macro to
>> do?
>
> No idea.  They'd make up their own idea of what the macro does, then
> find it doesn't perform as they expect it, and they complain.  That will
> either let us fix the macro to better reflect their understanding, or
> improve the docstring to avoid the confusion.
>

My old man calls me last night w/ a problem:

 "How do I get my back arrow back. Firefox lost it."

He made his own mind up what the problem was... but Firefox wasn't
broken it just didn't perform as expcected when he toggled the GUI
navigation checkbox of his nav bar.

I can't imagine it being a very good idea to expect uniformed users to
inform you as to how to tweak a macro they neither understand (or
otherwise endow with exceptionally magical powers) any more than I
can imagine letting me father direct the Mozilla project according to his
design spec :)

:SEE (URL `http://www.joelonsoftware.com/articles/fog0000000356.html')

>
> The conceptual notion of the guy who decides to use this macro.
> In a sense, the use of the macro is a way for the programmer to tell
> Emacs what is "a real modification" (it does it by telling: anything
> that happens within BODY is not "a real modification").
>

That explanation made perfect sense for me. Thank you.

>
>        Stefan
>

--
/s_P\

bug#6525: documentation of macro `with-silent-modifications' 1

[Lars Magne Ingebrigtsen]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

> Here's an another try:
>
>   Run BODY normally, but don't count its buffer modifications as being
>   buffer modifications.
>   This affects things like buffer-modified-p, checking whether the file
>   is locked by someone else, running buffer modification hooks, ...

I've installed a version of this now.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/