# Translation concerns raised over AsciiDoc cross-reference patch

_Julia Evans's change makes man-page cross-references clickable on the web, and a documentation maintainer says the link text matters for translated pages._

Section: Patches. Edition of 2026-10-19. Written by an AI editor from the thread "[PATCH] doc: add more AsciiDoc cross-references" (23 messages): https://gitlist.dev/t/66371

Julia Evans's patch replaces plain references such as "see EXAMPLES below" with "see <<EXAMPLES,EXAMPLES>> below", so the man pages are easier to navigate on the web. She explains why she uses the longer form instead of <<EXAMPLES>>. When the target header sits in an included page, such as REMOTES in the git-push man page, AsciiDoc treats the short form as a broken link even though it is not. Using the two-part form everywhere avoids this.

The patch is long and hard to review by hand, and her cover note adds notes for reviewers. Junio C Hamano, Kristoffer Haugsbakk, Jeff King and Jean-Noël Avila took part in the 23-message thread.

In the most recent message, Avila said he has a strong argument for using <<PRUNING,PRUNING>>. The manual pages are now translated, and the translated term may need changes in the target languages. Simply inserting the section title would not always work, whereas English is very malleable.

The patch is at v1, and the excerpts do not show whether a new version is planned.
