* Comments and control lines (# vs. #+)
@ 2012-05-23 17:02 Samuel Wales
2012-05-25 2:14 ` Mark Shoulson
2012-08-02 9:47 ` Bastien
0 siblings, 2 replies; 4+ messages in thread
From: Samuel Wales @ 2012-05-23 17:02 UTC (permalink / raw)
To: Nicolas Goaziou; +Cc: Daniel Schoepe, emacs-orgmode
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.
This list is not complete or minimal. Please disregard the
items you don't like.
===
Here are some of the reasons I prefer # to #+ as a
consistent commenting scheme for Org.
1) #+ is not as standard as #
2) there are tools for commenting and uncommenting regions
with #, but not with #+
3) many users have their own tools that do not
understand #+
4) imported (or pasted) text will often have # commenting
and this will need special processing to make it work
with Org
5) fill functions and packages often don't understand #+
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 #
7) parsing commented comments is more complicated and
error-prone when both are used
8) internal and external parsers might or might not expect
a more standard commenting scheme.
9) indented #+ is not colored as a comment or a control
line
10) it is natural to want to do a block comment on a
section of a list without breaking list structure.
there are built-in tools for this.
11) it is natural to want to do an indented comment on a
single list item at the same level of indentation as
the bullet
12) there are tools for auto-fill and indentation within
comments that take into account # but not #+
13) some parsers probably expect a single character
14) internal and external parsers might want a
special-case-free commenting scheme
15) #+ indicates an Org control line, so using it for
comments overloads the syntax
Hope it's of some use.
Thanks.
Samuel
--
The Kafka Pandemic: http://thekafkapandemic.blogspot.com
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: Comments and control lines (# vs. #+)
2012-05-23 17:02 Comments and control lines (# vs. #+) Samuel Wales
@ 2012-05-25 2:14 ` Mark Shoulson
2012-08-02 9:47 ` Bastien
1 sibling, 0 replies; 4+ messages in thread
From: Mark Shoulson @ 2012-05-25 2:14 UTC (permalink / raw)
To: emacs-orgmode
Samuel Wales <samologist <at> 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
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: Comments and control lines (# vs. #+)
2012-05-23 17:02 Comments and control lines (# vs. #+) Samuel Wales
2012-05-25 2:14 ` Mark Shoulson
@ 2012-08-02 9:47 ` Bastien
2012-08-07 22:05 ` Samuel Wales
1 sibling, 1 reply; 4+ messages in thread
From: Bastien @ 2012-08-02 9:47 UTC (permalink / raw)
To: Samuel Wales; +Cc: Daniel Schoepe, emacs-orgmode, Nicolas Goaziou
Hi Samuel,
Samuel Wales <samologist@gmail.com> writes:
> Hope it's of some use.
Yes it has been. If you pull from latest repo, the way comments
are handled have been updated. Specifically, there is no "#+ "
anymore. Please check carefully and let us know.
--
Bastien
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: Comments and control lines (# vs. #+)
2012-08-02 9:47 ` Bastien
@ 2012-08-07 22:05 ` Samuel Wales
0 siblings, 0 replies; 4+ messages in thread
From: Samuel Wales @ 2012-08-07 22:05 UTC (permalink / raw)
To: Bastien; +Cc: Daniel Schoepe, emacs-orgmode, Nicolas Goaziou
This is excellent!
Samuel
On 8/2/12, Bastien <bzg@gnu.org> wrote:
> Yes it has been. If you pull from latest repo, the way comments
> are handled have been updated. Specifically, there is no "#+ "
> anymore. Please check carefully and let us know.
--
The Kafka Pandemic: http://thekafkapandemic.blogspot.com
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2012-08-07 22:05 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2012-05-23 17:02 Comments and control lines (# vs. #+) Samuel Wales
2012-05-25 2:14 ` Mark Shoulson
2012-08-02 9:47 ` Bastien
2012-08-07 22:05 ` Samuel Wales
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).