Re: Feedback on changes to org-id

[Nicolas Goaziou <mail@nicolasgoaziou.fr>]

Hello,

Aaron Ecay <aaronecay@gmail.com> writes:

> 2016ko irailak 3an, Nicolas Goaziou-ek idatzi zuen:
>
>> Please don't make that change. A marker is pointless if the file is not
>> currently associated to any buffer. In that case (file-name . postition)
>> cons cell is a valuable return value.
>
> The API has the following two functions already:
> - org-id-find-file-for: id -> file-name
> - org-id-find-id-in-file: id file -> position

I don't think these functions belong to the API. The seems more like
internal functions, implemented before the "--" convention.

> Imagine I add to this API org-id-find-marker: id -> marker. Then
> I think we can deprecate (and eventually delete) org-id-find, since
> all its uses can be replaced by some combination of the other
> 3 functions. (We could also keep it as a convenience function wrapping
> the other 3, but it hardly seems worth it: the marker case just adds
> the overhead of another funcall,

This complicates the API for no real benefit. We ought to consider
`org-id-find' as the sole entry point in "org-id.el". The rest is
implementation details.

More on this below.

> whereas a significant proportion of the non-marker calls in the
> codebase actually only care about the file name, so it is a waste of
> effort to calculate the buffer position only to throw it away.)

In the code base, notwithstanding contrib/ and "org-id.el" itself, there
are 4 calls to `org-id-find' without a marker. Half of them make use of
the position (in org-capture and org-colview.el). If we add
`org-id-find-id-in-file', there are two more calls. One of them actually
require the position anyway (in ob-ref). I don't think 3 calls out of
6 is significant.

If speed is an issue, we can add an optional argument to skip position
(and marker) in the return value. E.g.,

  (org-id-find ID &optional OUTPUT)

where OUTPUT is either

- nil : return value is the usual cons cell (file . position)
- file : return value is the file, as a string
- marker : return value is a marker.

Again, I don't think we need 3 functions just for this.

> I think this would imply writing the ID database to ‘org-id-locations-file’
> under certain circumstances without asking/letting the user approve this
> action.  Is that OK?  (I am not bothered by it, FWIW).
>
> If it’s not acceptable, perhaps this variable should be replaced by a
> new defcustom ‘org-id-write-database’ which would control only the
> writing of the DB to disk (but unlike the existing implementation would
> not turn off the ID tracking code paths within the emacs session).

IMO the former is acceptable. If it happens to disturb some users,
I guess we will fallback to the latter.

Regards,

-- 
Nicolas Goaziou