POM (point-or-marker) in org-mode

Question

I'm trying to use functions org-entry-properties and org-id-get, both of which use an optional argument pom. For example, org-entry-properties documentation says:

Get all properties of the entry at point-or-marker POM.

Emacs manual almost doesn't mention the word "marker", however there are several functions ending with -marker. Now i have several questions about it.

1. What is that point-or-marker?
2. Is it the same as mark in a mark ring?
3. How do i get a marker in an org-mode buffer?
4. How do i use this marker in the above functions invocation?

Answer 1

An (absolute) position in a buffer is given by a number, which is roughly the number of characters that are before that position. Markers, on the other hand, allow to mark a "relative position" in the buffer : if you add text before it, it moves forward (like it were an invisible, 0-width, character).

At any time, you can convert a marker to an (absolute) position (an integer). That is why many arguments want a POM: they want a position, but accept that it is given as a marker.

The "mark" in emacs, is one specific marker which is easy to access by appropriate key chords (C-SPC sets it, C-x C-x exchanges the mark and the point, etc.). The/a "mark ring" is the history of all previous "mark" markers (either in a given buffer, which is the local mark ring, or globally, for the so called global mark ring).

More info in the elisp manual :

• from within emacs : (info "(elisp) Markers")
• on the web : http://www.gnu.org/software/emacs/manual/html_node/elisp/Markers.html

Answer 2

Instead of the Emacs Manual, take a look at the Emacs Lisp Reference Manual for more information on markers:

A marker is a Lisp object used to specify a position in a buffer relative to the surrounding text. A marker changes its offset from the beginning of the buffer automatically whenever text is inserted or deleted, so that it stays with the two characters on either side of it.

The POM element to the functions you mention can thus either be a marker, i.e., a lisp object that contains both a buffer and a position in that buffer, or simply a position. In the first case, the functions will first switch to the buffer of the marker and move point to the marker's position before executing the rest of the function.

In the second case, it will stay in the current buffer, but move point to the given position before executing the rest of the function.

That is, the function is executed relative to the given buffer/position. At the end of the function's body, the original location of the point is restored.