From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.devel Subject: Emacs manual nodes about text replacement Date: Sat, 15 Nov 2008 10:43:15 -0800 Message-ID: <005801c94752$053e9e50$0200a8c0@us.oracle.com> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1226774610 32552 80.91.229.12 (15 Nov 2008 18:43:30 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 15 Nov 2008 18:43:30 +0000 (UTC) To: Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Nov 15 19:44:31 2008 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1L1Q8C-0007UD-PE for ged-emacs-devel@m.gmane.org; Sat, 15 Nov 2008 19:44:29 +0100 Original-Received: from localhost ([127.0.0.1]:49994 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1L1Q74-0007PO-Gp for ged-emacs-devel@m.gmane.org; Sat, 15 Nov 2008 13:43:18 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1L1Q6z-0007Ow-1k for emacs-devel@gnu.org; Sat, 15 Nov 2008 13:43:13 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1L1Q6x-0007OZ-Cv for emacs-devel@gnu.org; Sat, 15 Nov 2008 13:43:12 -0500 Original-Received: from [199.232.76.173] (port=39383 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1L1Q6x-0007OV-4C for emacs-devel@gnu.org; Sat, 15 Nov 2008 13:43:11 -0500 Original-Received: from rcsinet13.oracle.com ([148.87.113.125]:19367 helo=rgminet13.oracle.com) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1L1Q6w-0004zv-LV for emacs-devel@gnu.org; Sat, 15 Nov 2008 13:43:10 -0500 Original-Received: from acsinet13.oracle.com (acsinet13.oracle.com [141.146.126.235]) by rgminet13.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id mAFIhL4k022957 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Sat, 15 Nov 2008 18:43:23 GMT Original-Received: from acsmt702.oracle.com (acsmt702.oracle.com [141.146.40.80]) by acsinet13.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id mAFIhHm0012678 for ; Sat, 15 Nov 2008 18:43:19 GMT Original-Received: from dradamslap1 (/24.23.165.218) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sat, 15 Nov 2008 10:43:04 -0800 X-Mailer: Microsoft Office Outlook 11 Thread-Index: AclHUgTm/cJ8o4yfTvKUbsta0ONVMg== X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.3350 X-Source-IP: acsmt702.oracle.com [141.146.40.80] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090209.491F1839.00A9:SCFSTAT928724,ss=1,fgs=0 X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6 (newer, 1) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:105706 Archived-At: The presentation and order of the manual nodes describing text replacement could be improved. I don't have a concrete proposal, but here are some problems I see. The main node, Replace, starts by saying that you don't use global search-and-replace that much in Emacs. That's true in the batch (unconditional) sense, but query-replacement is commonly used. This could be made clearer: Unconditional global replacement is not needed that often. Most of the time you use conditional, interactive replacement - called query-replacement. The subnode order then describes first precisely what we just said is not needed that much. First comes batch string replace, then batch regexp replace, then case considerations during (batch) replacement. The nitty gritty of replacement types and mechanisms is presented in the context of batch replacement (only), which gives the impression that these do not apply also to query-replacement (which has not even been introduced yet!). This, in spite of the fact that users will, most of the time, use that information for query-replacment, not for batch replacement. It is not until after all of this (which includes some pretty heavy Lisp-oriented details about expression regexp replacement) that we get to node Query Replace, which tells you that you can query-replace. In a sense, the existing node order is bottom-up, presenting details about replacement before presenting how to replace in general. It would be better to guide users by presenting first and foremost query-replacement. For the details about which replacements are possible and how they are made (things such as case considerations and regexp and evalled expression replacement), users could then read the nodes that follow. IOW, give a top-down explanation of how Emacs users typically replace text. Start with query-replace and let readers drill down as needed. Make it clear that all of the replacement possibilities and mechanisms apply to both query-replacement and to (the lesser used) batch replacement. Point out exceptions, if there are any. As it stands now, query-replacement seems to be almost an afterthought (after we're all done explaining replacement in all its glory), and for only simple, lightweight replacements. In fact, query-replacement is the main entry point for all kinds of replacements. This fact is lost, IMO. Batch replacement, not query-replacement, should be presented as almost an afterthought: BTW, you can also replace unconditionally - but if you do that interactively then it is usually better to use query-replacement and, after you are sure of what the replacement does, hit `!'. The fact that advanced replacement is possible when you query-replace needs to be made clear. The problem is not only the node order. It is not obvious when reading the Query Replace node, for example, that you can do evalled Lisp-expression replacement. You really have to read carefully and somewhat between the lines to catch that. This passage is the only clue I could find: "`C-M-%' performs regexp search and replace (`query-replace-regexp'). It works like `replace-regexp' ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ except that it queries like `query-replace'." It's only the phrase "it works like `replace-regexp'" that hints that you might be able to use things like \, in the replace string when query-replacing. This is not enough to guide the user. Yes, things such as \, are advanced uses, but they are also interactive uses, and powerful ones. Such functionality merits clear documentation in the Emacs manual, which is our user guide. Programmers can now use query-replacement to do things interactively that they might have done previously only via script or Lisp code. They need to be made aware of these possibilities. In sum, the overall presentation should take users through what's available in a top-down way, and it should emphasize query-replacing throughout. In particular, it should help users see that advanced, sophisticated replacement (regexp, expressions, lists) is available for query-replacement. It's OK to present the advanced features and the details in subsequent nodes, but the advanced replacement features should at least be called out at the higher level, when introducing query-replacement. They should not be buried, and they should not appear to be available only for batch replacement. In general, present first the features available: _what_ you can do with Emacs (query-)replacement, before presenting all of the details of _how_ to do it: `C-w' to delete and then recurse, etc. [See also my mail of today, subject "general perform-replace REPLACEMENTS arg for regexp query-replacement?".]