Re: Please document the caching and its user options

[Ihor Radchenko]

Eli Zaretskii <eliz@gnu.org> writes:

>> Hmm. What aspect of caching do you want us to document?
>
> First and foremost, that it exists, and is turned on by default.  The
> manual is currently completely silent about it.
>
> Next, please document the user options that control this caching, and
> especially those options which can be used to turn this caching off or
> direct it to a different place.

I am not convinced that we have to do it.

Firstly, it is not clear if you are asking to document caching parser
state specifically or all kinds of caching Org mode does.

Secondly, I am not sure if we have to document the details of caching at
all in the manual. We do not document all the custom options in the
manual; just the most important/useful.

Emacs user manual does not document `multisession-directory' - something
very close to how we implement Org caches.  So, apparently, customizing
`multisession-directory' and even the very multisession feature
existence is not deemed necessary inside Emacs manual. Why would it be
different for Org mode manual?

> I'm not a heavy user of Org, but I do have several Org files that I
> visit from time to time.  This was the first time I got prompted about
> anything related to this caching.

The prompt you saw is indeed a bug.

> ...  Moreover, I think this was the
> first time the Org file I visited was parsed by Org and the results
> cached: I have a feature on my system that prominently indicates when
> the machine is heavily loaded, and I was surprised to see it in action
> when I visited org.org.  I never had this activated before just by
> visiting an Org file.  I presumed the high load was due to the
> parsing.  So either this is very new, or maybe my Org files are much
> simpler than doc/misc/org.org, and so the parsing I triggered before
> was much less expensive.

Org mode uses parser since long time ago. Previously, the parser was
invoked without any caching, even in-memory. Since Org 9.6, we
implemented in-memory and on-disk caches for the parser. This allowed us
to utilize the parser more frequently, without relying upon
half-accurate regexp matches. Overall, it decreased CPU loads, but there
are different scenarios; sometimes CPU load is larger momentarily.

>> I believe that this particular problem has been solved in
>> https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=c8f88589c
>> It is a part of Org 9.7.
>
> Maybe.  Try visiting org.org on a system whose locale is set to, say,
> Latin-1, and see if you get the warnings about a safe coding-system.
>
> But why do you use utf-8 there and not utf-8-unix?  Come to think
> about it, why not emacs-internal?  Those files are used internally by
> Org, so they should be able to encode any characters supported by
> Emacs, not just those which have UTF-8 encoding.  And using native EOL
> convention is not needed, and will get in the way if the user shares
> these files between systems.

Mostly because we chose whatever looked reasonable. I am not 100% sure
what is the practical difference between `utf-8' and `utf-8-unix' and
why the latter should be considered better.

As for `emacs-internal', we try to make files readable if at all
possible. In particular, index.eld file is even pretty-printed for user
convenience. The idea is to keep things in plain text and not in binary
formats, following the overall spirit how Emacs usually stores data. (I
think you may recall people raising their voice about plain text
vs. binary during the discussion of multisession feature and the use of
sqlite database).

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