Problem in org-inlinetask-min-level's docstring?

Problem in org-inlinetask-min-level's docstring?

[Alain.Cochard]

The last paragraph of this docstring is:

   It is strongly recommended that you set ‘org-cycle-max-level’ not
   at all, or to a number smaller than this one.  In fact, when
   ‘org-cycle-max-level’ is not set, it will be assumed to be one less
   than the value of smaller than the value of this variable.

I do not understand the last sentence, even assuming that the 1st 'of'
is 'or'.   Is my English the problem?

Thanks

-- 
EOST (École et Observatoire des Sciences de la Terre) 
ITE (Institut Terre & Environnement) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 110]  | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France     | [ slot available for rent ]

Re: Problem in org-inlinetask-min-level's docstring?

[Ihor Radchenko]

Alain.Cochard@unistra.fr writes:

> The last paragraph of this docstring is:
>
>    It is strongly recommended that you set ‘org-cycle-max-level’ not
>    at all, or to a number smaller than this one.  In fact, when
>    ‘org-cycle-max-level’ is not set, it will be assumed to be one less
>    than the value of smaller than the value of this variable.
>
> I do not understand the last sentence, even assuming that the 1st 'of'
> is 'or'.   Is my English the problem?

That sentence is indeed screwed up.

Does `org-cycle-max-level' docstring sound better?

    Maximum level which should still be subject to visibility cycling.
    Levels higher than this will, for cycling, be treated as text, not a headline.
    When `org-odd-levels-only' is set, a value of N in this variable actually
    means 2N-1 stars as the limiting headline.
    When nil, cycle all levels.
    Note that the limiting level of cycling is also influenced by
    `org-inlinetask-min-level'.  When `org-cycle-max-level' is not set but
    `org-inlinetask-min-level' is, cycling will be limited to levels one less
    than its value.

We may simply replace the faulty sentence with a link to
`org-cycle-max-level' docstring.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Problem in org-inlinetask-min-level's docstring?

[Alain.Cochard]

Ihor Radchenko writes on Fri 25 Nov 2022 10:33:
 > Alain.Cochard@unistra.fr writes:

 > > I do not understand the last sentence, even assuming that the 1st
 > > 'of' is 'or'.  Is my English the problem?
 > 
 > That sentence is indeed screwed up.
 > 
 > Does `org-cycle-max-level' docstring sound better?

Yes.

NB: While experimenting, I noticed that, if I customize
org-cycle-max-level to 0, then a <TAB> on a headline generates the
cryptic "org-match-line: Invalid regexp: "Invalid content of
\\{\\}"".  

 > We may simply replace the faulty sentence with a link to
 > `org-cycle-max-level' docstring.

-- 
EOST (École et Observatoire des Sciences de la Terre) 
ITE (Institut Terre & Environnement) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 110]  | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France     | [ slot available for rent ]

Re: Problem in org-inlinetask-min-level's docstring?

[Ihor Radchenko]

Alain.Cochard@unistra.fr writes:

> Ihor Radchenko writes on Fri 25 Nov 2022 10:33:
>  > Alain.Cochard@unistra.fr writes:
>
>  > > I do not understand the last sentence, even assuming that the 1st
>  > > 'of' is 'or'.  Is my English the problem?
>  > 
>  > That sentence is indeed screwed up.
>  > 
>  > Does `org-cycle-max-level' docstring sound better?
>
> Yes.

Fixed on main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=45dc19516

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

[BUG] org-cycle-max-level is broken, especially when using org-element-cache (was: Problem in org-inlinetask-min-level's docstring?)

[Ihor Radchenko]

Alain.Cochard@unistra.fr writes:

> NB: While experimenting, I noticed that, if I customize
> org-cycle-max-level to 0, then a <TAB> on a headline generates the
> cryptic "org-match-line: Invalid regexp: "Invalid content of
> \\{\\}"".  

Well. It does not really make much sense to set this variable to 0 or
negative values. I guess we can add a guard against such scenarios.

Also, this whole thing is broken when cache is active.

I will need to look into this further. The current approach with
let-binding org-outline-regexp appears to be broken, especially when
using element cache.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [BUG] org-cycle-max-level is broken, especially when using org-element-cache (was: Problem in org-inlinetask-min-level's docstring?)

[Alain.Cochard]

Ihor Radchenko writes on Tue 13 Dec 2022 07:36:
 > Alain.Cochard@unistra.fr writes:
 > 
 > > NB: While experimenting, I noticed that, if I customize
 > > org-cycle-max-level to 0, then a <TAB> on a headline generates the
 > > cryptic "org-match-line: Invalid regexp: "Invalid content of
 > > \\{\\}"".  
 > 
 > Well. It does not really make much sense to set this variable to 0
 > or negative values.  I guess we can add a guard against such
 > scenarios.

Indeed, it does not make sense, but I realized it only when I fully
understood the behavior.

If one experiments, customizing several variables in row, it will take
time to identify the origin of the message.  Specifying in the
documentation of the Customize buffer (=customize docstring?) that the
value of this variables has to be greater than or equal to 1 will
certainly help; also having as the error message, instead of the
current one, would be even better (perhaps that is what you call a
"guard").


-- 
EOST (École et Observatoire des Sciences de la Terre) 
ITE (Institut Terre & Environnement) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 110]  | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France     | [ slot available for rent ]