From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Michael Albinus Newsgroups: gmane.emacs.devel Subject: Re: Docstrings and manuals Date: Sun, 17 Apr 2016 18:39:18 +0200 Message-ID: <87h9f02nrd.fsf@gmx.de> References: <6ok2vyzwf9.fsf@fencepost.gnu.org> <08f70cda-44be-0657-e50a-2b2c80d2c21c@yandex.ru> <87oa9dzgl0.fsf@gmx.de> <87potshczh.fsf@gmx.de> <87h9f4ghzg.fsf@gmx.de> <8737qnc8ep.fsf@gmx.de> <87k2jwd3gr.fsf_-_@gmx.de> <8dfdfe5d-41fe-7c05-0054-0bd3e589390e@yandex.ru> <8737qkcwoo.fsf@gmx.de> <909c91ef-aa2e-4bcc-9828-603c4203e3d0@yandex.ru> <87y48cctr6.fsf@gmx.de> <149a61a2-d812-5ae1-d969-d4201872e870@yandex.ru> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1460911190 28975 80.91.229.3 (17 Apr 2016 16:39:50 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 17 Apr 2016 16:39:50 +0000 (UTC) Cc: Glenn Morris , emacs-devel To: Dmitry Gutov Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Apr 17 18:39:41 2016 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 1arpjZ-0004aG-2Z for ged-emacs-devel@m.gmane.org; Sun, 17 Apr 2016 18:39:41 +0200 Original-Received: from localhost ([::1]:48723 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1arpjY-0004Qh-A8 for ged-emacs-devel@m.gmane.org; Sun, 17 Apr 2016 12:39:40 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:38577) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1arpjK-0004Kv-6O for emacs-devel@gnu.org; Sun, 17 Apr 2016 12:39:27 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1arpjJ-000238-AT for emacs-devel@gnu.org; Sun, 17 Apr 2016 12:39:26 -0400 Original-Received: from mout.gmx.net ([212.227.15.18]:57140) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1arpjF-00022T-CM; Sun, 17 Apr 2016 12:39:21 -0400 Original-Received: from detlef.gmx.de ([87.146.42.239]) by mail.gmx.com (mrgmx001) with ESMTPSA (Nemesis) id 0MNIi1-1apKkb0Fr7-006sl2; Sun, 17 Apr 2016 18:39:20 +0200 In-Reply-To: <149a61a2-d812-5ae1-d969-d4201872e870@yandex.ru> (Dmitry Gutov's message of "Sun, 17 Apr 2016 16:12:05 +0300") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1.50 (gnu/linux) X-Provags-ID: V03:K0:aU1Jg4SZrC1mlia5NTXz+SHMSzvbJi2RZamBYtXb08IhmQaH6Bd i/SZ8+VMNC56pbQ5wrKb6wewGkod2iiz/TXffcpQUz1DtjMehkIfI82rtplcs0B60hYc/gr B7hDFemNrurDnLPshbu/JuhccJdlJOKcpyYFvZujS4Me073ig2ZZ3UJQ/e/72Z/zdRCnF4j OegY0KSMvha5zsLD4bSZg== X-UI-Out-Filterresults: notjunk:1;V01:K0:ad7On0nuYig=:AmUwbsvLZBdbpv2PJ88/qQ 3swdo884bqtpwZHq9jyK0wrl9LEAgFUk6kXczuKW6WZoGyOLPVPSjKfLKaRHi8lXCZMRTufIQ spsf14bCbH807oWPvacFMCBlsCATkGPvDGS7juGiDMcHWnOzv00m8eDLMnd0dWJwaGmXrac0+ Yu6N5IgI9Ap2MigeuC0j6xSzBFX8ZNydmQm5gUL41QnQWRGxEselhY4MKrbBwc+imWd1+e7WY HBqOOZ52cN9oVyFB4hRcl1G/rgk7tfkHFbqEcCYrQN2d7uFanqHV171inimdosaUdckI/SHCC JpsYaj686ZzrBheR02GblVZFax8E1Pnfku/mhXvo5T31nZFukXMuYPAILTMyBHuohSNy2NaDW G3hnob6lbnxP+CKoVm2Il67e3rSIbp8FGrBr1RYRYIO/qnjCezmE4jrF8pkDcaVi1nB+kqB7Z 6zfIw87Bv0w18NY5TakIPlpccsK1pmoVBkeSEiyqetm7wuVQN7w/2xKtT9TiBiAZn/P6Se+h7 Fwgm9rSZH4W65fpo/LqvZaUID89svdtmqVCgAtcuxmfuzLrmo5TeMNLuUogvgqS+WmfhcDRZ0 sHhhCy5/iEWLhcTs/HDPAaSF2NtRFTsf68Dn8Idh19Wl+tBTlSxwRGWAeo62FclhhhlxpiiYg zy2uqJXQGb37WBWEzibI1P20NZx+6lk1661UJWXpU7oK5CTnW3l6u0Ts5rGKuPvEBIlkKqCwp hULnqWfjEsz7BN897UVldcQsrzgQXAJCUz0ETFLdd/qT6lhfby0aCFaPj/YSf12JefzXcqzn X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 212.227.15.18 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 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" Xref: news.gmane.org gmane.emacs.devel:203018 Archived-At: Dmitry Gutov writes: > My problem is that you stated the lack of a manual as the reason for > your lack of understanding of VC's internals. I'm saying the problem > is them being documented insufficiently in the code. And, like I > mentioned, if you go ahead and write the newfound revelations in the > manual, but not anywhere else, a certain slice of developers is going > to miss out. > > To expand on my message in > http://debbugs.gnu.org/cgi/bugreport.cgi?bug=20637#91, an example: > > If we make a decision that vc-BACKEND-state can rely on FILE not > having state `unregistered' (I'm not saying we should; it's just one > option), that information should go into the Commentary at the top of > vc.el (probably into the description of the `state' command), but... So we are in agreement :-) Of course, every relevant documentation must be up-to-date. Docstring, commentary section, manual. Personally, I believe a commentary section is a poor man's manual. Once the information is in the manual, the commentary section is not needed anymore. But this is nothing we need to worry about just now; let's discuss it once a proper manual entry about vc exist. Best regards, Michael.