From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Stefan Monnier Newsgroups: gmane.emacs.devel Subject: Re: docstrings and elisp reference Date: Wed, 07 Jun 2017 09:03:04 -0400 Message-ID: References: <0BB64F35-233A-471F-B99F-51F96C4E6CCB@gmail.com> <8360g99n07.fsf@gnu.org> <86lgp4q2xa.fsf@stephe-leake.org> <878tl4976i.fsf@fastmail.fm> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: blaine.gmane.org 1496840658 28507 195.159.176.226 (7 Jun 2017 13:04:18 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Wed, 7 Jun 2017 13:04:18 +0000 (UTC) User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.0.50 (gnu/linux) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Jun 07 15:04:11 2017 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dIad6-0006yV-Ty for ged-emacs-devel@m.gmane.org; Wed, 07 Jun 2017 15:04:09 +0200 Original-Received: from localhost ([::1]:43348 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dIadC-0002DO-D5 for ged-emacs-devel@m.gmane.org; Wed, 07 Jun 2017 09:04:14 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:45807) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dIacH-0002A7-Gr for emacs-devel@gnu.org; Wed, 07 Jun 2017 09:03:21 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dIacD-0001a8-KY for emacs-devel@gnu.org; Wed, 07 Jun 2017 09:03:17 -0400 Original-Received: from [195.159.176.226] (port=40375 helo=blaine.gmane.org) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dIacD-0001Zj-E8 for emacs-devel@gnu.org; Wed, 07 Jun 2017 09:03:13 -0400 Original-Received: from list by blaine.gmane.org with local (Exim 4.84_2) (envelope-from ) id 1dIac5-0003xB-GD for emacs-devel@gnu.org; Wed, 07 Jun 2017 15:03:05 +0200 X-Injected-Via-Gmane: http://gmane.org/ Original-Lines: 20 Original-X-Complaints-To: usenet@blaine.gmane.org Cancel-Lock: sha1:6DEbcQ7F1f6kOm40WoDRL1p1m1k= X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 195.159.176.226 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:215495 Archived-At: > And yet, the Elisp manual documents a large number of functions and > variables / options in a format that is very reminiscent of doc strings and > which provides basically the same information. Agreed. And I also think this is a problem. >From where I stand, the way to fix it is: - Better integration between the manual browser and the docstring browser, so you can click on a function/variable name in the manual to get to its docstring and you can easily jump from a docstring to the relevant section of the manual. - Remove the redundant var/fun documentation from the manual (this is a tedious job: there is some redundance but it's not systematic, so we can't just do this removal systematically). - Come up with a way to re-add those var/fun documentation into the printed manual (e.g. by adding to the Texinfo source external references to docstrings, which are then processed by now ad-hoc script). Stefan