From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: On being web-friendly and why info must die Date: Fri, 12 Dec 2014 16:46:09 +0200 Message-ID: <838uidrkni.fsf@gnu.org> References: <20141205123549.GA29331@thyrsus.com> <87ppbqb6s1.fsf@gnu.org> <87388mme16.fsf@newcastle.ac.uk> <87a92u86wv.fsf@gnu.org> <87egs5ktdv.fsf@newcastle.ac.uk> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: QUOTED-PRINTABLE X-Trace: ger.gmane.org 1418395592 31020 80.91.229.3 (12 Dec 2014 14:46:32 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 12 Dec 2014 14:46:32 +0000 (UTC) Cc: esr@thyrsus.com, ludo@gnu.org, emacs-devel@gnu.org To: phillip.lord@newcastle.ac.uk (Phillip Lord) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Dec 12 15:46:25 2014 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 1XzRU7-0001Vo-7g for ged-emacs-devel@m.gmane.org; Fri, 12 Dec 2014 15:46:23 +0100 Original-Received: from localhost ([::1]:57627 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XzRU6-0006p2-Sf for ged-emacs-devel@m.gmane.org; Fri, 12 Dec 2014 09:46:22 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:39569) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XzRTy-0006oa-My for emacs-devel@gnu.org; Fri, 12 Dec 2014 09:46:19 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1XzRTt-0002uv-PO for emacs-devel@gnu.org; Fri, 12 Dec 2014 09:46:14 -0500 Original-Received: from mtaout22.012.net.il ([80.179.55.172]:59134) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XzRTt-0002uT-Gc; Fri, 12 Dec 2014 09:46:09 -0500 Original-Received: from conversion-daemon.a-mtaout22.012.net.il by a-mtaout22.012.net.il (HyperSendmail v2007.08) id <0NGH00D004XCKD00@a-mtaout22.012.net.il>; Fri, 12 Dec 2014 16:46:07 +0200 (IST) Original-Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout22.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0NGH00D8U50VIA40@a-mtaout22.012.net.il>; Fri, 12 Dec 2014 16:46:07 +0200 (IST) In-reply-to: <87egs5ktdv.fsf@newcastle.ac.uk> X-012-Sender: halo1@inter.net.il X-detected-operating-system: by eggs.gnu.org: Solaris 10 X-Received-From: 80.179.55.172 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 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-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:179912 Archived-At: > From: phillip.lord@newcastle.ac.uk (Phillip Lord) > Date: Fri, 12 Dec 2014 11:19:24 +0000 > Cc: esr@thyrsus.com, emacs-devel@gnu.org >=20 > I've always wondered, with the emacs doc about things like this... >=20 > -- Function: current-buffer > This function returns the current buffer. >=20 > (current-buffer) > =E2=87=92 # >=20 >=20 > Now, this describes `current-buffer'. But the real documentation fo= r > this is here: >=20 > doc: /* Return the current buffer as a Lisp object. */ There are 2 (sometimes more) "real documentations" for each Emacs symbol. You somehow assume there should be just one, but that's a false assumption. The documentation is worded differently in the manual and in the doc string because it targets 2 different use cases: the latter is for immediate references while using Emacs, the former is for learning about Emacs. Therefore, the manual can have longer and more detailed descriptions, while the doc string needs to be concise and cut to the cheese very quickly. > How do you include docstring from a lisp function or var in texinfo= ? What for? > Go to the Emacs manual, and type "i", and "current-buffer". [No mat= ch]. > Which is strange, because there is documentation for current-buffer= , in > the elips manual. >=20 > So, the manuals already are isolated. The info index functionality = is > not really as rich as it seems. Your conclusion is wrong. We describe each symbol in the manual(s) where they are relevant. The variable current-buffer is not relevant to Emacs users, unless they write Lisp code, in which case they shoul= d look in the ELisp manual. There's also a Help command to find the documentation no matter which manual it is in: "C-h S". This command allows to find the manual, an= y manual, where some symbol is defined, and it in a way makes all the manuals a single searchable database. You can try it with current-buffer, if you like. There are also "C-h F" and "C-h K". No similar command for variables exists, but it could be added if deemed important.