From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Glenn Morris Newsgroups: gmane.emacs.devel Subject: Re: changes in r112843 Date: Wed, 05 Jun 2013 13:41:05 -0400 Message-ID: References: <8bvc5tlqpa.fsf@fencepost.gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: ger.gmane.org 1370454078 13602 80.91.229.3 (5 Jun 2013 17:41:18 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Wed, 5 Jun 2013 17:41:18 +0000 (UTC) Cc: emacs-devel To: Xue Fuqiao Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Jun 05 19:41:19 2013 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1UkHi3-0003O3-EI for ged-emacs-devel@m.gmane.org; Wed, 05 Jun 2013 19:41:19 +0200 Original-Received: from localhost ([::1]:57881 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UkHi3-0002rE-1i for ged-emacs-devel@m.gmane.org; Wed, 05 Jun 2013 13:41:19 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:45816) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UkHhw-0002qz-3g for emacs-devel@gnu.org; Wed, 05 Jun 2013 13:41:17 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1UkHhr-0005V3-8K for emacs-devel@gnu.org; Wed, 05 Jun 2013 13:41:12 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:56100) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UkHhr-0005Uz-4i for emacs-devel@gnu.org; Wed, 05 Jun 2013 13:41:07 -0400 Original-Received: from rgm by fencepost.gnu.org with local (Exim 4.71) (envelope-from ) id 1UkHhq-0003b6-1l; Wed, 05 Jun 2013 13:41:06 -0400 X-Spook: Reno Bellcore Armani Janet Reno PET target spy pipeline X-Ran: 8,)8Juo3bduuJSk?HiX44sWBHG&6XtWI_Q6;oM6av|FN}CXV~Pl^z&zopp"6bVES5Zo`E{ X-Hue: green X-Attribution: GM In-Reply-To: (Xue Fuqiao's message of "Wed, 5 Jun 2013 07:12:24 +0800") User-Agent: Gnus (www.gnus.org), GNU Emacs (www.gnu.org/software/emacs/) X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-Received-From: 2001:4830:134:3::e X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:160122 Archived-At: First, thank you for trying to improve the Emacs documentation. My main point was, please don't copy text from other sources (especially without attribution). Instead, it is much better to add a cross-reference. This avoids duplication, and helps keep the size of the manual down. (Or find your own phrasing. If you are not confident that you have it correct, there are lots of people on this list who love critiquing grammar etc.) In this case, it would be something like: for more information on branches, see . Which IMO shows how pointless it is, because such a note could be added after just about every word in the manual. It's obvious, and we don't need to state the obvious. The Emacs manual does not need to explain why to use branches. It just needs to say; if you _are_ using branches, here is how Emacs can help. To avoid anyone reading the Emacs manual who doesn't know what a branch is getting totally confused, there can optionally be a brief explanatory sentence. That is what the original text had. Of course we could quibble about the precise wording all day, but doing so won't improve the Emacs manual measurably.