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

[Stefan Monnier <monnier@IRO.UMontreal.CA>]

> 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