New startup options, show<n>levels

New startup options, show<n>levels

[Gustav Wikström]

Prompted by a question on StackOverflow, https://stackoverflow.com/questions/56536184/set-initial-visiblity-to-a-certain-level-in-org-mode, a few new options are added to the startup setting.

Patch is applied to master as this is non-critical and it is communicated here and now for full transparency. See commit hash a71ac14e4, 
https://code.orgmode.org/bzg/org-mode/commit/a71ac14e46bb820abdbd2e6651c58179c50eb2fa

Hope these new options will be usable for some of you!

Kind Regards
Gustav

Re: New startup options, show<n>levels

[Bastien]

Hi Gustav,

Gustav Wikström <gustav@whil.se> writes:

> Prompted by a question on StackOverflow,
> https://stackoverflow.com/questions/56536184/set-initial-visiblity-to-a-certain-level-in-org-mode,
> a few new options are added to the startup setting.

thanks -- in the future, I suggest discussing such additions on this
list before committing them.  In this case, I think we could come up
with better option names than "show2levels", even if I don't have a
better suggestion right now.

> Patch is applied to master as this is non-critical and it is
> communicated here and now for full transparency. See commit hash
> a71ac14e4,
> https://code.orgmode.org/bzg/org-mode/commit/a71ac14e46bb820abdbd2e6651c58179c50eb2fa

Mandatory nitpick: the log should contain proper sentences, ending
with a dot.  I'm mentioning this because your other commit has the
same small error.

> Hope these new options will be usable for some of you!

It sure is, thanks for taking care of this,

-- 
 Bastien

Re: New startup options, show<n>levels

[Gustav Wikström]

[-- Attachment #1: Type: text/plain, Size: 2074 bytes --]

Hi Bastien,

Thanks for the feedback.

Regarding naming, there may ofc be other possibilities. I considered spelling the level out but discarded that option due to its verbosity. I find this quite elegant actually. One might argue that it's not general enough, with 2 to 5 hard-coded. But thinking of the use-case a bit more, I struggled to find a reason for more dynamics.

I don't object to the mailing list RFC method of doing things, but in this case it felt like a too small contribution for that trouble. Had there been a more streamlined pull-request workflow than the list I'm sure I'd have taken another decision. In this case the option was to just not do it due to time and energy constraints.

Nitpick noted, I'll try to care better with ending sentences moving forward!

Best
Gustav
________________________________
From: Bastien <bzg@gnu.org>
Sent: Saturday, December 12, 2020 6:54:21 PM
To: Gustav Wikström <gustav@whil.se>
Cc: emacs-orgmode@gnu.org <emacs-orgmode@gnu.org>
Subject: Re: New startup options, show<n>levels

Hi Gustav,

Gustav Wikström <gustav@whil.se> writes:

> Prompted by a question on StackOverflow,
> https://stackoverflow.com/questions/56536184/set-initial-visiblity-to-a-certain-level-in-org-mode,
> a few new options are added to the startup setting.

thanks -- in the future, I suggest discussing such additions on this
list before committing them.  In this case, I think we could come up
with better option names than "show2levels", even if I don't have a
better suggestion right now.

> Patch is applied to master as this is non-critical and it is
> communicated here and now for full transparency. See commit hash
> a71ac14e4,
> https://code.orgmode.org/bzg/org-mode/commit/a71ac14e46bb820abdbd2e6651c58179c50eb2fa

Mandatory nitpick: the log should contain proper sentences, ending
with a dot.  I'm mentioning this because your other commit has the
same small error.

> Hope these new options will be usable for some of you!

It sure is, thanks for taking care of this,

--
 Bastien

[-- Attachment #2: Type: text/html, Size: 3955 bytes --]

Re: New startup options, show<n>levels

[Eric S Fraga]

On Saturday, 12 Dec 2020 at 18:54, Bastien wrote:
> In this case, I think we could come up with better option names than
> "show2levels", even if I don't have a better suggestion right now.

I agree.  I had started responding to Gustav when the original post
appeared but then aborted my response.  I wonder whether something like
levels:N or show:N or content:N is possible in a startup setting, akin
to H:N in options?

I do have (org-content N) often in my file local variables in any case.
-- 
: Eric S Fraga via Emacs 28.0.50, Org release_9.4-160-g7c8dce

Re: New startup options, show<n>levels

[TEC]

Eric S Fraga <e.fraga@ucl.ac.uk> writes:

> I wonder whether something like levels:N or show:N or content:N is
> possible in a startup setting, akin to H:N in options?

If I may toss my opinion into the ring, "show:N" seems like the most
intuitive syntax to me :)

--
Timothy

Re: New startup options, show<n>levels

[TEC]

Eric S Fraga <e.fraga@ucl.ac.uk> writes:

> I wonder whether something like levels:N or show:N or content:N is
> possible in a startup setting, akin to H:N in options?

If I may toss my opinion into the ring, "show:N" seems like the most
intuitive syntax to me :)

