New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add support for a custom formatting string in the xrefstyle attribute #2212

mojavelinux opened this Issue May 24, 2017 · 5 comments


None yet
3 participants

mojavelinux commented May 24, 2017

Issues #858 and #1132 introduce the xrefstyle attribute to control how automatic reference text is formatted (i.e., the text displayed at the location of a cross reference). To start, that attribute will support two built-in values (full and short). If the value of the xrefstyle is not one of these built-in keys, the value should be assumed to be a formatting string. This allows authors to customize the content and style of the automatic reference text.

@mojavelinux mojavelinux added this to the v1.5.7 milestone May 24, 2017

@mojavelinux mojavelinux self-assigned this May 24, 2017


This comment has been minimized.


mojavelinux commented May 24, 2017


This comment has been minimized.


mojavelinux commented May 24, 2017

The automatic cross reference text consists of at least four parts:

  • label_name - the name part of the label (e.g., Figure)
  • number - the number of the reference (e.g., 1)
  • label - the combined label (e.g., Figure 1)
  • title - the title of the reference (e.g., System Overview)
  • fancy_title - the title decorated according to the type of reference (e.g., “System Overview” or Chapter Title)

There are a few ways we can go with this. One idea is to build on the AsciiDoc attribute reference syntax, using reserved names to refer to the different elements:

:xrefstyle: \{label}, \{fancy_title}

The attribute references have to be escaped so that interpolation is deferred. The pass macro could be used to make this look nicer:

:xrefstyle: pass:[{label}, {fancy_title}]

// or

:xrefstyle: pass:[{label_name} {number}, “{title}”]

Instead of using the AsciiDoc attribute reference syntax, we could use something more like what's in DocBook:

:xrefstyle: %L, %T

// or

:xrefstyle: pass:[%l %n, “%t”]

The placeholders are as follows:

  • %L - label
  • %l - label name
  • %n - number
  • %t - title
  • %T - fancy title

If the single letters are too cryptic, we could opt for full words:

:xrefstyle: %label, %fancy_title

// or

:xrefstyle: pass:[%label_name %number, “%title”]

If you wanted to decorate the title differently for different types of references, we'd need to introduce some sort of qualifier on the xrefstyle attribute. For example:

:chapter-xrefstyle: %label, _%title_

There's some overhead in doing that, but that seems to be the only way short of introducing some sort of logic into the formatted string itself (which I'd like to avoid, if possible).

Keep in mind that the custom xrefstyle is only used when all the parts can be satisfied. In other words, it's only used when the target is a formal element (has label, number, and title)


This comment has been minimized.


mojavelinux commented Jul 10, 2017


This comment has been minimized.

rockyallen commented Apr 14, 2018

I like the DocBook template style.
But we should consider whether the syntax can be extended in the future (in a regular way).
For example:

  1. Override for a single xref.
    YES "See <<fig_1, Picture %n>>"

  2. Optional parts, ie "See Section 3.1" if the link is to the same chapter, or "See Section 3.1 in Chapter 2" if the link is to another chapter.
    NO but could be "See <<fig_1, Picture %L[ in %c %C]>>"

  3. Merged references ie "See <<table_1>><<table_2>>" becomes "See Tables 1 and 2".
    YES (but could be automated) "See Tables <<table_1,%n>> and <<table_2,%n>>". How do you internationalize plurals?

  4. Prefix numbers with chapter, ie "See <<figure_x>>" becomes "See Figure B-4-3" where figure_x is the third figure in section 4 of Appendix B.
    NO but could be "See <<fig_1, %C-%n>>"

  5. Page number references ie "See Table 3-2 on page 59".
    NO (because page numbers are not currently supported) but in the future could be "See <<table_x[ on %p %P]>>".

  6. Variations in backends (HTML vs PDF).
    YES? - surround attributes in #ifdef backend?


This comment has been minimized.

elextr commented Apr 14, 2018

@mojavelinux Having different attributes hold the format for different types of numbered object types seems like a good way (eg chapter-xrefstyle), but it would need to be the docbook formats or they would have to be translated into the docbook ones by the docbook backend.

Having to put formatting in each individual reference is the wrong thing to do, it should be set once for the contents. With an attribute it can be a block of contents until the attribute is changed.

Personally I prefer the %something approach for the template since it lets you embed it in text, just don't use text that has pluralisation since thats not so simple.

Since its only something that would be changed occasionally, having to refer to the table in the docs for the cryptic single letter to use seems ok to me.

@rockyallen another problem with "See Tables 1 and 2" is how does it now become two links, one to each table?

@mojavelinux mojavelinux modified the milestones: v1.5.8, v2.0.0 Oct 27, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment