From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Emanuel Berg Newsgroups: gmane.emacs.bugs Subject: bug#35163: 25.1; `narrow-to-region' docstring no mention of args Date: Tue, 09 Apr 2019 03:09:02 +0200 Message-ID: <86zhp0t26p.fsf@zoho.eu> References: <868swoffpi.fsf@zoho.eu> <83ftqwb788.fsf@gnu.org> <86wok8dzi8.fsf@zoho.eu> <83bm1jbqgi.fsf@gnu.org> <86mul3bodv.fsf@zoho.eu> <83r2afa4od.fsf@gnu.org> <86zhp0urlr.fsf@zoho.eu> <87a7h0cf7p.fsf@tcd.ie> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="68014"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1 (gnu/linux) Cc: 35163@debbugs.gnu.org To: "Basil L. Contovounesios" Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Apr 09 03:10:15 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1hDfHC-000Hac-Ni for geb-bug-gnu-emacs@m.gmane.org; Tue, 09 Apr 2019 03:10:14 +0200 Original-Received: from localhost ([127.0.0.1]:33193 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hDfHB-0003cn-Oc for geb-bug-gnu-emacs@m.gmane.org; Mon, 08 Apr 2019 21:10:13 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:34710) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hDfH2-0003cR-W0 for bug-gnu-emacs@gnu.org; Mon, 08 Apr 2019 21:10:06 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hDfH1-0002Kq-PI for bug-gnu-emacs@gnu.org; Mon, 08 Apr 2019 21:10:04 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:36846) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hDfH0-0002Is-0Y for bug-gnu-emacs@gnu.org; Mon, 08 Apr 2019 21:10:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1hDfGz-0001h9-Qb for bug-gnu-emacs@gnu.org; Mon, 08 Apr 2019 21:10:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Emanuel Berg Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 09 Apr 2019 01:10:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 35163 X-GNU-PR-Package: emacs Original-Received: via spool by 35163-submit@debbugs.gnu.org id=B35163.15547721506434 (code B ref 35163); Tue, 09 Apr 2019 01:10:01 +0000 Original-Received: (at 35163) by debbugs.gnu.org; 9 Apr 2019 01:09:10 +0000 Original-Received: from localhost ([127.0.0.1]:50390 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hDfG9-0001fi-IL for submit@debbugs.gnu.org; Mon, 08 Apr 2019 21:09:09 -0400 Original-Received: from sender-pp-o92.zoho.eu ([31.186.226.252]:25748) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hDfG6-0001fX-Ou for 35163@debbugs.gnu.org; Mon, 08 Apr 2019 21:09:07 -0400 ARC-Seal: i=1; a=rsa-sha256; t=1554772144; cv=none; d=zohomail.eu; s=zohoarc; b=hVT8an8JxTHUv9FJWpdjiF1b3ZTV4OIusfBtiamw8xbddnEnZNyyAr8ClJkvUYAPxJngbXwWHvYBaW7+OBKg5of7e3LhsiShum03Yz/tMVz6iM1vwRMZLYM/nT3Kso2tlObKJ+GkvrmrGWXrfqR1UYgzU2pzlfWAbBCQDRQ915s= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.eu; s=zohoarc; t=1554772144; h=Content-Type:Cc:Date:From:In-Reply-To:MIME-Version:Message-ID:References:Subject:To:ARC-Authentication-Results; bh=8Z6uX5Xq9GTNuJ7vlwDTNSZOPI5mn/MkWfMG6vQa0iw=; b=Qtd/yyyQ+2RCZOyzvOHse84d4EjXKL9wwWHMiWikzMK4xWTpf3/SnyWU138bCYbVhEacbfnPk18eUleBPI0GSKyuPh6GwG4yo/+cF+UNRbd+7HFZTL3WYMhNZctVM+amHf2eZhj/bQrIX2L/fS4eNLYm7wtEDR8SvGXTehYIDwI= ARC-Authentication-Results: i=1; mx.zohomail.eu; dkim=pass header.i=zoho.eu; spf=pass smtp.mailfrom=moasenwood@zoho.eu; dmarc=pass header.from= header.from= DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; t=1554772144; s=admin; d=zoho.eu; i=moasenwood@zoho.eu; h=From:To:Cc:Subject:References:Date:In-Reply-To:Message-ID:MIME-Version:Content-Type; l=1835; bh=8Z6uX5Xq9GTNuJ7vlwDTNSZOPI5mn/MkWfMG6vQa0iw=; b=Zk7U8ySQ/SG/3Sf94jtKs355lJNX9aXK9VQ8iNVjOYNRRqR2WTmh1cnG7Xu+hIn2 7t65VoYZTnHg3VFrl1ZSx37rNehlbeV0Zc+1poOVpVr2yZULDkb/jV43MbSPDPoUjyT SO2wogck4A00ZbFoSBESfjb1xEoMdp4LTjwJcrYU= Original-Received: from raspberrypi.zoho.eu (c-b895225c.021-67-7570702.bbcust.telenor.se [92.34.149.184]) by mx.zoho.eu with SMTPS id 1554772143576538.7672327919697; Tue, 9 Apr 2019 03:09:03 +0200 (CEST) Mail-Copies-To: never In-Reply-To: <87a7h0cf7p.fsf@tcd.ie> (Basil L. Contovounesios's message of "Mon, 08 Apr 2019 23:19:38 +0100") X-ZohoMailClient: External X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 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: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:157384 Archived-At: Basil L. Contovounesios wrote: > [ Your Mail-Followup-To and Mail-Copies-To > headers seem wrong, they should point to > the bug address 35163@debbugs.gnu.org > instead of bug-gnu-emacs@gnu.org. ] [ OK, now I reply tho this (i.e., your) message thru gmane.emacs.bugs, and after that, I hope to reply to Noam Postavsky's message, and I'll do that thru mail, and we'll perhaps see if there is a difference or both ways are broken. My hunch is it'll work if I use mail, but not if I use the Gmane newsgroup. ] [ I was right, the Gmane newsgroups is to blame. So I re-send it here as well. Now everyone should be happy and content. ] > They're conventions and decent guidelines for > the general case, not rules. Humans reserve > the right to exercise their own judgement. > In particular, the "rule" to mention > positional arguments in the order they appear > often makes for unreadable docstrings IME. OK, the rule to mention them in order makes sense especially if you have a function with tons of args. But most important is that they are mentioned exactly as they are, so they can be searched for. Often, in Elisp code, you see this (some-function some-feature some-property t) Now, you can often guess what everything does, except for the last `t'. Brining up the help and searching for the arg's name to find it immediately in the docstring is a good way of finding out, fast. Thanks for your message, I'll keep it if this situation appears again. > Eli [...] keeps himself very busy > co-maintaining Emacs, yet he still manages to > set a stellar example of how documentation > should be maintained. ... okay? I just thought that was a strange statement. Like someone had _denied_ that (?) -- underground experts united http://user.it.uu.se/~embe8573