--
Timothy

Sv: New startup options, show<n>levels

[Gustav Wikström]

Hi,

I believe we still can change the name if that’s preferred. I'm not overly attached to the name I committed, although I fail to see the ugliness in it. And it's only in master since a few days. No biggie to change.

In my opinion it's important to see the names in their context. One context is the other available startup options.

Principles I tried to follow when choosing the names (Alt 0 below):
1) Keep the name as close to the intent as possible. It should be possible to understand it based on name alone, if possible. (I.e. avoid ambiguity)
2) Let the pattern for the name match with the pattern already existing for names in its surrounding context.
3) Keep it short, but prefer principle 1 and 2 to short.

The following options have been presented, where the first one is already in master:

Already in master (Alt 0): 
 `overview'        Top-level headlines only.  
 `content'         All headlines.             
 `show2levels'     Headline levels 1-2.       
 `show3levels'     Headline levels 1-3.       
 `show4levels'     Headline levels 1-4.       
 `show5levels'     Headline levels 1-5.       
 `showall'         No folding on any entry.   
 `showeverything'  Show even drawer contents. 

Alt 1:
 `overview'        Top-level headlines only.  
 `content'         All headlines.             
 `show:2'          Headline levels 1-2.       
 `show:3'          Headline levels 1-3.       
 `show:4'          Headline levels 1-4.       
 `show:5'          Headline levels 1-5.       
 `showall'         No folding on any entry.   
 `showeverything'  Show even drawer contents. 

Alt 2:
 `overview'        Top-level headlines only.  
 `content'         All headlines.             
 `levels:2'        Headline levels 1-2.       
 `levels:3'        Headline levels 1-3.       
 `levels:4'        Headline levels 1-4.       
 `levels:5'        Headline levels 1-5.       
 `showall'         No folding on any entry.   
 `showeverything'  Show even drawer contents. 

Alt 3:
 `overview'        Top-level headlines only.  
 `content'         All headlines.             
 `content:2'       Headline levels 1-2.       
 `content:3'       Headline levels 1-3.       
 `content:4'       Headline levels 1-4.       
 `content:5'       Headline levels 1-5.       
 `showall'         No folding on any entry.   
 `showeverything'  Show even drawer contents.

To me no option is perfect. There are incongruencies for all. Maybe a fourth option?

Alt 4:
`overview'        Top-level headlines only.  
 `content'         All headlines.             
 `2levels'         Headline levels 1-2.       
 `3levels'         Headline levels 1-3.       
 `4levels'         Headline levels 1-4.       
 `5levels'         Headline levels 1-5.       
 `showall'         No folding on any entry.   
 `showeverything'  Show even drawer contents.

Since show in showall and showeverything seems to symbolize the unfolding of things.

That would be an improvement based on all three principles above, in that it removes the ambiguity of "show" (and how it relates to unfolding), makes the names shorter, and stays in line with the naming convention (i.e. no ':'). Not sure what the syntax says about names starting with numerals though.

Your call. Personally I'd prefer Alt 4 or the existing one.

/Gustav

> -----Ursprungligt meddelande-----
> Från: Eric S Fraga <e.fraga@ucl.ac.uk>
> Skickat: den 13 december 2020 10:49
> Till: Bastien <bzg@gnu.org>
> Kopia: Gustav Wikström <gustav@whil.se>; emacs-orgmode@gnu.org
> Ämne: Re: New startup options, show<n>levels
> 
> On Saturday, 12 Dec 2020 at 18:54, Bastien wrote:
> > In this case, I think we could come up with better option names than
> > "show2levels", even if I don't have a better suggestion right now.
> 
> I agree.  I had started responding to Gustav when the original post
> appeared but then aborted my response.  I wonder whether something like
> levels:N or show:N or content:N is possible in a startup setting, akin
> to H:N in options?
> 
> I do have (org-content N) often in my file local variables in any case.
> --
> : Eric S Fraga via Emacs 28.0.50, Org release_9.4-160-g7c8dce

