From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Dmitry Gutov Newsgroups: gmane.emacs.bugs Subject: bug#20637: incompatible, undocumented change to vc-working-revision Date: Sun, 17 Apr 2016 03:27:38 +0300 Message-ID: <2735212c-3852-ee0b-2080-d5ea33af49f9@yandex.ru> 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> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 8bit X-Trace: ger.gmane.org 1460852904 19687 80.91.229.3 (17 Apr 2016 00:28:24 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 17 Apr 2016 00:28:24 +0000 (UTC) Cc: 20637@debbugs.gnu.org To: Michael Albinus Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Apr 17 02:28:14 2016 Return-path: Envelope-to: geb-bug-gnu-emacs@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 1araZR-0000hM-2y for geb-bug-gnu-emacs@m.gmane.org; Sun, 17 Apr 2016 02:28:13 +0200 Original-Received: from localhost ([::1]:36149 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1araZM-0002oQ-R2 for geb-bug-gnu-emacs@m.gmane.org; Sat, 16 Apr 2016 20:28:08 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:56140) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1araZJ-0002lz-2a for bug-gnu-emacs@gnu.org; Sat, 16 Apr 2016 20:28:06 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1araZF-0006vc-Q1 for bug-gnu-emacs@gnu.org; Sat, 16 Apr 2016 20:28:04 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:53580) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1araZF-0006vY-Mb for bug-gnu-emacs@gnu.org; Sat, 16 Apr 2016 20:28:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1araZF-0002dl-IY for bug-gnu-emacs@gnu.org; Sat, 16 Apr 2016 20:28:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Dmitry Gutov Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 17 Apr 2016 00:28:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 20637 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 20637-submit@debbugs.gnu.org id=B20637.146085286810130 (code B ref 20637); Sun, 17 Apr 2016 00:28:01 +0000 Original-Received: (at 20637) by debbugs.gnu.org; 17 Apr 2016 00:27:48 +0000 Original-Received: from localhost ([127.0.0.1]:37684 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1araZ1-0002dJ-Sn for submit@debbugs.gnu.org; Sat, 16 Apr 2016 20:27:48 -0400 Original-Received: from mail-wm0-f65.google.com ([74.125.82.65]:35742) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1araZ0-0002d4-B6 for 20637@debbugs.gnu.org; Sat, 16 Apr 2016 20:27:46 -0400 Original-Received: by mail-wm0-f65.google.com with SMTP id a140so15153295wma.2 for <20637@debbugs.gnu.org>; Sat, 16 Apr 2016 17:27:46 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=sender:subject:to:references:cc:from:message-id:date:user-agent :mime-version:in-reply-to:content-transfer-encoding; bh=GzligXrMl1A+7+VMab6YxP2Oxdc1hKrqCrdg3H20uvA=; b=YLSL/ekPzpWonX2zrTyHpHSKRmQTus5oufmYJDFo0XDc5wF9LedNBObW/kgNTLRr6G A6McPnCERSG9pEYh+9n2J4/NCuEPh7L14yE3eZ6PouCUZ8emWoN0qsQjSXnn1Cx4guLk oIh0BfR4F0sJIwLs2GIP0y6509Z6Ehhit3WxLjD2Kiuku4fd+aMBBfHrLTuyKpKhD3I+ AXNMS7XJ/4NaQfvGNWpLYvEl80J2mNMooR98A1AXAKzvDkcomoCYfNc9CPqu+lJjDQJy 7dronsiq6Wr4HPrB/GvwR+0agoXYGfbKQcUWAQMBh0gbcqwsX42cI3dnpJfhydR5FKtr qusg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:sender:subject:to:references:cc:from:message-id :date:user-agent:mime-version:in-reply-to:content-transfer-encoding; bh=GzligXrMl1A+7+VMab6YxP2Oxdc1hKrqCrdg3H20uvA=; b=RKXkZV1+E1tjpWWlBd4ALsw4kBQ6wQnYi4Hw/SLSB4WYW6tA7dSEg2b88IdHP/YdmO mS8iF+qOOu96FGuZjweawL4DViDhydFwyjE0hUjFZQMk10k4h3UJ6YfD5lzUYjZytgd9 lhjSj23SNDUj48CbWgi9s4ujYxJ9HqRLS4y8uq7RgPFSWx+wIM3UROmmuE10Z7EYw4+7 CYf+OsQdUuwGgobKpM235ZYT0mYph044qbT/dTPKM3nFNolDZx2YFY9wkntRSB+znh6P xUdtX/Il3UHzs4J6GlRLn9Qk3w4hZWJ4mw+lzFP7FwCY30/fAuXvAd+CrXuXLor1/0pd bZTA== X-Gm-Message-State: AOPr4FX4OtNhtkzprFAdlEq7QyNoq+iNX8/bftLHkE5BWaudLI8sgx3siavoNS/KTfrDSg== X-Received: by 10.194.92.237 with SMTP id cp13mr28995302wjb.168.1460852860765; Sat, 16 Apr 2016 17:27:40 -0700 (PDT) Original-Received: from [192.168.1.2] ([185.105.175.24]) by smtp.googlemail.com with ESMTPSA id j71sm18981817wmj.21.2016.04.16.17.27.39 (version=TLSv1/SSLv3 cipher=OTHER); Sat, 16 Apr 2016 17:27:40 -0700 (PDT) User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.0 In-Reply-To: <8737qnc8ep.fsf@gmx.de> 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: 208.118.235.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:116547 Archived-At: On 04/15/2016 04:23 PM, Michael Albinus wrote: > I'm not against this. But I would like to see the whole picture > first. Where else unregistered is used, and whether we run into > conflicts when using nil instead of unregistered. Sure. I'm reasonably confident, but please take the time and do your own evaluation. >> I disagree. The manual is the documentation for the users, to explain >> in depth, give examples, et cetera. The docstrings and VC's internal >> documentation have to stand on their own. It would be silly if the >> difference between `vc-backend' and `vc-responsible-backend' were to >> only be explained in the manual, but not in the docstrings. > > Are we speaking about different manuals? I'm speaking about the ‘GNU > Emacs Lisp Reference Manual’, and not the ‘GNU Emacs Manual’ (the manual > dedicated to users). I've split off a tangent to emacs-devel. Emacs Lisp Reference is a counter-example, but I think the last sentence in my paragraph above is still correct. VC has been documented in the docstrings and the Commentary sections (especially the one at the begining of vc.el). The new important information should go there first. If then you'd like to create a manual based on that information, to present it in more digestible form, sure, but let's not put anything essential into the manual only. We might avoid publishing that manual, though, until we're sure that VC is rock-solid to build third-party code on. >> That would also be unfair to people such as myself who prefer to >> consult the latter. > > With your argument, we could nuke the Emacs Lisp manual. Shall we? Does your argument allow nuking all docstrings and comments? >> So, do you need anything from me in this area? E.g., feel free to give >> a list of docstrings that seem insufficient to you, together with what >> you feel they are missing. > > I will start somehow, and show you for review. Thanks. >> I usually tease that kind of information out by reading the source >> code. Is there anything in particular I could help add to your >> understanding of the "global view"? > > Even if I understand it, it won't help any other developer. Let's > document it. Sure.