* bug#6525: documentation of macro `with-silent-modifications' 1 typo + multi-horrid @ 2010-06-28 7:36 MON KEY 2010-07-01 1:10 ` Stefan Monnier 0 siblings, 1 reply; 6+ messages in thread From: MON KEY @ 2010-06-28 7:36 UTC (permalink / raw) To: 6525 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\ ^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#6525: documentation of macro `with-silent-modifications' 1 typo + multi-horrid 2010-06-28 7:36 bug#6525: documentation of macro `with-silent-modifications' 1 typo + multi-horrid MON KEY @ 2010-07-01 1:10 ` Stefan Monnier 2010-07-01 23:07 ` MON KEY 0 siblings, 1 reply; 6+ messages in thread From: Stefan Monnier @ 2010-07-01 1:10 UTC (permalink / raw) To: MON KEY; +Cc: 6525 > 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#6525: documentation of macro `with-silent-modifications' 1 typo + multi-horrid 2010-07-01 1:10 ` Stefan Monnier @ 2010-07-01 23:07 ` MON KEY 2010-07-04 17:21 ` bug#6525: documentation of macro `with-silent-modifications' 1 Stefan Monnier 0 siblings, 1 reply; 6+ messages in thread From: MON KEY @ 2010-07-01 23:07 UTC (permalink / raw) To: Stefan Monnier; +Cc: 6525 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#6525: documentation of macro `with-silent-modifications' 1 2010-07-01 23:07 ` MON KEY @ 2010-07-04 17:21 ` Stefan Monnier 2010-07-06 21:29 ` MON KEY 2011-07-13 23:40 ` Lars Magne Ingebrigtsen 0 siblings, 2 replies; 6+ messages in thread From: Stefan Monnier @ 2010-07-04 17:21 UTC (permalink / raw) To: MON KEY; +Cc: 6525 > 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#6525: documentation of macro `with-silent-modifications' 1 2010-07-04 17:21 ` bug#6525: documentation of macro `with-silent-modifications' 1 Stefan Monnier @ 2010-07-06 21:29 ` MON KEY 2011-07-13 23:40 ` Lars Magne Ingebrigtsen 1 sibling, 0 replies; 6+ messages in thread From: MON KEY @ 2010-07-06 21:29 UTC (permalink / raw) To: Stefan Monnier; +Cc: 6525 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\ ^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#6525: documentation of macro `with-silent-modifications' 1 2010-07-04 17:21 ` bug#6525: documentation of macro `with-silent-modifications' 1 Stefan Monnier 2010-07-06 21:29 ` MON KEY @ 2011-07-13 23:40 ` Lars Magne Ingebrigtsen 1 sibling, 0 replies; 6+ messages in thread From: Lars Magne Ingebrigtsen @ 2011-07-13 23:40 UTC (permalink / raw) To: Stefan Monnier; +Cc: MON KEY, 6525 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/ ^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2011-07-13 23:40 UTC | newest] Thread overview: 6+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2010-06-28 7:36 bug#6525: documentation of macro `with-silent-modifications' 1 typo + multi-horrid MON KEY 2010-07-01 1:10 ` Stefan Monnier 2010-07-01 23:07 ` MON KEY 2010-07-04 17:21 ` bug#6525: documentation of macro `with-silent-modifications' 1 Stefan Monnier 2010-07-06 21:29 ` MON KEY 2011-07-13 23:40 ` Lars Magne Ingebrigtsen
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).