emacs-orgmode
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [O] "COMMENT" keyword not properly documented in the manual


From: Alain . Cochard
Subject: Re: [O] "COMMENT" keyword not properly documented in the manual
Date: Tue, 10 Jan 2017 08:36:36 +0100

Hi, and thanks for the feedback.

Nicolas Goaziou writes on Mon  9 Jan 2017 00:51:

 > > Unaware that "COMMENT" was a specific org string,

[...]

 > > I had used it at the beginning of a headline, resulting in biased tag
 > > and string searches ('C-c a m' or 'C-c a s'). (I was unlucky: the
 > > color of the headline was the same as the COMMENT's, so I did not
 > > notice anything strange.) I think I finally understood, and found
 > > about the org-agenda-skip-comment-trees variable, but...

[...]

 > > So it seems to me that something about "COMMENT" should be said at
 > > some place(s) in the "Agenda views" section.

 > Considering COMMENT is primarily export related, one option would
 > be to make `org-agenda-skip-comment-trees' to nil as a default. In
 > this case, it might not even be necessary to document this variable
 > in the manual.
 > 
 > WDYT?

I was initially tempted to suggest that nil would indeed be a better
default for this variable, but in this related post
https://lists.gnu.org/archive/html/emacs-orgmode/2013-05/msg00287.html
Samuel Wales says that

  "It defaults to `t' which I think is a good default."

Considering the time that you experts spend on endless discussions
about what the default value of some variable should be, I'd rather
remain agnostic on this one.  But unless the use of this variable is
obsolete, I feel it has to be documented -- could be as discreet as
one sentence in a footnote.  Otherwise, with a nil default, even
people using the export features would have difficulties to know about
it.

(More generally, what would be the harm of having some appendix with a
list of all customizable variables?  Seems to me it could help
beginners to learn Org; sure, there is 'C-h v org-<TAB>', but it's not
exactly the same for me.)

a.

-- 
EOST (École et Observatoire des Sciences de la Terre) 
IPG (Institut de Physique du Globe) | address@hidden
5 rue René Descartes   [bureau 106] | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France    | Fax:   +33 (0)3 68 85 01 25     


reply via email to

[Prev in Thread] Current Thread [Next in Thread]