Re: Please document the caching and its user options

[Eli Zaretskii <eliz@gnu.org>]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: emacs-orgmode@gnu.org
> Date: Fri, 14 Jun 2024 15:31:28 +0000
> 
> 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.

That's too bad.  When a user finds out about this caching, how do you
propose that he/she looks for the information about it?  I wanted to
know what is being cached, why, and in what file/directory.  It took
me quite some time to find the answers, since Org is a very large
package, and there's no org-cache.el file or similar to serve as the
immediate suspect.  Surely, such a basic functionality should be at
least hinted in the documentation, so that users new which options to
look at and where?

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

All of them.

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

I submit that at least the options which control where the cache is
and how to disable it are important enough to be in the manual.  Given
their names, users can use apropos or customize-group to find other
relevant options.

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

multisession is an optional package, it is neither preloaded nor
turned on by default in Emacs.  And even if Emacs makes a mistake of
not documenting anything it is not a valid argument to make the same
mistake elsewhere.

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

The emacs-internal encoding is not binary.  In almost all the cases it
is indistinguishable from utf-8-unix.  It differs where a buffer
includes characters outside of the Unicode codespace.  The usual
practice in Emacs is that files holding internal data use
emacs-internal to make sure all the characters are saved correctly and
can be later restored correctly.