Record the origin on the xref stack when following a reference so that `xref-go-back`/`M-,` work properly by psaris · Pull Request #88 · bbatsov/adoc-mode

psaris · 2026-10-05T08:11:48Z

Push the origin onto the xref marker stack in adoc-goto-ref-label and in the include:: and link: file branches of adoc-follow-thing-at-point. The Antora branch already did so.

Before submitting a PR make sure the following things have been done (and denote this
by checking the relevant checkboxes):

The commits are consistent with our contribution guidelines
You've added tests (if possible) to cover your change(s)
All tests are passing (eldev test)
The new code is not generating bytecode or M-x checkdoc warnings
You've updated the changelog (if adding/changing user-visible functionality)
You've updated the readme (if adding/changing user-visible functionality)

Thanks!

bbatsov · 2026-10-05T09:27:44Z

Can you clarify the problem your trying to solve? After all any link resolution is kind of tied to the underlying AsciiDoc "framework" as they tend to organize files differently. (as illustrated by handling of Antora files)

psaris · 2026-10-05T09:45:59Z

@bbatsov, first let me thank you for taking over this project. i, too, love the functionality that emacs and asciidoc bring. the progress you've made is amazing, and the test harness is so important.

in other modes, M-, (xref-go-back) brings you back to where you typed M-. (xref-find-definitions). but when i do this in adoc-mode, i get this error

xref-go-back: The marked buffer has been deleted

this is because adoc-mode rebinds M-. to adoc-follow-thing-at-point.

based on the adoc-mode documenetation, this is supposed to work

adoc-mode also registers an xref backend, so the standard cross-reference keys work for AsciiDoc ids: M-? (xref-find-references) lists every [id] / [id] that points at the id under point, and M-, (xref-go-back) returns after a jump. In an Antora component M-? searches the whole component, so cross-page references (this/page.adoc from other pages) are included.

to fix this, we need to add a call to xref-push-marker-stack so xref-go-back knows where to return to.

this pull request tries to minimize the diff and leaves the existing code alone by adding calls to xref-push-marker-stack.

psaris · 2026-10-05T22:09:31Z

@bbatsov the M-. redefinition was introduced in the fix for #29. the request was for markdown-mode-like functionality. critically, however, markdown-mode does not rebind M-.. it only binds C-c C-o.

an alternative is to remove this binding and fix xref-backend-identifier-at-point and xref-backend-definitions to return the proper file locations and allow xref to manage the stack. happy to raise this PR.

one downside is that the code won't be able to open a browser for urls, since emacs is handling the navigation.

bbatsov · 2026-10-05T22:12:48Z

Thanks for the extra details! I'll take a closer look at the proposed fix tomorrow.

