Interactive functions do not have double-dashes in their names. However,
I have concerns about this interactive status. Given than the function
is not properly documented in the manual, there is little chance it will
be actually used. And if it isn't, it could return surprising results.
Another idea would be to replace NOCACHE with CLEAR-CACHE. When this is
non-nil, the cache is reset at the beginning of the function. The point
is to reset the cache the first time the function is called, but not on
recursive calls, which ensures any file is retrieved only once.
Here is my use case for org-file-clear-cache:
Let's say I have a file where I have a SETUPFILE retrieved from a URL. Now the upstream version changes but my cache is still on the older version. So I need to clear the hash. The org-file-clear-cache simply does that.
With the function being interactive, I just do
- M-x org-file-clear-cache
- C-c C-e h h (or whatever I am exporting to)
If you suggest a node where I should put that in the manual, I can add that to my updated patch. I'll all add more explanation to the doc-string of that function.
Now, if the CLEAR-CACHE argument is added to org-file-clear-cache, how do we control the cache clearing interactively from outside?
Also, how do we implement the resetting of the cache only the first time the function is called? Wouldn't that need an extra alist defvar to record the state of whether the function is already called specifically for that file? I think that would unnecessary complicate the logic.
Another idea is that we have a defcustom like org-file-never-cache. When non-nil, that will always do a fresh URL download. This will be or'ed with the NOCACHE inside org-file-contents. This, though, makes it a bit inconvenient for the user to use the latest upstream version when they need... They might need to set org-file-never-cache to t momentarily, probably via Local Variables, before an export.
course the cache doesn't survive to multiple exports, but at least it is
transparent to the user.
Sorry, I didn't follow that. Did you mean that the cache doesn't survive between emacs sessions? Because the cache will actually survive between multiple exports.
This issue is still open. I have just added a bit more info to the docstring of org-file-clear-cache.
I grepped org.texi but found no reference of org-file-contents. So may be we need to add a section for that, and there I can explain org-file-clear-cache in more detail. What would be a good node for that?
I have integrated most of your refactored version except for this portion. Above will do a false match if that "HTTP.." string is present in the FILE body too! I have retained my version of only that part where the search happens only inside the url-retrieve header. The search is also faster in the case of failure as it does not have to search through the whole file before declaring a fail.. as only the header is searched.
0001-Allow-org-file-contents-to-fetch-file-contents-from-.patch