From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: "Basil L. Contovounesios" Newsgroups: gmane.emacs.bugs Subject: bug#35163: 25.1; `narrow-to-region' docstring no mention of args Date: Mon, 08 Apr 2019 23:19:38 +0100 Message-ID: <87a7h0cf7p.fsf@tcd.ie> 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> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="196949"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) Cc: 35163@debbugs.gnu.org To: Emanuel Berg Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Apr 09 00:20:30 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 1hDccv-000p7v-T3 for geb-bug-gnu-emacs@m.gmane.org; Tue, 09 Apr 2019 00:20:30 +0200 Original-Received: from localhost ([127.0.0.1]:59780 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hDccu-00021X-P4 for geb-bug-gnu-emacs@m.gmane.org; Mon, 08 Apr 2019 18:20:28 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:54715) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hDccj-0001xf-MY for bug-gnu-emacs@gnu.org; Mon, 08 Apr 2019 18:20:19 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hDccc-0005ZS-T6 for bug-gnu-emacs@gnu.org; Mon, 08 Apr 2019 18:20:14 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:36745) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hDccU-0005VC-F8 for bug-gnu-emacs@gnu.org; Mon, 08 Apr 2019 18:20:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1hDccU-0005j8-49 for bug-gnu-emacs@gnu.org; Mon, 08 Apr 2019 18:20:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: "Basil L. Contovounesios" Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 08 Apr 2019 22:20:02 +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.155476199321993 (code B ref 35163); Mon, 08 Apr 2019 22:20:02 +0000 Original-Received: (at 35163) by debbugs.gnu.org; 8 Apr 2019 22:19:53 +0000 Original-Received: from localhost ([127.0.0.1]:50289 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hDccK-0005if-Ei for submit@debbugs.gnu.org; Mon, 08 Apr 2019 18:19:52 -0400 Original-Received: from mail-ed1-f65.google.com ([209.85.208.65]:45434) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hDccE-0005iN-LK for 35163@debbugs.gnu.org; Mon, 08 Apr 2019 18:19:50 -0400 Original-Received: by mail-ed1-f65.google.com with SMTP id f19so6103907edw.12 for <35163@debbugs.gnu.org>; Mon, 08 Apr 2019 15:19:46 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=tcd-ie.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version:content-transfer-encoding; bh=Z9NhX0o+/3jbhAYSm0lXl68ojqUreakgkkrMdgctAyw=; b=slm1lS9rJDWTq5bESJMd7Dlq0JcG+xce6xm9mtnZuMyFzJ3XvWqHt6Nw8+hbMM/MbU qOrs7xTUsFW59bRs9cjdyqVa4kFcr0LyQ7tiIKoytpwizkOQRl41Ea7tb2dMK3MOE3LP CZpeTvDTrVop4tOd4cZbCrM9YxLyqmVEUeHANhwUtTE+To7LsPcq/WZV+9n3LDCNQ0uD gkFyy37BREaczSPtU7Kloa7AqraEpZi8dEsqDRBS9UE/BJCgPpgtQlN3+DxiLQX81Q7y TV9oslsIxwipUo3b56ygBtZwF5AF2HrT39FJRpoePgTkiqtpR2epjTk07HagbvgszcJf HbHg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:references:date:in-reply-to :message-id:user-agent:mime-version:content-transfer-encoding; bh=Z9NhX0o+/3jbhAYSm0lXl68ojqUreakgkkrMdgctAyw=; b=Bkppfqb9nx5ikHl3p9+z3MIdZ4R45HF2rDpCro/koabMCQwxVo5SuyBBa5SOIYI5c1 QxhQ3b0VuDHY8pwjogE6JDGVJkLqTx7Du089d+X5m6288SNW6QxdoS/4ezYgCNvHaSf4 8Bh4U3HkQAZ24Nc20GJE/bHWRKAwq/aIMWQFu6qQ+X/gPj/mHDH0ORBrwfd3H3AHtifC InmEW0bKO4tycI4vU1r4g/PDBFmiLY7ptN83UPbmcovNKFDLvMsfhD1kOBTJcPIxNs3U rxPXw+TgCD5V1D7swgdzfYtxX8dR+Xvy0ZdJvL/DnxPQagu++MBCgRfXqNRmJ3cIarcy NUhA== X-Gm-Message-State: APjAAAUkik5h5jlw2Qax8dtbpdU/9y6MOb1dvTSLr/OgqAMLCbET6B5U WPb4ZSh6z5Bv2af7a+ABiaBdwQ== X-Google-Smtp-Source: APXvYqxoAw3S1NZR+Tw2ZL7FLTPqS8QxrVT9BkXfAoH0Ooq7KxLkxuErI9TmoNNI4NQbJplqO/7IBw== X-Received: by 2002:a17:906:4f19:: with SMTP id t25mr18272260eju.165.1554761980811; Mon, 08 Apr 2019 15:19:40 -0700 (PDT) Original-Received: from localhost ([2a02:8084:20e2:c380:f786:805d:f4ab:1006]) by smtp.gmail.com with ESMTPSA id p16sm5684862ejb.13.2019.04.08.15.19.39 (version=TLS1_3 cipher=AEAD-AES256-GCM-SHA384 bits=256/256); Mon, 08 Apr 2019 15:19:40 -0700 (PDT) In-Reply-To: <86zhp0urlr.fsf@zoho.eu> (Emanuel Berg's message of "Mon, 8 Apr 2019 23:14:40 +0200") 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:157367 Archived-At: [ 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. ] Emanuel Berg writes: > Glenn Morris wrote: > >> (People who have particular ideas about doc >> strings > > Well, I don't know about "particular", as > I myself learned the rules from > (checkdoc-current-buffer t) when I did Elisp > packages. But yes, I think the rules > make sense! 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. Note also the relevant Elisp manual node is called "Documentation Tips"[1], and its opening paragraph reads as follows: > Here are some tips and conventions for the writing of documentation > strings. You can check many of these conventions by running the command > =E2=80=98M-x checkdoc-minor-mode=E2=80=99. [1]: (info "(elisp) Documentation Tips") >> could save everyone a lot of time by >> sending patches.) > > Should I interpret this as "one shouldn't > bother the maintainers with details like this"? Not at all. Eli (amongst several other fastidious contributors) keeps himself very busy co-maintaining Emacs, yet he still manages to set a stellar example of how documentation should be maintained. I'm sure what Glenn and Eli meant is closer to "a patch speaks a thousand words," i.e. it's easier and more efficient to convey one's intentions by showing, rather than describing, them, especially over the lossy communication medium that is email. > If so, I'm happy to supply patches instead, > only I haven't done it before and don't know > how to do it. In theory, you change the code, > then use a tool that generates a note of the > changes you made, and you submit that > note, right? Right. > Is there some Emacs mode or infrastructure to help you with this? There are various tools you can use. Since Emacs uses Git as its VCS, the built-in Version Control[2] interface and/or the third-party Magit[3][4] package would be obvious choices if you're already somewhat familiar with Git. Even simpler would be to use M-x diff[5][6] or the eponymous command-line utilities 'diff' or 'patch'. See, for example, the manual node on Bugs[7], particularly its subnode on Sending Patches[8]. There is also some related information under Contributing[9] and in the CONTRIBUTE[10] file of the Emacs source tree[11]. [2]: (info "(emacs) Version Control") [3]: https://github.com/magit/magit/ [4]: (info "(magit) Top") [5]: (info "(emacs) Comparing Files") [6]: (info "(emacs) Diff Mode") [7]: (info "(emacs) Bugs") [8]: (info "(emacs) Sending Patches") [9]: (info "(emacs) Contributing") [10]: http://git.savannah.gnu.org/cgit/emacs.git/tree/CONTRIBUTE [11]: http://git.savannah.gnu.org/cgit/emacs.git/ > Also, if the docstring is in the C code, does > that mean you have to recompile that source > file after the change? You only need to recompile if you want the changes to appear next time you run the compiled Emacs instance. You do not need to recompile in order to create and send a patch, though compilation warnings/errors can alert you to unforeseen problems or mistakes prior to sending the patch. > Docstrings for C functions are themselves in the C code, right? Yes, they are written as multiline C comments of the form /* ... */. For details, see (info "(elisp) Writing Emacs Primitives"). > As I'm using Emacs 25, does that mean I should > get a more recent version, for the single > purpose of doing this? If so, which one? > That sounds like a lot of work but thinking > about it I suppose it doesn't have to be. If you are interested in contributing code and/or documentation, it would definitely be easier if you checked out the Git sources[11], if only so that you wouldn't be looking at outdated code/documentation. Alternatively, you can download and/or install the most recent release[12], or download the sources via 'apt-get source'. [12]: https://www.gnu.org/software/emacs/download.html Emacs 26 is the current release, and it includes many fixes since Emacs 25, so I would recommend looking at something at least as recent as 26.1, if not the emacs-26 or master branches of the Git repository (I think Emacs 26.2 is due to be released soon as well). Thanks for your interest, --=20 Basil