Enhance the xref macro to permit relative document references
Currently, the xref
macro requires, at a minimum, the path to a document to be specified each time. For example, anywhere for an API reference with function categories and groups, my xref
s look like: xref:api_name/category/group/function.adoc[Function!]
. Very often, the pages for functions need to provide xref
s to comparable/related functions in the same group, and occasionally to functions in the same category. So there are many, verbose xref
definitions.
Additionally, as APIs evolve over time, sometimes a group is promoted to a category (or a new API altogether). The pages within the category/group folders maintain their relative positioning, but the folder structure can move as a unit.
To better support these use cases, I'd like to request an enhancement to the xref
macro where a relative path can be provided. For example: xref:./other_function.adoc[Other Function!]
The xref
macro can compute the context of the relative link from the page containing the xref
.
The benefit is that xref
s between related pages can be less verbose, and structural changes require notably less effort to complete as fewer (sometimes no) xref
s need to be updated.
For my intended use, I would be okay if such relative paths were restricted to the module of the containing page. If I'm moving content between modules or components, that's a larger effort that needs more planning.