Re: Sv: New startup options, show<n>levels

[TEC]

Just a quick note on the values proposed.

All of the Alt Ns have overview + N-in-the-name options for N >= 2.
e.g. show2levels, show3levels...

For the sake of completeness/consistency I would suggest having a N=1
variant with that format too. This would duplicate the behaviour of
"overview", but if say I currently have "levels:2" and I want to bump it
down to 1, then I'd naturally go to "levels:1" and expect it to work.

--
Timothy.

Gustav Wikström <gustav@whil.se> writes:

> Already in master (Alt 0): 
>  `overview'        Top-level headlines only.  
>  `content'         All headlines.             
>  `show2levels'     Headline levels 1-2.       
>  `show3levels'     Headline levels 1-3.       
>  `show4levels'     Headline levels 1-4.       
>  `show5levels'     Headline levels 1-5.       
>  `showall'         No folding on any entry.   
>  `showeverything'  Show even drawer contents. 
>
> Alt 1:
>  `overview'        Top-level headlines only.  
>  `content'         All headlines.             
>  `show:2'          Headline levels 1-2.       
>  `show:3'          Headline levels 1-3.       
>  `show:4'          Headline levels 1-4.       
>  `show:5'          Headline levels 1-5.       
>  `showall'         No folding on any entry.   
>  `showeverything'  Show even drawer contents. 
>
> Alt 2:
>  `overview'        Top-level headlines only.  
>  `content'         All headlines.             
>  `levels:2'        Headline levels 1-2.       
>  `levels:3'        Headline levels 1-3.       
>  `levels:4'        Headline levels 1-4.       
>  `levels:5'        Headline levels 1-5.       
>  `showall'         No folding on any entry.   
>  `showeverything'  Show even drawer contents. 
>
> Alt 3:
>  `overview'        Top-level headlines only.  
>  `content'         All headlines.             
>  `content:2'       Headline levels 1-2.       
>  `content:3'       Headline levels 1-3.       
>  `content:4'       Headline levels 1-4.       
>  `content:5'       Headline levels 1-5.       
>  `showall'         No folding on any entry.   
>  `showeverything'  Show even drawer contents.
>
> To me no option is perfect. There are incongruencies for all. Maybe a fourth option?
>
> Alt 4:
> `overview'        Top-level headlines only.  
>  `content'         All headlines.             
>  `2levels'         Headline levels 1-2.       
>  `3levels'         Headline levels 1-3.       
>  `4levels'         Headline levels 1-4.       
>  `5levels'         Headline levels 1-5.       
>  `showall'         No folding on any entry.   
>  `showeverything'  Show even drawer contents.
>
> Since show in showall and showeverything seems to symbolize the unfolding of things.
>
> That would be an improvement based on all three principles above, in that it removes the ambiguity of "show" (and how it relates to unfolding), makes the names shorter, and stays in line with the naming convention (i.e. no ':'). Not sure what the syntax says about names starting with numerals though.
>
> Your call. Personally I'd prefer Alt 4 or the existing one.
>
> /Gustav
>
>> -----Ursprungligt meddelande-----
>> Från: Eric S Fraga <e.fraga@ucl.ac.uk>
>> Skickat: den 13 december 2020 10:49
>> Till: Bastien <bzg@gnu.org>
>> Kopia: Gustav Wikström <gustav@whil.se>; emacs-orgmode@gnu.org
>> Ämne: Re: New startup options, show<n>levels
>> 
>> On Saturday, 12 Dec 2020 at 18:54, Bastien wrote:
>> > In this case, I think we could come up with better option names than
>> > "show2levels", even if I don't have a better suggestion right now.
>> 
>> I agree.  I had started responding to Gustav when the original post
>> appeared but then aborted my response.  I wonder whether something like
>> levels:N or show:N or content:N is possible in a startup setting, akin
>> to H:N in options?
>> 
>> I do have (org-content N) often in my file local variables in any case.
>> --
>> : Eric S Fraga via Emacs 28.0.50, Org release_9.4-160-g7c8dce