Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Add support for a custom formatting string in the xrefstyle attribute #2212
Issues #858 and #1132 introduce the
For ideas, see http://www.sagehill.net/docbookxsl/CustomXrefs.html
The automatic cross reference text consists of at least four parts:
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:
The attribute references have to be escaped so that interpolation is deferred. The pass macro could be used to make this look nicer:
Instead of using the AsciiDoc attribute reference syntax, we could use something more like what's in DocBook:
The placeholders are as follows:
If the single letters are too cryptic, we could opt for full words:
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:
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)
referenced this issue
May 24, 2017
For reference: http://www.sagehill.net/docbookxsl/CustomXrefs.html
I like the DocBook template style.
@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?