From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: New optional Eshell module: em-elecslash Date: Sun, 17 Apr 2022 09:20:59 +0300 Message-ID: <837d7oz0vo.fsf@gnu.org> References: <87k0bokg98.fsf@melete.silentflame.com> <83ee1wzvki.fsf@gnu.org> <87fsmckd6d.fsf@melete.silentflame.com> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="18145"; mail-complaints-to="usenet@ciao.gmane.io" Cc: philipk@posteo.net, emacs-devel@gnu.org To: Sean Whitton Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sun Apr 17 08:22:31 2022 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1nfyIo-0004Yt-DS for ged-emacs-devel@m.gmane-mx.org; Sun, 17 Apr 2022 08:22:30 +0200 Original-Received: from localhost ([::1]:47422 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nfyIm-0007BT-Qo for ged-emacs-devel@m.gmane-mx.org; Sun, 17 Apr 2022 02:22:28 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:54072) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nfyHe-0006N1-Sm for emacs-devel@gnu.org; Sun, 17 Apr 2022 02:21:19 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:44952) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nfyHd-0002k5-JR; Sun, 17 Apr 2022 02:21:17 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=XipFN4466MU64FSWydLgPVrG3NxcwgfNUyMxduH84QQ=; b=YdB5b25kzt5u aLI8sqU50StEGbbpJAfBz6jECHbC9Q82yctOW9ZGKbC9EG9e2/DnfL2sEOLxpKbMXbRetimrOPESC 5gA9Dc/lEoeM4rJeb3+ymn7StwxEkprhm8UIuAZZ4jOimkEvsn+L/XWTUTMy8WctXL/ch+z0u3K5V QACY6mT/4CR8/J87inap5dNQA3TEqFq+u9+JYeIw8bVSAvizaZZT9OZj8VP10Cc+sqeArUPeXrWdl xNs+k/UvWgggNKUxq03Fpwj0C3rPvg4AGh1f8vS7AnPYatxPXcly1i0gpFFIDO/fJn/2a26E7qP5+ sciVH+dDIudH9cfkdtEQLQ==; Original-Received: from [87.69.77.57] (port=1429 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nfyHb-0003Ld-1K; Sun, 17 Apr 2022 02:21:16 -0400 In-Reply-To: <87fsmckd6d.fsf@melete.silentflame.com> (message from Sean Whitton on Sat, 16 Apr 2022 13:04:26 -0700) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 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-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:288526 Archived-At: > From: Sean Whitton > Cc: emacs-devel@gnu.org, philipk@posteo.net > Date: Sat, 16 Apr 2022 13:04:26 -0700 > > On Sat 16 Apr 2022 at 10:18PM +03, Eli Zaretskii wrote: > > >> +If the @code{eshell-elecslash} module has been added to > >> +@code{eshell-modules-list}, and @code{default-directory} is remote, > >> +then when you type the first forward slash of an argument to a Lisp > >> +function, the Tramp prefix will be filled in for you. A second > >> +forward slash can be used to undo the insertion, for when you really > >> +do want to pass a local absolute path, such as when you want to copy a > >> +remote file to the local machine. And when typing arguments to > >> +external commands, the Tramp prefix is not filled in. The result is > >> +that you don't have to think about inserting the Tramp prefix and can > >> +just type absolute paths in the same way for both types of command. > >> +The Tramp prefix is additionally filled in when you type @code{~/}. > > > > You use passive tense a lot (here and elsewhere), which in many cases > > makes the text longer, more complicated, and harder to understand. > > Please try rephrasing without using passive tense so much. > > I'm happy to try to make it clearer, but in the U.K. we don't have this > idea that the passive voice is worse than the active -- I didn't learn > the distinction until after finishing a humanities degree -- so could > you be more specific, please? IME, use of passive tense is not the "disease", it's a symptom. The "disease" is overly complicated sentences that make the text hard to understand. Using passive tense is a good indicator that the structure of the text is sub-optimal and needs to be rethought. Trying to use active tense as much as possible in many cases leads to such rethinking and makes the text more clear. For example, here's how I'd rephrase the above paragraph: To help you type file-name arguments to remote commands, add the @code{eshell-elecslash} module to @code{eshell-modules-list}. Then typing the first @kbd{/} character of a command-line argument will automatically insert the Tramp prefix if the @code{default-directory} is remote. If this is not what you want (e.g., you want to type a local absolute file name instead), type another @kbd{/} to undo this automatic prefix insertion. Typing @kbd{~/} also inserts the Tramp prefix. By contrast, typing arguments to external commands, which always run locally, doesn't insert the prefix. The result is that in most cases you get the Tramp prefix inserted automatically only when you should reasonably expect it. Do you see how using the active tense makes the text more clear? Another thing to remember for writing clear documentation is not to put the important parts too far near the end of a sentence; the above rewording fixed a few instances of that in your original text. > >> +*** New optional Eshell module to help avoid mistakes when supplying > > > > The first line of a NEWS entry is a heading, so it should be a > > complete sentence, to facilitate reading the outlines. > > Hmm interesting. I found continuing sentences from the outline heading > to the next line strange, but noticed that many NEWS entries did it, so > thought it was how outline-mode is meant to be used. No, the NEWS entries where the first line is not a complete sentence ending in a period are in error and should be fixed. (We usually fix that close to starting a pretest, if not earlier.) > >> +;;;###autoload > >> +(progn > >> +(defgroup eshell-elecslash nil > >> + "When `default-directory' is remote thanks to Eshell's TRAMP > > > > the first line of a doc string should be a complete sentence, because > > some Help commands only show that single line. > > > >> +(defun eshell-electric-forward-slash () > >> + "Electric insertion of TRAMP part of `default-directory' in > >> +remote Eshells. Added to `post-self-insert-hook' when the > > > > Likewise. > > I'll try to come up with something. This rule can be very difficult to > satisfy given line length restrictions. We all bump into that from time to time. Some techniques for dealing with the difficulties: . omit some less important parts, like "the" etc. . rearrange the text to make it shorter (for example, say "buffer text" instead of "the text of the buffer") . omit less important details from the first sentence, and describe them in the following parts of the doc string Thanks.