From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: =?utf-8?Q?Etienne_Prud=E2=80=99homme?= Newsgroups: gmane.emacs.devel Subject: Re: docstrings and elisp reference Date: Fri, 09 Jun 2017 15:24:09 -0400 Message-ID: <87h8zpge1y.fsf@x230.lts> 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> <877f0ln3dx.fsf@x230.lts> <83poed7i4t.fsf@gnu.org> <83o9tx7b7d.fsf@gnu.org> <83mv9h73o1.fsf@gnu.org> <83lgp16zpw.fsf@gnu.org> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1497036265 27426 195.159.176.226 (9 Jun 2017 19:24:25 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Fri, 9 Jun 2017 19:24:25 +0000 (UTC) User-Agent: Emacs/25.2 (gnu/linux) Cc: emacs-devel@gnu.org, stephen_leake@stephe-leake.org, rms@gnu.org, drew.adams@oracle.com, Yuri Khan To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Jun 09 21:24:20 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 1dJPW8-0006rC-Cq for ged-emacs-devel@m.gmane.org; Fri, 09 Jun 2017 21:24:20 +0200 Original-Received: from localhost ([::1]:56141 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dJPWD-0001Au-GN for ged-emacs-devel@m.gmane.org; Fri, 09 Jun 2017 15:24:25 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:53995) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dJPW6-0001Ak-QE for emacs-devel@gnu.org; Fri, 09 Jun 2017 15:24:19 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dJPW5-0003xD-Ny for emacs-devel@gnu.org; Fri, 09 Jun 2017 15:24:18 -0400 Original-Received: from mail-it0-x241.google.com ([2607:f8b0:4001:c0b::241]:35422) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dJPW0-0003v5-9Q; Fri, 09 Jun 2017 15:24:12 -0400 Original-Received: by mail-it0-x241.google.com with SMTP id 67so6706289itx.2; Fri, 09 Jun 2017 12:24:12 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version:content-transfer-encoding; bh=Bs/UH6yr5FAfRUWipJCjROxBTh/nsF+93EXp1IKPlQY=; b=Fd7Qt1Y6fgKNj/qfLr7wjhnbLLnr2NyRhqSalGhdwZcvCivtdqi8XStbXg1Es0oBUF ocgeh1QngwYvbCRo7O4+HSbYX086KCFge3Atr+I+EZulD/kcBA8A3oopDHTY0R3yoTwl 9y1tMEqXqXK8j8F9rMI4Wwfuyp3+dtX76VVNgW/e/JlG3/fSsemwhsgqDgLEPpGZNWr7 GPs6RRp9DFxCPsQC94a3J+1MYkULx/sxUtq0Q5tywODnD2DZjJ4Lw4iVprPKNhaW1hZS i/MgyHzF7gea1bjV6R2F0DO0uIZpAoNgFX/070Ma7qJEI2oo7zDe/7dCKBopCGl62EM1 /yjg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:references:date:in-reply-to :message-id:user-agent:mime-version:content-transfer-encoding; bh=Bs/UH6yr5FAfRUWipJCjROxBTh/nsF+93EXp1IKPlQY=; b=QAbZCxlbW8irs3VL18slSYlmTpjb61ySOOOinu5C5cxtHQrITetIX7DdpjReMwSXMk FVq7vDIyhfAwqzqmtrUKTH8StS2odxmVy2zUM3Bk0FQLLsXtGVPo7FMdaO44at0s+a7m C1emDJzN7FT0uevsWZn+wJsWaJgZsYzHATRn+g6XLnIXPpTDCgTGGsU7fcqM7Zm5Rfft T4x5CHK7eS6YJVzGSqXH5m3AZ0Pdo1lAFPMvoivWSpEXhsHn+Hbl9jIU7RA6E8pyguXp kCjq9r55rG/HG0rfVlHIclA7fL0Yy7SHUbiPhoHS99b+L2cFitOyJa3dZBPDSKKUsw11 Af9A== X-Gm-Message-State: AODbwcBqjL80fj0O6miXKe6K5DPT/2+E1etOkmNDXUWvIYkpZgrkPi5w hVnDPaoN0eXLmup2eHQTCg== X-Received: by 10.36.4.73 with SMTP id 70mr1078323itb.113.1497036251091; Fri, 09 Jun 2017 12:24:11 -0700 (PDT) Original-Received: from localhost (modemcable232.49-20-96.mc.videotron.ca. [96.20.49.232]) by smtp.gmail.com with ESMTPSA id w195sm859232iof.31.2017.06.09.12.24.09 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 09 Jun 2017 12:24:10 -0700 (PDT) In-Reply-To: <83lgp16zpw.fsf@gnu.org> (Eli Zaretskii's message of "Fri, 09 Jun 2017 16:46:19 +0300") X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2607:f8b0:4001:c0b::241 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:215545 Archived-At: Eli Zaretskii writes: > I don't know what you mean by "for the most part", but since it cannot > simply display a GNU manual converted to HTML by texi2any, I guess > something else is needed that a docset needs to provide that isn't > readily available. So packages need to _want_ to provide this format, > otherwise their docs will not be viewable in Zeal. You previously said that you had enough of this discussion and I would understand if you don=E2=80=99t read it. I explained the process in a resp= onse to RMS: > Therefore, for an index to be created, we either have to use Natural > Language Processing (which we never do) or use some kind of clues in > the HTML document describing the type of information to index. > The perfect way would be to use XML directly, but few or no projects > use it. We instead rely on the HTML tag class names from the > documentation documents. Almost every time, they can be really > helpful to know the type of the tagged information. Most developpers > making the CSS stylesheets use names like =E2=80=9Cfunction=E2=80=9D (or = an other > arbitrary name) when tagging the functions. That=E2=80=99s the same for > variables, macros, etc. But as I said also in the same post, it looks like Jean-Christophe is right in saying we don=E2=80=99t use the exporting templates enough. The t= exi files seems to have a lot of meaningful =E2=80=9Ctags=E2=80=9D (I call that= semantic) we could use when exporting the manual documentation to HTML. Why not even use JavaScript to enable searching the manuals and/or expanding/collapsing setions. A good example of what could be done is the ECMAScript 2018 Language Specifications[1]. [1] https://tc39.github.io/ecma262/ (WARNING: It looks a JS file doesn=E2= =80=99t contain any license information for LibreJS users, but the blocked script is licensed under MIT). -- Etienne