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 01:20:26 -0400 Message-ID: <877f0ln3dx.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> 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 1496985675 569 195.159.176.226 (9 Jun 2017 05:21:15 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Fri, 9 Jun 2017 05:21:15 +0000 (UTC) User-Agent: Emacs/25.2 (gnu/linux) Cc: stephen_leake@stephe-leake.org, drew.adams@oracle.com, emacs-devel@gnu.org To: Richard Stallman Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Jun 09 07:21: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 1dJCMA-0008KM-Az for ged-emacs-devel@m.gmane.org; Fri, 09 Jun 2017 07:21:10 +0200 Original-Received: from localhost ([::1]:52636 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dJCMF-0001Yc-LJ for ged-emacs-devel@m.gmane.org; Fri, 09 Jun 2017 01:21:15 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:45714) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dJCLb-0001YL-V0 for emacs-devel@gnu.org; Fri, 09 Jun 2017 01:20:37 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dJCLa-0004K7-Qg for emacs-devel@gnu.org; Fri, 09 Jun 2017 01:20:35 -0400 Original-Received: from mail-qt0-x242.google.com ([2607:f8b0:400d:c0d::242]:33061) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dJCLW-0004JS-8k; Fri, 09 Jun 2017 01:20:30 -0400 Original-Received: by mail-qt0-x242.google.com with SMTP id w1so12940960qtg.0; Thu, 08 Jun 2017 22:20:28 -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=oEbd/R9uNikkt9rtDr9OHDTfm3ddm/5uzQjdd+wndZM=; b=G99Ti4keVc/FN8GhzwyWZX4cz23fJRcEsnKLyI8qOWhnxmB09hw3T7BYryMBu0lBQK GehP3mb2RbM7wnRjcPmQ2Th29pd5pMM+KejhJP8Hlm7+vTE38jqr9eDrAzU6jycnoMze 9oGzSgQySP7qDfckS/90mfCNraZzGI91bryhU0/D0Scmwmb+zEz43aGdOq1hCF3NU8+F 3iCJ1FSvVIkuJ16v3KzUp7l5/fXRLV5XF4YmhxrnToQzFbuX+SeVpeCxCzRoSp5KY5PD zNIbXKFGDjczwIJbigqqnMDXCU80qm8hUatT67SvEU088GYc9h8gJyxe894/tib0tKss ezCw== 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=oEbd/R9uNikkt9rtDr9OHDTfm3ddm/5uzQjdd+wndZM=; b=I4cF2XxIqh1cGCqz5TvXVAYXFMNmJKoDu0HE03nbXBI8ARRABG9+eKb5563lNo4QbA B/wmNRJaiahBqE/FEKie0CY45UYam8EprbVcaaidRrFVEV/ddSJMvhS0VGWD/olMNPf7 70FGZq0InEhjvcARY6RtU9b724UIPcaqLWEk8SpKQ5v+MNlSUUY1d3795XCjUJXfeXX+ eTAV1koH0q+iCYnwrwvWVA+onCqQYLunwy/SJOAMvFbtDBAcnVDAK8XrPFekACVkzboc 0hDAQLPX1AmPYL39orEgSPVJ8/Ix2MrmPZlQTTVHzWPWpFACpMncrbSom48zxN22Xxkh avxg== X-Gm-Message-State: AODbwcB2ky+rkYo7iZaPgqMaWPaakO2/FWNNnQfl2vZI0ZNEVlIxdP+G TKlUe/SiCcXGODPh8t5Faw== X-Received: by 10.200.41.135 with SMTP id 7mr46603082qts.85.1496985628038; Thu, 08 Jun 2017 22:20:28 -0700 (PDT) Original-Received: from localhost (modemcable232.49-20-96.mc.videotron.ca. [96.20.49.232]) by smtp.gmail.com with ESMTPSA id o76sm29830qke.34.2017.06.08.22.20.26 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 08 Jun 2017 22:20:27 -0700 (PDT) In-Reply-To: (Richard Stallman's message of "Fri, 09 Jun 2017 00:10:31 -0400") X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2607:f8b0:400d:c0d::242 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:215537 Archived-At: Richard Stallman writes: > I could be mistaken, but I think that Javadoc is comparable to Emacs > Lisp doc strings. 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: - 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 And many other things I don=E2=80=99t have in mind now. Of course, some of those things are directly addressed with options variables. > If that is correct, then of course Javadoc documentation is useful. > Emacs Lisp doc strings are useful too. But concatenating them does > not make a clear tutorial/reference manual. We need both! > > > However, I also think Jean-Christophe makes a good point about > > documentation generation. Not with duplication, but semantic support. > What is "semantic support"? It is more or less tagging useful information about the content generated. Particularly useful when doing indexation of either comments or the documentation. As I said another response, _I have mistaken_ some other GNU tools that I tried to port at the same time as the Emacs Lisp manual. I think it could apply to both the reference manual and the doc strings in general. =09=09=09=09=09=09=09=09=20=20=20=20=20=20 > > GNU projects are almost nonexistent. > > You can't mean that literally, so what do you mean? The tool I described is an offline documentation viewer. The docset is what is interesting. What we usually call docset is a tarball with the documentation and an index tagging the documentation. The index is a standardized SQLite table with a restricted set of identifiers and their classes. There are several programs allowing searching this documentation standard. Zeal is an example, but the _helm-dash_ MELPA package also offers a basic interface for searching the docs. In order to make a docset, we can use documentation generators like JavaDoc, Doxygen, etc. We can also use the online documentation provided by the project. This way, the documentation is either fetched from the website (like Mozilla Developer Network) or the HTML version of a project is taken. To make indexation, we generally make small programs to record all functions/macros/variables/... and their reference in an HTML document. This way, the index can easily be updated when the documentation changes without having to review each references. 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 arbitrar= y name) when tagging the functions. That=E2=80=99s the same for variables, macros, etc. That is where _most_ GNU projects seem to lack the capability. It looks like Jean-Christophe was right in pointing out it might be because we=E2=80= =99re not using HTML exporting templates at its best. GNU projects are usually harder to index because of that. Thus we have a minority of GNU tools listed. I=E2=80=99m not saying that for criticizing GNU, but I think it=E2=80=99s an important issue we could address in the ne= ar future. Of course, this discussion is about Emacs. I hope I clarified some of what I said. -- Etienne