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: Tue, 6 Jun 2017 14:10:19 +0900 Message-ID: <0BB64F35-233A-471F-B99F-51F96C4E6CCB@gmail.com> References: 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 1496725863 17461 195.159.176.226 (6 Jun 2017 05:11:03 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Tue, 6 Jun 2017 05:11:03 +0000 (UTC) To: emacs-devel Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Jun 06 07:10:59 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 1dI6le-0004Fr-L5 for ged-emacs-devel@m.gmane.org; Tue, 06 Jun 2017 07:10:58 +0200 Original-Received: from localhost ([::1]:36272 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dI6lj-00049K-U3 for ged-emacs-devel@m.gmane.org; Tue, 06 Jun 2017 01:11:03 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:47691) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dI6lA-00049C-6n for emacs-devel@gnu.org; Tue, 06 Jun 2017 01:10:29 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dI6l6-0006FL-V3 for emacs-devel@gnu.org; Tue, 06 Jun 2017 01:10:28 -0400 Original-Received: from mail-pf0-x236.google.com ([2607:f8b0:400e:c00::236]:36708) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dI6l6-0006Ew-Ng for emacs-devel@gnu.org; Tue, 06 Jun 2017 01:10:24 -0400 Original-Received: by mail-pf0-x236.google.com with SMTP id m17so93010741pfg.3 for ; Mon, 05 Jun 2017 22:10:24 -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=ynOA+xH+JA6HbA8sWxNYwjjn45hZ348ciSwNPf3kr20=; b=GutIKxFmT62f+GiQutUEenQT1k9us3x+rwd0WxMH38YkTLWAZh2XyJVUBM9YYj/UME NFMf7OxpcKXDYOdvxS+qOZr2iTK8NTDmzrY/qj7PaisU26JCeoBl1nZaoMEFn3EeAMsR BuRmP1j3a+CINEVAjqjKCR4V0UiYn5sgccngHQUA+zKZXseEd7aQcJuwR7/rk4pRS3oz cwIdAyPW0/zm74Z8M54WZ9tRthJRpJDMlAjfiqk4ASsZKjPh4pp+j5VBw/4zFnb7dpw1 Fyi5IlBPLxW7T03CE2lz0BIvST27nXPxHtRjiRvTH3nY/N7J5CtsAW78AG1bOLJVyYbc /n5w== 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=ynOA+xH+JA6HbA8sWxNYwjjn45hZ348ciSwNPf3kr20=; b=emKMMmrHK42QRIXncr72qvu/tB05NDuhcEZVQbfAjYuzoQPeqp/UouoPpsE7AXl1E5 ix721W6iUQ5Tju9n3/GwJb6gZhmMz2rk6AIMN/NYX0ec6mfWRDtwGfamSCBtTbxoQsep an/QZly1UVqQWyJ9FlRM04AmCTgyIVavNeURIFvlx7F7gjYrfuQHQhqOGaaivlMnXaHS aYzEIkj+JoRI1i1V3wAA9AKJPZpmhU18/DEGmrP83Gi2ibDNNGVDxcT6lUI4BI2eNSXs trI+skvRDU+DkT9lkmImnhbQ1XHBlrzUVOIKX6OcPGbJpLfdh0ca0EYEJDQEasZe0auv 1vxg== X-Gm-Message-State: AODbwcD9avUbge0jCfDtiSGZZcwBpSRamCElM/j+qr8t8o+rFGfMhXJH Q38iSQFKTFe5oMTiYAY= X-Received: by 10.84.233.143 with SMTP id l15mr15923518plk.216.1496725823386; Mon, 05 Jun 2017 22:10:23 -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 c29sm64555888pfj.101.2017.06.05.22.10.21 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Mon, 05 Jun 2017 22:10:22 -0700 (PDT) In-Reply-To: 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::236 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:215467 Archived-At: > 2017/06/06 9:09=E3=80=81Tino Calancha = =E3=81=AE=E3=83=A1=E3=83=BC=E3=83=AB: >=20 >> I was thinking (naively?) that having the docstrings on one side and = the reference on the other side was not a very efficient way to maintain = documentation. Is everything in the documentation actually written by = hand based on the docstrings? Wouldn't it be nicer to have good = docstrings and use them directly in the documentation to avoid = duplication of work? Is there any reason I'm not seeing why this is not = happening? > Hi, >=20 > you might wish to read the following thread: > https://lists.gnu.org/archive/html/emacs-devel/2016-04/msg00452.html Wow, did I open a can of worms... :) Fascinating thread. Just a few comments. Having a mechanism that generates automatic documentation (a la javadoc) = would be extremely valuable. By just having that "reference" it would = suggest developers to adopt a more standardized format/style. The elisp reference should definitely extend the descriptions by adding = exemples so that people learn from reading (which is admittedly = difficult with the docstrings only). Maybe not go as far as a cookbook, = but a bit more than what we have would be very welcome (there is a = *huge* gap between the Introduction and the Reference). My initial worry is that the day we start l10n (and we'll get there = eventually :), we're going to have a huge amount of redundancy. But the = flip side is that we're going to have also a huge amount of feedback on = both the docstrings and the elisp reference... Jean-Christophe=20=