Hello all,

It’s an occasional project of mine to try to improve and refactor
aspects of org’s code.  I’ve been going through org-id recently.  The
following issues came up that I would appreciate feedback on:

1. org-id is not loaded by default; it is supposed to be selected by the
   user (see footnote 2 of (info "(org) Handling links")).  Yet, other
   org libraries rely on it, without requiring it (e.g. ox-icalendar).
   Also, at least one library (org-bibtex) reimplements bits of org-id’s
   internals to avoid requiring it explicitly.  Is there a good reason
   not to make org-id a core library, that is to require it
   unconditionally from org.el?

2. I would like to deprecate the org-id-method variable.  This allows
   choosing different methods of generating random IDs.  But one method
   is as good as another (they are random*...), so we can just always use
   a single method (powered by the elisp ‘random’ function).  Choosing
   this allows deprecating several other variables and functions, along
   with a soft dependency on the external uuidgen binary.  Any
   objections to this course of action?

(* Not all the values of org-id-method lead to IDs that are random in
the statistical sense.  But they are not meaningful from the user’s
point of view in any case.)

3. I would like to change the API of the org-id-get function.  The
   current signature is (&optional pom create prefix).  POM
   (i.e. position or marker) is a useless argument, because in the
   (relatively uncommon) case that callers are interested in a location
   other than (point) they can wrap the call in (org-with-point-at ...).
   PREFIX is similarly useless (and in fact unused in org’s code base)
   because a caller could let-bind org-id-prefix around the call.  The
   new signature would be (&optional create reset), which are both
   boolean arguments.  The question arises of how to make this change.
   Options I see:
   a. Hard breakage; code using the old calling convention will break.
   b. Introduce a new function under a new name, deprecate the old name
   c. Try to detect which calling convention is in use.
   Options (a) and (b) have drawbacks.  I would like to implement
   (c) by requiring the create and reset arguments, if given, to have
   values 'create and 'reset respectively.  The old and new calling
   conventions have identical semantics when both arguments are nil, so
   that case is not a problem.  With the new code, any other value for
   these arguments (besides nil and a same-named symbol) would indicate
   use of the old convention, and signal an error.  Comments?

4. A similar issue arises for org-id-find.  I would like it to always
   return a marker, rather than having an argument switch between a
   marker and a cons of filename and position.  (There are functions
   which return the filename or position individually, so returning both
   as a cons is useless from an API point of view).  There’s no good way
   to detect the old calling convention, however, so I think I have to
   introduce a new name.  (My draft patch is written instead with hard
   breakage, but stability of API is important so I will change that...)

There are other deprecations and renamings as well, but none of them
should break third-party code.  The resultant patch shrinks the codebase
by 60-ish lines and eliminates 3 defcustoms...baby steps.  A draft patch
is attached to this message; I expect to make further changes based on
feedback I receive, so detailed code review (while certainly always
appreciated!) can be postponed until the conceptual issues are
resolved.

Thanks,

-- 
Aaron Ecay