From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mark Shoulson Subject: Re: Comments and control lines (# vs. #+) Date: Fri, 25 May 2012 02:14:22 +0000 (UTC) Message-ID: References: Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Return-path: Received: from eggs.gnu.org ([208.118.235.92]:45032) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SXk3b-000090-Dh for emacs-orgmode@gnu.org; Thu, 24 May 2012 22:15:12 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1SXk3Z-0000eb-Mo for emacs-orgmode@gnu.org; Thu, 24 May 2012 22:15:10 -0400 Received: from plane.gmane.org ([80.91.229.3]:54759) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SXk3Z-0000eR-GP for emacs-orgmode@gnu.org; Thu, 24 May 2012 22:15:09 -0400 Received: from list by plane.gmane.org with local (Exim 4.69) (envelope-from ) id 1SXk3U-0004MP-5R for emacs-orgmode@gnu.org; Fri, 25 May 2012 04:15:04 +0200 Received: from pi.meson.org ([96.56.207.26]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Fri, 25 May 2012 04:15:04 +0200 Received: from mark by pi.meson.org with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Fri, 25 May 2012 04:15:04 +0200 List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: emacs-orgmode@gnu.org Samuel Wales gmail.com> writes: > > The following, which is general and I wrote a long time ago, > might also be relevant to the recent thread on comments > breaking lists. > > === > > There might be really good reasons for the #+ comment > convention in Org, but I am not sure what they are. So > please bear with me. Probably the most important one is that # is often used in ordinary writing without the intent of commenting out the rest of the line. Like saying "We're #1" or talking about #hashtags. It could be escaped for things like that, maybe, but the whole point is to keep the markup as minimal and unobtrusive as possible. Comments are specifically a departure from the norm; they are things *excluded* from the usual functioning of whatever they're in. Let _them_ be what has to get extra markup. #+ is a sufficiently rare combination that it can be spared. > This list is not complete or minimal. Please disregard the > items you don't like. Most of them can't really counter the above issue, I think (you may feel otherwise). > 1) #+ is not as standard as # Standards are per-format anyway. > 2) there are tools for commenting and uncommenting regions > with #, but not with #+ Org is its own tool. If it needs region-commenting features, let them be added, and they can use #+. Besides, the COMMENT keyword in headlines also comments out regions quite effectively (if the region is a subtree). > 4) imported (or pasted) text will often have # commenting > and this will need special processing to make it work > with Org This is perfectly sensible if you're a programmer (I haven't seen # used as a comment character anywhere outside of computer-parsable input). Org has a much larger scope than talking about programming. I would say that "Imported (or pasted) text will often have # without intending to comment and this will need special processing..." That's more or less what I said above. Org is mainly about prose. If you're pasting in programs with comments they probably belong in code-blocks anyway. > 5) fill functions and packages often don't understand #+ Org is its own tool, and is what's best suited for editing org files. > 6) plain # works in column 0 in Org, leading to user > expectation that it will behave consistently in other > columns as it does in most other languages that use # # in column 0 is a special case precisely for something simpler than #+ since # is rarely seen in column 0 in ordinary text, though it could happen if a # sign or something like #1 happened to be wrapped at a bad place. This present paragraph does serve as a counterexample, to be sure, but I think it is a rare case. ~mark