Inconsistent usage of "overview"

Inconsistent usage of "overview"

[Carlos Pita]

Hi all,

Here is something I find very confusing. In [1]:

    #+STARTUP: overview
    #+STARTUP: content
    #+STARTUP: showall
    #+STARTUP: show<n>levels
    #+STARTUP: showeverything

In org-startup-folded docstring it is said that it takes values equivalent to:

   #+STARTUP: fold              (or ‘overview’, this is equivalent)
   #+STARTUP: nofold            (or ‘showall’, this is equivalent)
   #+STARTUP: content
   #+STARTUP: show<n>levels (<n> = 2..5)
   #+STARTUP: showeverything

The fact that "overview" is also called "fold" doesn't make what
follows simpler, but so far so good.

Then there is the function org-overview, which:

    Switch to overview mode, showing only top-level headlines.

But org-overview shows drawers unfolded while "overview" mode folds
drawers at startup. That is, if you start in "fold" or "overview" mode
(as in #+STARTUP or org-startup-folder) and then cycle visibility all
the way back to "overview" (now as in org-overview) you're not at the
beginning again.

I would say that this is not intentional but an inconsistency in what
"overview" means that should be resolved some way or another. For me
it makes sense that drawers begin folded in an overview and the
docstring of org-overview seems to suggest that. Moreover, while
cycling the rest of the "more expanded" visibility states fold
drawers.

And sometimes properties represent a disproportionate part of the
document when compared to folded top-level headlines. For example, I'm
thinking of brief org-roam notes showing an awful UUID at the top
which is IMO not relevant to an overview.

Best regards,
Carlos

---

[1] https://orgmode.org/manual/Initial-visibility.html

Re: Inconsistent usage of "overview"

[Carlos Pita]

I believe my confusion was due to the fact that the docstring of
org-startup-folded is not particularly precise regarding to its
possible values. On the one hand it seems to be a toggle, but its
initial value is nevertheless showeverything and not t. On the other
hand it states that "This can also be configured on a per-file basis
by adding one of the following lines anywhere in your buffer..." but
it's not clear whether these values may also be assigned directly to
the variable. If you do that, then inconsistencies appear: when they
are options in a buffer, showall and nofold are both mapped to nil,
fold and overview are both mapped to t; but when they are directly set
this mapping obviously doesn't take place. Following a suggestion I'd
read elsewhere, I set org-startup-folded to fold (and, later, to
overview), and this is not really calling org-overview but instead
ends up in a catch-all clause that hides drawers. By the same token I
could have set org-startup-folded to foobar.

The point still stands that showall and contents fold drawers but
overview (aka fold) doesn't fold drawers, which seems extremely odd to
me.

Best regards,
Carlos

Re: Inconsistent usage of "overview"

[Ihor Radchenko]

Carlos Pita <carlosjosepita2@gmail.com> writes:

> I believe my confusion was due to the fact that the docstring of
> org-startup-folded is not particularly precise regarding to its
> possible values.

I improved the docstring on main. Hopefully, it can reduce the
confusion.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=c2a58bbd5

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