From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Stefan Monnier Newsgroups: gmane.emacs.bugs Subject: bug#6525: documentation of macro `with-silent-modifications' 1 typo + multi-horrid Date: Thu, 01 Jul 2010 03:10:11 +0200 Message-ID: References: NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: dough.gmane.org 1277949581 9038 80.91.229.12 (1 Jul 2010 01:59:41 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Thu, 1 Jul 2010 01:59:41 +0000 (UTC) Cc: 6525@debbugs.gnu.org To: MON KEY Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Jul 01 03:59:39 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 1OU93y-0001fk-RL for geb-bug-gnu-emacs@m.gmane.org; Thu, 01 Jul 2010 03:59:39 +0200 Original-Received: from localhost ([127.0.0.1]:49796 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OU93y-0007K2-A6 for geb-bug-gnu-emacs@m.gmane.org; Wed, 30 Jun 2010 21:59:38 -0400 Original-Received: from [140.186.70.92] (port=49506 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OU93q-0007Jo-Pk for bug-gnu-emacs@gnu.org; Wed, 30 Jun 2010 21:59:31 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OU93o-0007Vw-U0 for bug-gnu-emacs@gnu.org; Wed, 30 Jun 2010 21:59:30 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:49594) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OU93o-0007Vs-Sa for bug-gnu-emacs@gnu.org; Wed, 30 Jun 2010 21:59:28 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1OU8rl-0006Nd-N1; Wed, 30 Jun 2010 21:47:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Stefan Monnier 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 01:47:01 +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.127794878224517 (code B ref 6525); Thu, 01 Jul 2010 01:47:01 +0000 Original-Received: (at 6525) by debbugs.gnu.org; 1 Jul 2010 01:46:22 +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 1OU8r7-0006NO-Ou for submit@debbugs.gnu.org; Wed, 30 Jun 2010 21:46:22 -0400 Original-Received: from smtp-03.vtx.ch ([194.38.175.92]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OU8r5-0006NJ-TN for 6525@debbugs.gnu.org; Wed, 30 Jun 2010 21:46:20 -0400 Original-Received: from ceviche.home (dyn.144-85-133-055.dsl.vtx.ch [144.85.133.55]) by smtp-03.vtx.ch (VTX Services SA) with ESMTP id 93165296CCF; Thu, 1 Jul 2010 03:46:15 +0200 (CEST) Original-Received: by ceviche.home (Postfix, from userid 20848) id 1818A662B0; Thu, 1 Jul 2010 03:10:11 +0200 (CEST) In-Reply-To: (MON KEY's message of "Mon, 28 Jun 2010 03:36:09 -0400") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.50 (gnu/linux) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Wed, 30 Jun 2010 21:47:01 -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:38157 Archived-At: > 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