Push the origin onto the xref marker stack in `adoc-goto-ref-label' and in the `include::' and `link:' file branches of `adoc-follow-thing-at-point'. The Antora branch already did so.

psaris · 2026-10-05T22:50:03Z

@bbatsov simplified PR. should pass tests now.

bbatsov

The fix looks right to me - M-, now comes back from xrefs, include:: and link: files. Mostly small test things inline, but the Emacs 28 one will break CI.

bbatsov · 2026-10-07T08:45:50Z

+      (beginning-of-buffer)
      (adoc-goto-ref-label "cool")
      (expect (line-number-at-pos) :to-equal 5)
+      (xref-go-back)


xref-go-back only appeared in Emacs 29.1, and we still support 28.1 (it's in the CI matrix), so this fails there with void-function. On 28 the command is xref-pop-marker-stack. A tiny helper covers both:

(defun adoc-test--go-back () (funcall (if (fboundp 'xref-go-back) 'xref-go-back 'xref-pop-marker-stack)))

Quoting the symbols instead of using #' keeps 29+ from warning about the obsolete alias.

bbatsov · 2026-10-07T08:45:50Z

              "[[bar]]\n"
              "dolor [[geil]]sit amen\n"
              "anchor:cool[]\n")
+      (beginning-of-buffer)


The byte-compiler warns that beginning-of-buffer is for interactive use only. (goto-char (point-min)) does the same here.

bbatsov · 2026-10-07T08:45:50Z

    (let ((file (match-string-no-properties 1)))
      (if (file-exists-p file)
-          (find-file file)
+          (progn (xref-push-marker-stack) (find-file file))


Only the adoc-goto-ref-label path has a test. A spec that follows an include:: (and a link:) to a real file and then goes back would cover this branch and the link: one below.

bbatsov · 2026-10-07T08:45:50Z

 - Following a cross-reference at point (`C-c C-o` / `M-.`, and the new `xref` commands) now works for a plain `<<id>>` even when a captioned `<<id,caption>>` appears later on the same or an adjacent line, and ignores the whitespace in forms like `<<id >>`. Previously `adoc-xref-id-at-point` could return nil or an id with a trailing space in those cases.
 - Heading navigation (`C-c C-n` and friends) and the imenu index no longer get confused by code and other delimited blocks. A `==`-style line inside a listing, source, literal, example, sidebar, quote, or open block, or a code line followed by `----` (which looks just like a two-line title underline), is no longer mistaken for a section title. Navigation and imenu now stay in step with what is actually highlighted as a title.
 - Heading navigation and imenu now honour `adoc-enable-two-line-title`. It is nil by default, so two-line (setext) titles are no longer picked up unless you opt in, matching their fontification. Previously they were always recognised, which was the main source of the code-block confusion above.
+- Fix `M-,` (`xref-go-back`) after following an xref, `include::` or `link:` file with `M-.` / `C-c C-o`. The origin is now recorded on the xref marker stack.


Please start the entry with a link to the PR: - [#88](https://github.com/bbatsov/adoc-mode/pull/88): Fix ...

psaris force-pushed the xref-go-back branch from b8d204a to 76b0810 Compare October 5, 2026 11:38

Fix xref-go-back after following an xref

18031f6

Push the origin onto the xref marker stack in `adoc-goto-ref-label' and in the `include::' and `link:' file branches of `adoc-follow-thing-at-point'. The Antora branch already did so.

psaris force-pushed the xref-go-back branch from 76b0810 to 18031f6 Compare October 5, 2026 22:44

bbatsov reviewed Oct 7, 2026

View reviewed changes

Navigation Menu

Repository navigation

Record the origin on the xref stack when following a reference so that `xref-go-back`/`M-,` work properly - #88

Record the origin on the xref stack when following a reference so that `xref-go-back`/`M-,` work properly #88
psaris wants to merge 1 commit into
bbatsov:masterfrom
psaris:xref-go-back

psaris commented Oct 5, 2026 •

edited

Loading

Uh oh!

bbatsov commented Oct 5, 2026

Uh oh!

psaris commented Oct 5, 2026 •

edited

Loading

Uh oh!

psaris commented Oct 5, 2026

Uh oh!

bbatsov commented Oct 5, 2026

Uh oh!

psaris commented Oct 5, 2026

Uh oh!

bbatsov left a comment

Uh oh!

bbatsov Oct 7, 2026

Uh oh!

bbatsov Oct 7, 2026

Uh oh!

bbatsov Oct 7, 2026

Uh oh!

bbatsov Oct 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

psaris commented Oct 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bbatsov commented Oct 5, 2026

Uh oh!

psaris commented Oct 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

psaris commented Oct 5, 2026

Uh oh!

bbatsov commented Oct 5, 2026

Uh oh!

psaris commented Oct 5, 2026

Uh oh!

bbatsov left a comment

Choose a reason for hiding this comment

Uh oh!

bbatsov Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

bbatsov Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

bbatsov Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

bbatsov Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

psaris commented Oct 5, 2026 •

edited

Loading

psaris commented Oct 5, 2026 •

edited

Loading