Re: Please document the caching and its user options

[Daniel Clemente <n142857@gmail.com>]

> > A user has somefile.org which contains some headers marked with the
> > "crypt" tag. Only those headers are encrypted. The org-element cache
> > may now cache the whole file, including the encrypted headers (this is
> > ok). Now the user temporarily decrypts the encrypted header, works on
> > it some time (including closing the file and opening it again) then
> > encrypts the section again. During the time that the header was
> > unencrypted, the org-element cache was storing information about
> > unencrypted data in ~/.cache/org-persist, which could even be a remote
> > server (NFS, SMB etc), not as private as the org file itself.
> Nope. Storing to disk only happens when you kill the buffer and before
> exiting Emacs. At that point, org-crypt must take care about
> re-encrypting everything.

Sometimes org-crypt fails to reencrypt the data. E.g. if Emacs
crashes, or if you fail to type the same password twice, or of course
if you don't use (org-crypt-use-before-save-magic), etc.
At the end of the day when I do "git diff" + "git commit" sometimes I
realize there's unencrypted data and then I have to reencrypt it. In
the meantime I might have killed and reopened the buffer, thus
updating the file cache.
That may be a problem by org-encrypt and something to document in
org-crypt itself. The point is that users of org-encrypt should take
extra precautions when enabling org-element-cache-persistent. Like:
not closing buffers while the sections are unencrypted.

> Multiple Emacs instances are handled correctly. I do not see much
> point documenting that things are working as expected.

Ok, thanks, it's good to read this guarantee here. I'm used to
org-element cache inconsistency errors, so I didn't know the state of
things.
I agree it doesn't need to be in the docstring.
If there's some chapter about caches in the manual (which is one of
the topics in the original post of this thread) it can describe these
minor things. But the major ones like what does it do and to turn it
on/off are more interesting.