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

[Nicolas Goaziou]

Hello,

alain.coch...@unistra.fr writes:

> 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.

I dropped a note about in "agenda views" part of the manual.
>
> (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-', but it's not
> exactly the same for me.)

There is a lot of variables. We cannot possibly document all of them in
the manual. However, the best way for a beginnier to discover these
options is probably to call "M-x customize-group RET org RET".

Regards,

-- 
Nicolas Goaziou0x80A93738

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

[Matt Price]

On Sun, Jan 8, 2017 at 6:51 PM, Nicolas Goaziou 
wrote:

> Hello,
>
> alain.coch...@unistra.fr writes:
>
> > Unaware that "COMMENT" was a specific org string,
>
> It is special only at the beginning of a headline (but past TODO keyword
> and priority cookie, if any).
>
> > 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'll just say that once I learned about COMMENT -- from the list, not from
the manual -- I started using it pretty extensively.  Also, the Github
org-->html renderer hides COMMENT trees by default.  For these reasons, I
think the current default is sensible.  But yeah, it should be
documented.

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

[Samuel Wales]

that was bastien :)

On 1/10/17, alain.coch...@unistra.fr  wrote:
> Samuel Wales says that

-- 
The Kafka Pandemic: http://thekafkapandemic.blogspot.com

The disease DOES progress.  MANY people have died from it.  And
ANYBODY can get it.

Denmark: free Karina Hansen NOW.
  UPDATE 2016-10: home, but not fully free

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

[Alain . Cochard]

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-', 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) | alain.coch...@unistra.fr
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 

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

[Nicolas Goaziou]

Hello,

alain.coch...@unistra.fr writes:

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

It is special only at the beginning of a headline (but past TODO keyword
and priority cookie, if any).

> 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?

-- 
Nicolas Goaziou

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

[Alain . Cochard]

Hello.  I am a relatively new org user; I am writing this email after
I spent all morning finding the origin of my problem and searching the
web for an explanation and a solution.

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...

But I don't see how I could have avoided the problem.  As far as I can
see, the "COMMENT" string only appears in the "Exporting > Comment
lines" subsection of the manual (plus a cryptic part in the "Hacking >
Using the mapping API" appendix).  So if one is not yet concerned with
exporting, one does not feel compelled to go into such details...
Besides, it isn't even specified that COMMENTing interferes with
agenda searches.

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

Regards

-- 
EOST (École et Observatoire des Sciences de la Terre) 
IPG (Institut de Physique du Globe) | alain.coch...@unistra.fr
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