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: Thu, 8 Jun 2017 12:48:19 +0900 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> 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 1496893723 409 195.159.176.226 (8 Jun 2017 03:48:43 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Thu, 8 Jun 2017 03:48:43 +0000 (UTC) To: emacs-devel Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Jun 08 05:48:39 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 1dIoR2-0008FU-Km for ged-emacs-devel@m.gmane.org; Thu, 08 Jun 2017 05:48:36 +0200 Original-Received: from localhost ([::1]:47186 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dIoR8-0000TT-5B for ged-emacs-devel@m.gmane.org; Wed, 07 Jun 2017 23:48:42 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:54488) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dIoQv-0000ST-LV for emacs-devel@gnu.org; Wed, 07 Jun 2017 23:48:30 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dIoQr-0007Aq-Ob for emacs-devel@gnu.org; Wed, 07 Jun 2017 23:48:29 -0400 Original-Received: from mail-pg0-x234.google.com ([2607:f8b0:400e:c05::234]:35150) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dIoQr-00079b-Ip for emacs-devel@gnu.org; Wed, 07 Jun 2017 23:48:25 -0400 Original-Received: by mail-pg0-x234.google.com with SMTP id k71so11638693pgd.2 for ; Wed, 07 Jun 2017 20:48:25 -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=EkuX78CsWmpW27xNbKBcy1Bm+hirn/SifZKqolmXM5o=; b=MHmXe7cmkW66uDYcdDYEsE+mx4crhdqTrJFcYbqUuIdvNIe3c0Lt6b1vygsOFNCWaT fWsrLdJGhlI2TCOcf+Tb4Ou+5n+8uXTF/p87tZunpCnjDEiLDbTfz4inTyYVcRRSQ4yD 9DWMg4JAkfCQnPQvDCVtmvRQdJEdVkOfH8X0zGAvwzEw6eIQIadSh+qfvp/wm/h2JVTa Wz9EVNQWItNdCj8CRlh+Ld4dzoS4mEtT8uZlNIv2Ri9n/CWK6VrxEgJsTVQ2uRaQoaZd 8jPMKUeoKV8muGwFe364uyKfYbRqEQ4Pw4mqMJuFdGwyPFWJAkmid2K9NuSSCquMatBL e0RQ== 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=EkuX78CsWmpW27xNbKBcy1Bm+hirn/SifZKqolmXM5o=; b=tBkO8c6QU3wxSbEdp1DCjpapCc3aaDmo0fRg9lQ/t+Sfdm935W6PZmWr6Al1m6ga/b dX0XM+v+Kwn0tY7vTNnilccSTrupFTSxpCNXjN8bVpLoSxzvIrMgPQr6V9GeW1Y/IZMH fPDeFvf0L6chYlV2eFzYC43hm7cE546E7V65FiDxyfBG73kODynbrkYLMCg6qovXCCMt vvl5bjuYvfCgXcmNY1UAXX6rnW3GWiZg71VWYvLEDotkNOC9DI8io5tUjrW9ZJAN2WJX swpqUQ8nxooT0UwtCpxlGXoj1xo+nJEjPy0dXnGpq1J13NpcnEfQtnX1i7A/loxz3wFx 1KcQ== X-Gm-Message-State: AODbwcAWIQHGGvOxU5W47XhmlrqNg5Tb2vo9B2v5E9esFqQiVzFtDlRj KolCHSVRkcXvcPB+kNE= X-Received: by 10.84.231.141 with SMTP id g13mr31872503plk.157.1496893704270; Wed, 07 Jun 2017 20:48:24 -0700 (PDT) Original-Received: from [10.251.103.132] ([210.160.37.43]) by smtp.gmail.com with ESMTPSA id c123sm5975163pfa.100.2017.06.07.20.48.20 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 07 Jun 2017 20:48:22 -0700 (PDT) In-Reply-To: <878tl3rz38.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:c05::234 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:215516 Archived-At: It was really not my intent to raise the temperature of this list to = that level. Apologies for that. But the discussion is really = interesting. 1) I'll read the Doc Strings and Manuals in the GNU Coding Standards. 2) my remark about javadoc was not intended to suggest a replacement of = the current documentation, but to have a document that has all the = docstring information (Emacs API) in one place. It would be an = alternative to the info system, with exactly the same contents. It would = be a great tool to find API information and also very practical to check = if the rules defined in the GNU Coding Standards are respected. 3) my remark about duplication was full answered in the discussion and = I'll have even better insights when I complete 1) above. So I'll just = put that aside for the moment. My perspective was not exclusively l10n = but also ease of access to information for beginners, etc. 4) regarding "semantic support" (although I'm not 100% sure what Etienne = is referring to here) it seems to me that there are a number of not so = hard things to do on the (some ?) texi conversion templates. I've been = working on a CSS for the manuals and I found the HTML conversion = templates remarkably underused (I'm currently discussing this on = help@texinfo). Even while maintaining legacy HTML support, there are = plenty of areas where CSS selectors could be added to considerably = enhance the output. There are even some regressions, for ex, the 4.8 = version I was unknowingly working with until this morning added a = class=3D"defun" to definitions, and that class information is gone in = 6.3 (replaced by a generic
tag). I understand I'm going in a lot of directions at the moment, sorry for = that. Jean-Christophe=20 > Jun 8, 2017 11:29=E3=80=81Etienne Prud=E2=80=99homme = =E3=81=AE=E3=83=A1=E3=83=BC=E3=83=AB: >=20 > Drew Adams writes: >=20 >> And this is not JavaDoc. The Elisp manual is not purely >> and simply an API reference manual. >=20 > It=E2=80=99s worth mentioning that JavaDoc documentation style is = particularly > useful for Object-Oriented Programming and strongly typed languages. = I > think it=E2=80=99s even mandatory with OOP to be readable. >=20 > However, I also think Jean-Christophe makes a good point about > documentation generation. Not with duplication, but semantic support. > While documentation support is awesome in Emacs with GNU libraries, = it=E2=80=99s > not always so with third-party documentation tools. I=E2=80=99m = thinking about > Zeal (and to a very limited extent Dash that is not free). >=20 > Those tools are highly effective for semantic indexation for newcomers > since they offer a simple interface for hundred FLOSS libraries. GNU > projects are almost nonexistent. >=20 > I=E2=80=99ve 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=E2=80=99s really hard to extract meaningful = definitions > from texi files. >=20