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

[Stefan Monnier <monnier@iro.umontreal.ca>]

> 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