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

[MON KEY <monkey@sandpframing.com>]

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\