From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: phillip.lord@newcastle.ac.uk (Phillip Lord) Newsgroups: gmane.emacs.devel Subject: Re: Comment conventions, adding an explicit Header. Date: Thu, 30 Oct 2014 16:38:56 +0000 Message-ID: <87r3xpbjhb.fsf@newcastle.ac.uk> References: <87d299eu1d.fsf@newcastle.ac.uk> <87a94dd5hi.fsf@newcastle.ac.uk> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1414781022 18022 80.91.229.3 (31 Oct 2014 18:43:42 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 31 Oct 2014 18:43:42 +0000 (UTC) Cc: emacs-devel@gnu.org To: Stefan Monnier Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Oct 31 19:43:35 2014 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 1XkHAd-0005v4-8m for ged-emacs-devel@m.gmane.org; Fri, 31 Oct 2014 19:43:35 +0100 Original-Received: from localhost ([::1]:41024 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XkHAc-0001t1-Su for ged-emacs-devel@m.gmane.org; Fri, 31 Oct 2014 14:43:34 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:60804) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XkEHe-00026K-En for emacs-devel@gnu.org; Fri, 31 Oct 2014 11:39:37 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1XjskV-0003r8-AW for emacs-devel@gnu.org; Thu, 30 Oct 2014 12:39:07 -0400 Original-Received: from cheviot22.ncl.ac.uk ([128.240.234.22]:60273) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XjskV-0003qr-43 for emacs-devel@gnu.org; Thu, 30 Oct 2014 12:38:59 -0400 Original-Received: from smtpauth-vm.ncl.ac.uk ([10.8.233.129] helo=smtpauth.ncl.ac.uk) by cheviot22.ncl.ac.uk with esmtp (Exim 4.63) (envelope-from ) id 1XjskS-0007zd-Fh; Thu, 30 Oct 2014 16:38:56 +0000 Original-Received: from jangai.ncl.ac.uk ([10.66.67.223] helo=localhost) by smtpauth.ncl.ac.uk with esmtpsa (TLSv1:AES128-SHA:128) (Exim 4.63) (envelope-from ) id 1XjskS-0008Vg-KO; Thu, 30 Oct 2014 16:38:56 +0000 In-Reply-To: (Stefan Monnier's message of "Thu, 30 Oct 2014 11:36:12 -0400") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.3 (gnu/linux) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 128.240.234.22 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:176130 Archived-At: Stefan Monnier writes: >> True. Currently, I handle the first line specially (as does emacs) >> because otherwise you end up with level 1 header with, for example, the >> lexical-binding instruction in it. > > outline-minor-mode doesn't handle it specially. I don't mind having the > lexical-binding thingy in there, since it means that when the file > "fully folded" I can still immediately know whether the file is using > lexical-binding or not. This is true. Likewise, the same is true with the summary. Of course, you can still see this in the org mode file, and it never folds. But as a comment, it will not get rendered to any output. It's not ideal, but I wanted to get something working, to see if it makes sense first. >> Also, in the org-mode transformation I translate this into a org-mode >> comment. The reason for this is that org-mode also has a "start of file" >> semantics -- the lines before the first header is special. > > Not knowing what this "special" implies, it's hard to judge whether it's > important. I'm not a high-power org-mode user either, am afraid, so it's hard for me to judge too. Things defined before the start, generally apply to the whole document, so things like new "drawers" are defined here, or keywords for TODO boxes. Likewise, titles for output, latex headers and so on. > The few files that use ";;;" for sectioning *within* the code itself > don't seem to use "single word with a colon" very much. E.g. a quick > grep shows things like: > > lisp/wid-edit.el:;;; Utility functions. > lisp/wid-edit.el:;;; Widget text specifications. > lisp/wid-edit.el:;;; Widget Properties. > lisp/view.el:;;; Commands that enter or exit view mode. > lisp/view.el:;;; Some help routines. > lisp/view.el:;;; Commands for moving around in the buffer. > lisp/vc/ediff-util.el:;;; Build keymaps > lisp/vc/ediff-util.el:;;; Setup functions > lisp/vc/ediff-util.el:;;; Commands for working with Ediff > lisp/vc/ediff-util.el:;;; Copying diffs. Indeed. These will not currently be treated as sections. I could make them so. In practice, files do need modifying to work with my code. Most obviously, org-mode needs all the code blocks to be marked up. I have been doing this by marking ALL of the file after the header, and then splitting the org code blocks later. I fix sectioning as I go. All good feedback. Can I conclude that so far there would be no show stopping problem with adding a ";;; Header:" line where it was wanted? Phil