From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: docstrings and elisp reference Date: Thu, 08 Jun 2017 22:14:57 +0300 Message-ID: <83vao670lq.fsf@gnu.org> References: <0BB64F35-233A-471F-B99F-51F96C4E6CCB@gmail.com> <8360g99n07.fsf@gnu.org> <86lgp4q2xa.fsf@stephe-leake.org> <7acc7d4f-23cc-4b6a-b062-ef92805e465b@default> <878tl3rz38.fsf@x230.lts> <834lvq8q3o.fsf@gnu.org> <8737bapcze.fsf@x230.lts> Reply-To: Eli Zaretskii NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Trace: blaine.gmane.org 1496949320 26451 195.159.176.226 (8 Jun 2017 19:15:20 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Thu, 8 Jun 2017 19:15:20 +0000 (UTC) Cc: stephen_leake@stephe-leake.org, drew.adams@oracle.com, emacs-devel@gnu.org To: Etienne =?utf-8?Q?Prud=E2=80=99homme?= Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Jun 08 21:15:13 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 1dJ2tl-0006Vs-1K for ged-emacs-devel@m.gmane.org; Thu, 08 Jun 2017 21:15:13 +0200 Original-Received: from localhost ([::1]:51136 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dJ2tq-0003WK-4V for ged-emacs-devel@m.gmane.org; Thu, 08 Jun 2017 15:15:18 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:54578) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dJ2td-0003VN-KP for emacs-devel@gnu.org; Thu, 08 Jun 2017 15:15:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dJ2tZ-0006gq-Ib for emacs-devel@gnu.org; Thu, 08 Jun 2017 15:15:05 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:36239) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dJ2tZ-0006gm-Es; Thu, 08 Jun 2017 15:15:01 -0400 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:1531 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1dJ2tY-0002hI-CR; Thu, 08 Jun 2017 15:15:01 -0400 In-reply-to: <8737bapcze.fsf@x230.lts> (message from Etienne =?utf-8?Q?Pru?= =?utf-8?Q?d=E2=80=99homme?= on Thu, 08 Jun 2017 14:10:13 -0400) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e 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:215528 Archived-At: > From: Etienne Prud’homme > Cc: stephen_leake@stephe-leake.org, drew.adams@oracle.com, emacs-devel@gnu.org > Date: Thu, 08 Jun 2017 14:10:13 -0400 > > > What's more, at least the docs it has for Bash and ELisp are exactly > > the respective Texinfo manuals, with the same text and the same node > > structure. What is the advantage of using a different browser for the > > exact same text? > > That’s my point. I must confess that the available documentation for > Elisp has better support now for choosing whether we search for a macro, > command, function, etc. It used to index every symbols in the same > entry type (variable entry). Not sure I understand what is it that you allude to. We always used different Texinfo commands for different kinds of symbols: @defmac for macros, @defvar for variables, @defun for functions, "@deffn Command" for commands, @defspec for special forms, etc. > Furthermore, we could support much more indexation capabilities given > the list of supported entry types[1]. If Texinfo lacks some of these, they could easily be added as the language continues to evolve and being developed. I see no fundamental problems here, just something to code. > What I meant was really the uniform search interface it provides. For > advanced Emacs users, it’s not a problem looking what we want from Emacs > itself (or Info entries), but for a newcomers, it might look insane. We _are_ in an Emacs forum, where the Emacs way of doing things is the "normal" way. And I definitely wouldn't say that the Emacs help system is "insane" by any measure. E.g., it offers hyperlinks that everyone is accustomed to. > People are now used to search engines when looking at documentation. Did you try giving a list of keywords to the Emacs apropos commands? That feature was added in Emacs 23, I think. IOW, Emacs uses search-engine techniques as well, always did. You cannot find your way through hundreds of pages of manuals without some reasonably smart indexing and searching facilities. > > This should be discussed on the Texinfo list, not here. The current > > Texinfo translator is highly customizable, so it could be that it can > > be adapted to these needs much better. > > Since we were talking about Emacs, I thought this thread was more > appropriate. I was refferring to the difficulty of porting GNU Emacs > Lisp documentation to the Dash docset format. I still feel I don't understand the nature of that difficulty.