From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Stefan Monnier Newsgroups: gmane.emacs.devel Subject: Re: Modern conventions for structuring Emacs Lisp libraries Date: Sat, 05 Oct 2013 20:42:17 -0400 Message-ID: References: <87hacvn8sm.fsf@gmail.com> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1381020154 6409 80.91.229.3 (6 Oct 2013 00:42:34 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 6 Oct 2013 00:42:34 +0000 (UTC) Cc: emacs-devel@gnu.org To: Thorsten Jolitz Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Oct 06 02:42:37 2013 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1VScQc-0008EA-Lx for ged-emacs-devel@m.gmane.org; Sun, 06 Oct 2013 02:42:34 +0200 Original-Received: from localhost ([::1]:53398 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VScQc-00082v-0R for ged-emacs-devel@m.gmane.org; Sat, 05 Oct 2013 20:42:34 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:56982) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VScQT-00081v-Vn for emacs-devel@gnu.org; Sat, 05 Oct 2013 20:42:32 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VScQO-0004pW-33 for emacs-devel@gnu.org; Sat, 05 Oct 2013 20:42:25 -0400 Original-Received: from ironport2-out.teksavvy.com ([206.248.154.182]:6672) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VScQN-0004pS-TT for emacs-devel@gnu.org; Sat, 05 Oct 2013 20:42:20 -0400 X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: Av8EABK/CFHO+K8t/2dsb2JhbABEvw4Xc4IeAQEEAScvIwULCw4mEhQYDSQcD4dzBsEtkQoDoUmDMYFegxOBSiQ X-IPAS-Result: Av8EABK/CFHO+K8t/2dsb2JhbABEvw4Xc4IeAQEEAScvIwULCw4mEhQYDSQcD4dzBsEtkQoDoUmDMYFegxOBSiQ X-IronPort-AV: E=Sophos;i="4.84,565,1355115600"; d="scan'208";a="34844344" Original-Received: from 206-248-175-45.dsl.teksavvy.com (HELO pastel.home) ([206.248.175.45]) by ironport2-out.teksavvy.com with ESMTP/TLS/ADH-AES256-SHA; 05 Oct 2013 20:38:46 -0400 Original-Received: by pastel.home (Postfix, from userid 20848) id D87EE6050E; Sat, 5 Oct 2013 20:42:17 -0400 (EDT) In-Reply-To: <87hacvn8sm.fsf@gmail.com> (Thorsten Jolitz's message of "Sat, 05 Oct 2013 15:31:37 +0200") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.3.50 (gnu/linux) X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 206.248.154.182 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 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-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:163900 Archived-At: > as a second take on this topic, I would like to make the attached > proposal for improving the conventions for structuring Emacs Lisp > source-code files: Thanks. I think it'd be good to improve the current situation, but I don't think anything more than refinement is an option. IOW changing the convention is not really an option for various reasons, such as the fact that several tools rely on it, and there are so many files using it, many of which we can't fix, that we'd be stuck with two different conventions for the next many years. > 2.2.1 Last Line Pathology > ------------------------- This is a very minor issue, I think. It's trivil to fix it by simply ignoring any "trailing header". > 2.2.2 Wasted First Level Weakness > --------------------------------- > | 7 matches for "^;;; " in buffer: help.el.gz > | 1:;;; help.el --- help commands for Emacs > | 25:;;; Commentary: > | 30:;;; Code: > | 280:;;; `User' help functions > | 967:;;; Automatic resizing of temporary buffers. > | 1041:;;; Help windows. > | 1193:;;; help.el ends here > `---- > The above example, produced by typing '1' in the associated > *Navi-buffer* of help.el (-> show headlines up-to first-level), shows > this weakness quite clearly: > 1. in a file with some 1200 lines of code, there are 7 1st-level > headlines > 2. at most 3 (if not only 2) of 7 headlines should really be 1st-level > headlines: Again, this seems like a rather minor issue. Furthermore, ";;; Code:" is a well-known header, so if needed, we can special case it in code such as navi. > all other headlines in the header-comment section are subheadlines of > this one, i.e. level 2 or higher. You can get that without any modification to existing files by considering that any header that comes before ";;; Code:" is really one deeper than what its semi-colons say. > In oldschool Elisp files, headlines often end in colons. In Org-mode, > this is not usual, and the Org-mode conventions are better in this > case. Again, trivial to "fix" in any tool like navi: just change a trailing colon into a full stop. > The otherwise fantastic library dired.el illustrates why: All those non-headers are bugs. > 8) shows a wild mix of real headlines and comments. This is because it > is only natural for people to get creative with comment characters Maybe it was a bad idea to choose this convention, but it's easier to fix the few cases where people's use of comments ends up accidentally colliding with your convention. > | 1:;; * iorg-scrape.el --- elisp glue code for `picoLisp/lib/scrape.l' Note that ";; *" is already in common use for other purposes (basically the * is used as a bullet point there), so your convention would also bump into other problems. > A big plus: this is /major-mode agnostic/. All 3 libraries (outshine, I'm pretty sure there are many other languages that define their own notion of comment structure, and I'd be surprise if any of them happens to choose your convention. IOW your convention is "major-mode agnostic" at the cost of not following the "normal" conventions. Just as is the case with allout.el. This is a trade-off with its benefit and its downsides. The other option is to make your tools's structuring convention sufficiently customizable that it can make adapt to the "normal" convention (this is the path taken by outline.el). It's not perfect either, of course, but I think that given the obstacles it's either to adapt the tools than to change the conventions. > Conversion between oldschool and outshine headlines would be > exceedingly easy - as long as the oldschool files don't mix comments > and headlines, i.e don't have "invalid" syntax (in a loose sense). Exactly: if they're correct, then the conversion is easy. So easy that you can do it on the fly, without touching the file! ;-) > | ;; * iorg-scrape.el --- elisp glue code for `picoLisp/lib/scrape.l' > | ;; ** MetaData > | ;; :PROPERTIES: > | ;; :copyright: Thorsten_Jolitz > | ;; :copyright-since: 2013 IIUC the syntax of the "copyright" line is legally significant (e.g. whether years can be abbreviated, whether year ranges can be used, etc...), and I don't think I want to get into discussions about what other syntax we can use. So I'm not interested in changing the copyright line. > | ;; :version: 0.9 The ";; Version:" format is used in ELPA, so changing it would require changes in too many places. Not gonna happen. > | ;; :licence: GPL3+ > | ;; :licence-url: http://www.gnu.org/licenses/ Here again, the many-lines blurb about the license has legal significance (otherwise we'd have switched to ";; License: GPLv3+" by now). > 2. Since a [Property API] for Org-mode's properties exists, reading > and writing them from an Emacs Lisp program becomes almost trivial. Reading them is already trivial (via the lisp-mnt.el library). Writing is usually very easy already; the only exception could the "Keywords:" header which is just a big problem in itself anyway (we don't really know which categories should be available). > 3 Summary > ========= Damn! You skipped the part I was looking for: the "Commentary:" section. I do want this part to be refined. More specifically, I'd like someone to come up with a description of a markup format to use there (99% compatible with what we already have), together with code that can turn such a Commentary section into nicely rendered text in an Emacs buffer. Stefan