From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Richard Stallman Newsgroups: gmane.emacs.devel Subject: Re: docstrings and elisp reference Date: Fri, 09 Jun 2017 00:10:31 -0400 Message-ID: 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> Reply-To: rms@gnu.org 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 1496981530 927 195.159.176.226 (9 Jun 2017 04:12:10 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Fri, 9 Jun 2017 04:12:10 +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 Fri Jun 09 06:12:07 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 1dJBHK-0008Nk-1y for ged-emacs-devel@m.gmane.org; Fri, 09 Jun 2017 06:12:06 +0200 Original-Received: from localhost ([::1]:52524 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dJBHP-0002MV-CX for ged-emacs-devel@m.gmane.org; Fri, 09 Jun 2017 00:12:11 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:37009) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dJBGA-0001gm-97 for emacs-devel@gnu.org; Fri, 09 Jun 2017 00:10:55 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dJBG8-0006Pz-VI for emacs-devel@gnu.org; Fri, 09 Jun 2017 00:10:53 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:33509) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dJBFo-0006Ib-Mm; Fri, 09 Jun 2017 00:10:32 -0400 Original-Received: from rms by fencepost.gnu.org with local (Exim 4.82) (envelope-from ) id 1dJBFn-0001Vt-V3; Fri, 09 Jun 2017 00:10:31 -0400 In-reply-to: <878tl3rz38.fsf@x230.lts> (message from Etienne =?utf-8?Q?Pru?= =?utf-8?Q?d=E2=80=99homme?= on Wed, 07 Jun 2017 22:29:47 -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:215536 Archived-At: [[[ To any NSA and FBI agents reading my email: please consider ]]] [[[ whether defending the US Constitution against all enemies, ]]] [[[ foreign or domestic, requires you to follow Snowden's example. ]]] > It’s worth mentioning that JavaDoc documentation style is particularly > useful for Object-Oriented Programming and strongly typed languages. I > think it’s even mandatory with OOP to be readable. I could be mistaken, but I think that Javadoc is comparable to Emacs Lisp doc strings. 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"? > Those tools are highly effective for semantic indexation for newcomers What is that? > since they offer a simple interface for hundred FLOSS libraries. Could you explain what "a simple interface" to a library means? Normally each library defines its own interface. GNU > projects are almost nonexistent. You can't mean that literally, so what do you mean? Maybe "semantic support" should be added to Emacs Lisp, but until I know what it means, I can't have an opinion. > I’ve been trying in the past to port GNU projects documentation and I > finally gave up. I find Texinfo to be very limited when it comes to > semantic support. It’s really hard to extract meaningful definitions > from texi files. I think what you are trying to do does not make sense. You can't extract the full description of a single function from a good manual because a good manual does not try to describe each function separately. What you want for this is something like a doc string, and a good manual is not like a collection of doc strings. -- Dr Richard Stallman President, Free Software Foundation (gnu.org, fsf.org) Internet Hall-of-Famer (internethalloffame.org) Skype: No way! See stallman.org/skype.html.