From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Sean Whitton Newsgroups: gmane.emacs.devel Subject: Re: New optional Eshell module: em-elecslash Date: Tue, 19 Apr 2022 09:52:59 -0700 Message-ID: <87wnfluiac.fsf@athena.silentflame.com> References: <87k0bokg98.fsf@melete.silentflame.com> <83ee1wzvki.fsf@gnu.org> <87fsmckd6d.fsf@melete.silentflame.com> <837d7oz0vo.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="38154"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Emacs/29.0.50 (x86_64-pc-linux-gnu) Cc: philipk@posteo.net, emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Tue Apr 19 18:54:26 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 1ngr7Q-0009fO-0K for ged-emacs-devel@m.gmane-mx.org; Tue, 19 Apr 2022 18:54:25 +0200 Original-Received: from localhost ([::1]:44512 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ngr7O-00040i-Ps for ged-emacs-devel@m.gmane-mx.org; Tue, 19 Apr 2022 12:54:22 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:58750) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ngr68-0001Ok-5r for emacs-devel@gnu.org; Tue, 19 Apr 2022 12:53:05 -0400 Original-Received: from out5-smtp.messagingengine.com ([66.111.4.29]:54805) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ngr66-0001n4-25; Tue, 19 Apr 2022 12:53:03 -0400 Original-Received: from compute2.internal (compute2.nyi.internal [10.202.2.46]) by mailout.nyi.internal (Postfix) with ESMTP id CAC645C0121; Tue, 19 Apr 2022 12:53:00 -0400 (EDT) Original-Received: from mailfrontend1 ([10.202.2.162]) by compute2.internal (MEProxy); Tue, 19 Apr 2022 12:53:00 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=spwhitton.name; h=cc:cc:content-type:date:date:from:from:in-reply-to :in-reply-to:message-id:mime-version:references:reply-to:sender :subject:subject:to:to; s=fm3; t=1650387180; x=1650473580; bh=T3 7pZcSCU44S5epsCKMg7w6Xw9eyhMhsuso1r1vsUHk=; b=rUm5FVVJP14aYKOLXr HRU1OT9oM/O5pIhjVPgY7fDrv5EfvpXk+jh6huoiRNLQYY54qW2oKdpDmO9dwtCQ qluLXWA2ta4skPH+QO63D3EEkZ2/buTfb4EcMlz1P+blPl/YhrLVuqntYzrEbR1E beb4nSgC24opiosAfoZXjgEOx0svA9VAD8mkJY6oFQaueN02BbandeW81pLEt8zj ocy8+rJpLqY8vpTGJMYCxzp91JFr7wD8lK6bLID4SH0OvWLJjWy7NRurICdoEuGp umXOQ6pR84DyfBsuhNqf8yeJqJe2MWAjJfyd2QBUMvraoCesb1k+TYnDztg9ah+s Zmyg== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:cc:content-type:date:date:from:from :in-reply-to:in-reply-to:message-id:mime-version:references :reply-to:sender:subject:subject:to:to:x-me-proxy:x-me-proxy :x-me-sender:x-me-sender:x-sasl-enc; s=fm1; t=1650387180; x= 1650473580; bh=T37pZcSCU44S5epsCKMg7w6Xw9eyhMhsuso1r1vsUHk=; b=p 1cuj9NuRc5axP1vxJrt9ZnNwmqYkrUQy7FNqfS2SDebA2j1Y1bnWk02vFipGE8nP IbHZLWWM/ZXgl2l5yi6FkPJ+e6QJKYRvdR/EbY2obKhSVCbf7vPUnsX2rRhVvB/o 70PDTrejvyfAQYwpg+TCNIzHZbsdGQMDzzC2Ri+Wkx9tU9BJFaC7BM4onQVa8rV+ 2CtjdvLgrB183d+CbPmtdlOU/UzyXxpGXZwMYJKLul8r8G1HmZxQ5mAd/pBWgQ+n e5e4hfKwoX/vMO0cgwQbdIVOXJjo1Bsro0hRz7z7qwgDXRbkFeVqnigp6xQftTr1 6UJBKmoGZzI1UhjNFOeYg== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedvvddrvddtfedguddtiecutefuodetggdotefrod ftvfcurfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfgh necuuegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmd enucfjughrpefhvffujghffgffkfggtgesthdttddttdertdenucfhrhhomhepufgvrghn ucghhhhithhtohhnuceoshhpfihhihhtthhonhesshhpfihhihhtthhonhdrnhgrmhgvqe enucggtffrrghtthgvrhhnpeelgeeggfdvieejvdfhudfggeetgfekkeeuieeljeejhedu geegfeetgefhueffkeenucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepmhgrih hlfhhrohhmpehsphifhhhithhtohhnsehsphifhhhithhtohhnrdhnrghmvg X-ME-Proxy: Original-Received: by mail.messagingengine.com (Postfix) with ESMTPA; Tue, 19 Apr 2022 12:53:00 -0400 (EDT) Original-Received: by athena.silentflame.com (Postfix, from userid 1000) id 10B3A1B7988; Tue, 19 Apr 2022 16:52:59 +0000 (UTC) In-Reply-To: <837d7oz0vo.fsf@gnu.org> Received-SPF: pass client-ip=66.111.4.29; envelope-from=spwhitton@spwhitton.name; helo=out5-smtp.messagingengine.com X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action 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:288676 Archived-At: Hello, On Sun 17 Apr 2022 at 09:20am +03, Eli Zaretskii wrote: > 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. Thanks for this, I will read it carefully and revise my patch. > 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.) Good to know. > 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 Right, I'll try to be more willing to say less in that first sentence. -- Sean Whitton