From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Jean-Christophe Helary Newsgroups: gmane.emacs.devel Subject: Re: docstrings and elisp reference Date: Sat, 10 Jun 2017 10:06:37 +0900 Message-ID: <54A01FC0-6692-411D-91CB-764402C7BF14@gmail.com> 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> <87h8zpge1y.fsf@x230.lts> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 (Mac OS X Mail 10.3 \(3273\)) Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1497056816 28463 195.159.176.226 (10 Jun 2017 01:06:56 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sat, 10 Jun 2017 01:06:56 +0000 (UTC) To: emacs-devel Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Jun 10 03:06:49 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 1dJUrZ-0006xo-1O for ged-emacs-devel@m.gmane.org; Sat, 10 Jun 2017 03:06:49 +0200 Original-Received: from localhost ([::1]:56888 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dJUre-00077H-AJ for ged-emacs-devel@m.gmane.org; Fri, 09 Jun 2017 21:06:54 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:35154) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dJUrX-000779-Ig for emacs-devel@gnu.org; Fri, 09 Jun 2017 21:06:48 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dJUrU-0000L8-Dq for emacs-devel@gnu.org; Fri, 09 Jun 2017 21:06:47 -0400 Original-Received: from mail-pf0-x230.google.com ([2607:f8b0:400e:c00::230]:33917) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dJUrU-0000KR-8Q for emacs-devel@gnu.org; Fri, 09 Jun 2017 21:06:44 -0400 Original-Received: by mail-pf0-x230.google.com with SMTP id 15so5944147pfc.1 for ; Fri, 09 Jun 2017 18:06:42 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:content-transfer-encoding:mime-version:subject:date:references :to:in-reply-to:message-id; bh=ley9QVWjAe6rnyefvboMIh2jJRgBv+6Lo/5VEcDvTZs=; b=uzN9yz2NTnPOe047/W7cZ/fyPKBgshZUUjZkPtnByYaB4k+HRyDDToxUu/3nFT1Q9W XBMh+/h/QYsOD8AgnTseeT+oepsuuwYb6QZnfgdjp6Ao/LOuoEQR7GTy00I5CSmmIO7W xBcgkYxkagaD70ZvfvpQUi6gCePF9B8lN4PCHpKNql3pd7ZAvYfYC7jp6ANbDaOK7pGh ywdvs9HrLe0uAWwdEdFEblf93rta1XjJQ2QLfaQeO8JFGu3L/+sgpohxaE8zZK9GUETe pF4UmJ2KC5UDrmgGwecBfs99JKvto9OyfuEp6tUVH8rjXm9BXGTix9li0gqml+DNx30q bo9g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:content-transfer-encoding:mime-version :subject:date:references:to:in-reply-to:message-id; bh=ley9QVWjAe6rnyefvboMIh2jJRgBv+6Lo/5VEcDvTZs=; b=seerZ3rJ3ZRJmhJLrLqYKg4FjRyUDKEz7flPbG63toWl0T3AyAAwIY6vsfEnplcJBd cH7Lfvad8L6g82V2hp2/ntUGsoW6H8Hhu0YGUzJpsdcIkR/2WZP7Koq6ZIKK7Mah+3bM vWiDxF0MsDNm+NTwXs1ZUPbBzh4My7vVQ4CuMJ+B2x3Jrb9XOhx5MGH0hZG/UgsBNMqh phWA610ZoHXWoLpfh32KsNoO6B3LdxzdULkKEsypN2f+ObCM6Gk+hihhA+uwQYQv5lMF bvKOrSGwJu778lT85EA+9Hd47hg+6O0etC0ufl557O1mnBSG5JBlVLxly7siOyO3SXdS X15Q== X-Gm-Message-State: AODbwcB8KbJQPUzr5ON0+KyX5JJRDh1HfLR7hslV9yTzAiCOyG9tySOO uiZnEIf1RZT6lGBTmzs= X-Received: by 10.84.229.14 with SMTP id b14mr43791220plk.14.1497056801666; Fri, 09 Jun 2017 18:06:41 -0700 (PDT) Original-Received: from [192.168.24.55] (pl2587.ag0304.nttpc.ne.jp. [128.53.196.27]) by smtp.gmail.com with ESMTPSA id u20sm4913556pfa.17.2017.06.09.18.06.39 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 09 Jun 2017 18:06:40 -0700 (PDT) In-Reply-To: <87h8zpge1y.fsf@x230.lts> X-Mailer: Apple Mail (2.3273) X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2607:f8b0:400e:c00::230 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:215547 Archived-At: > On Jun 10, 2017, at 4:24, Etienne Prud=E2=80=99homme = wrote: >=20 > 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 texi > 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. I'd like to point out that in the 2014 thread that I was referred to = earlier, RMS asked whether it would be possible to implement some = display features (display/hide nodes, etc.) with HTML and Stephen = Turnbull replied that, well, yes it was possible and relatively easy. https://lists.gnu.org/archive/html/emacs-devel/2014-12/msg01911.html Reading the whole thread shows that there was already some kind of = consensus back in 2014 about what we could do with the HTML output (ie = much more than what we do now) and how we could/should improve it. So, my personal conclusion for the current thread is that: 1) We need to improve the texinfo export templates for HTML (I have no = opinion for the other templates, but it could be the same) so that *no* = information is lost in the conversion process and possible some = information is added. 2) the i18n infrastructure that is very slowly emerging will allow for = extraction of docstrings along with messages, so that we'll eventually = be able to use that to create a "javadoc" like output for the docstrings = with the information that Etienne mentioned earlier: > Emacs Lisp doc strings have support for some of JavaDoc features, but > cannot compare in many things. Many things described in doc strings = are > informal and are pretty difficult to extract. For example, we have no > formal way of telling: >=20 > - the type of the function return value > - what exceptions can be thrown from the function > - does this function has side effects > - since when it was introduced > - it=E2=80=99s a hook variable > - if the comment includes a file system path in the example >=20 > And many other things I don=E2=80=99t have in mind now. 3) When we have 1) and 2) we can have a fully interlinked HTML = documentation set that could be used as a standard format for Emacs (as = was discussed in 2014) *and* as a base format for all sorts of = documentation display applications that use HTML as the standard, so = that Emacs documentation system features are not limited to the Emacs = application but are literally all over the place. Jean-Christophe=