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: Thu, 08 Jun 2017 16:22:06 -0400 Message-ID: <878tl2nsb5.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> <834lvq8q3o.fsf@gnu.org> <8737bapcze.fsf@x230.lts> <83vao670lq.fsf@gnu.org> 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 1496953340 32609 195.159.176.226 (8 Jun 2017 20:22:20 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Thu, 8 Jun 2017 20:22:20 +0000 (UTC) User-Agent: Emacs/25.2 (gnu/linux) Cc: stephen_leake@stephe-leake.org, drew.adams@oracle.com, emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Jun 08 22:22:16 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 1dJ3we-0008B0-EY for ged-emacs-devel@m.gmane.org; Thu, 08 Jun 2017 22:22:16 +0200 Original-Received: from localhost ([::1]:51343 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dJ3wi-0006rk-4H for ged-emacs-devel@m.gmane.org; Thu, 08 Jun 2017 16:22:20 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:43334) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dJ3wb-0006nN-Vy for emacs-devel@gnu.org; Thu, 08 Jun 2017 16:22:14 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dJ3wb-0001tw-18 for emacs-devel@gnu.org; Thu, 08 Jun 2017 16:22:13 -0400 Original-Received: from mail-qt0-x243.google.com ([2607:f8b0:400d:c0d::243]:35081) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dJ3wX-0001rt-9i; Thu, 08 Jun 2017 16:22:09 -0400 Original-Received: by mail-qt0-x243.google.com with SMTP id x58so10765025qtc.2; Thu, 08 Jun 2017 13:22:09 -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=bajOnzC/Umh9I2jI3M2j7Rs5w5LC2Yb2kkysRRVYR/o=; b=YlJFDyk0GE7/btsKUY8cE7wXW8ASM4c1qpPNfCKj44nWz0f4peMALScZCggplYLm5B SuCrj/UKtwJrw4GS3FllTyIHZXHzE6hJS9kUF5r3hmy2c/oHpzqqUgK6HXuUNifuaKrd UtytGKIm72r+ak5asfFDLZzGsHHsPClFTTu7ykTA6A25Hn/SO5Mb30IxSz8eC2qNKbUI amooMiRqaFNyNct7sbJj8hlhhEiBXB/11+RaQvECP5ufR92GqHvHJFtivDoD7rMQbAgr eq7RgcPxzFXB5BZxkKD9D69O/ve2agPEdGw0ysnmhyzdU45wlZD7QQ0EQy1rbvMCRFKu SRfA== 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=bajOnzC/Umh9I2jI3M2j7Rs5w5LC2Yb2kkysRRVYR/o=; b=ByPJTzubSYZ9BoTkIMwt74AUsoDlUF4Vql+IBv+q7JTBA6IZrbFdkynFh/lmqa/wcn ufKi/1VRkOk/MFs3ngmOkOOtQUJS3nhl0P5xnesBTgFB1jj8eG4DTukXAl4mxWYh4Szw JOF2bASJd8KI7Wa/radLsi6caKXUCbqNScMlLCqMZHSXYa+RkD5ezWG/Buk5kIAqM+iV HW+s2xD6Xi/gUTnOcPlHFn4+VwawnlZheQq8jksZcljXKWsvZicOZ9LR+YfFsVE0Gq61 oXINdehaCFCuqsx7nPUWZ/tGDY1gZsv/OFxV+ym3QHSJqN7X5DH0m0x8ODPHsb2/v7Mj ZisA== X-Gm-Message-State: AODbwcD7JuK4lKOL9KrbIun4gxxVgOa1StfuCc6W+gKKzns2e0m8uJAM +pZtL9s6KGCpR4OPMWGvkQ== X-Received: by 10.55.4.135 with SMTP id 129mr42237659qke.10.1496953328342; Thu, 08 Jun 2017 13:22:08 -0700 (PDT) Original-Received: from localhost (modemcable232.49-20-96.mc.videotron.ca. [96.20.49.232]) by smtp.gmail.com with ESMTPSA id t8sm293676qkt.45.2017.06.08.13.22.07 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 08 Jun 2017 13:22:07 -0700 (PDT) In-Reply-To: <83vao670lq.fsf@gnu.org> (Eli Zaretskii's message of "Thu, 08 Jun 2017 22:14:57 +0300") X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2607:f8b0:400d:c0d::243 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:215532 Archived-At: I want to make it clear I=E2=80=99m not questionning the usefulness of Texi= nfo, nor I am criticizing the Emacs documentation system. > Not sure I understand what is it that you allude to. We always used > different Texinfo commands for different kinds of symbols: @defmac for > macros, @defvar for variables, @defun for functions, "@deffn Command" > for commands, @defspec for special forms, etc. That=E2=80=99s great and I hope we continue to use this system. > We _are_ in an Emacs forum, where the Emacs way of doing things is the > "normal" way. And I definitely wouldn't say that the Emacs help > system is "insane" by any measure. E.g., it offers hyperlinks that > everyone is accustomed to. Far from me to say that the Emacs way is insane! Forgive me father Eli. I=E2=80=99m only pointing out that Emacs normal way of doing things is pret= ty different from editors like Atom or many new (hackable) editors used. I=E2=80=99m only talking about documentation here. Whether Emacs way is be= tter, I=E2=80=99m probably too biased to tell, but people coming from those edito= rs are not used to _some_ of the documentation interface we provide. That being said, I can bodly say that the Elisp printed manual is much better than any other text-editors or program API I know. The original subject of this thread was =E2=80=9Cdocstrings and elisp reference=E2=80=9D i.e. JavaDoc comments style. I=E2=80=99m thinking about= ways we could add relevant semantic information in either source. We already have support for some of that in docstrings i.e. =E2=80=98\\[]=E2=80=99 or = =E2=80=98\\<>=E2=80=99. I=E2=80=99m sorry if it looked like I was addressing other points. > I still feel I don't understand the nature of that difficulty. Looking at the source of the generated HTML documents, I think I might have confused porting other GNU documentations. I once tried to make the Autoconf documentation available on Zeal at almost the same time as I tried with Elisp. Jean-Christophe seems to be right about using more the HTML conversion templates. Some of the semantic tagging is lost in the HTML conversion and that=E2=80=99s where the difficulty was. -- Etienne