From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: MON KEY Newsgroups: gmane.emacs.bugs Subject: bug#6525: documentation of macro `with-silent-modifications' 1 typo + multi-horrid Date: Thu, 1 Jul 2010 19:07:14 -0400 Message-ID: References: NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 X-Trace: dough.gmane.org 1278027000 3833 80.91.229.12 (1 Jul 2010 23:30:00 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Thu, 1 Jul 2010 23:30:00 +0000 (UTC) Cc: 6525@debbugs.gnu.org To: Stefan Monnier Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Jul 02 01:29:57 2010 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1OUTCe-0006Um-On for geb-bug-gnu-emacs@m.gmane.org; Fri, 02 Jul 2010 01:29:57 +0200 Original-Received: from localhost ([127.0.0.1]:36909 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OUTCe-00027F-5N for geb-bug-gnu-emacs@m.gmane.org; Thu, 01 Jul 2010 19:29:56 -0400 Original-Received: from [140.186.70.92] (port=48639 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OUTCP-000265-BB for bug-gnu-emacs@gnu.org; Thu, 01 Jul 2010 19:29:51 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OUTCF-0005NJ-Tw for bug-gnu-emacs@gnu.org; Thu, 01 Jul 2010 19:29:41 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:60100) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OUTCF-0005ND-Rs for bug-gnu-emacs@gnu.org; Thu, 01 Jul 2010 19:29:31 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1OUSrS-0007Il-9Z; Thu, 01 Jul 2010 19:08:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: MON KEY Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 01 Jul 2010 23:08:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 6525 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 6525-submit@debbugs.gnu.org id=B6525.127802564028059 (code B ref 6525); Thu, 01 Jul 2010 23:08:02 +0000 Original-Received: (at 6525) by debbugs.gnu.org; 1 Jul 2010 23:07:20 +0000 Original-Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OUSqm-0007IW-5Y for submit@debbugs.gnu.org; Thu, 01 Jul 2010 19:07:20 -0400 Original-Received: from mail-gy0-f172.google.com ([209.85.160.172]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OUSqk-0007IP-AT for 6525@debbugs.gnu.org; Thu, 01 Jul 2010 19:07:18 -0400 Original-Received: by gyh3 with SMTP id 3so1373393gyh.3 for <6525@debbugs.gnu.org>; Thu, 01 Jul 2010 16:07:14 -0700 (PDT) Original-Received: by 10.101.26.33 with SMTP id d33mr203404anj.140.1278025634156; Thu, 01 Jul 2010 16:07:14 -0700 (PDT) Original-Received: by 10.151.46.4 with HTTP; Thu, 1 Jul 2010 16:07:14 -0700 (PDT) In-Reply-To: X-Google-Sender-Auth: Ghiq8CMaza4xjjANOWowo92wI-M X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Thu, 01 Jul 2010 19:08:02 -0400 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:38188 Archived-At: On Wed, Jun 30, 2010 at 9:10 PM, Stefan Monnier 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