By chance I had a conversation yesterday in person with several Red Hat technical writers. We wound up discussing xrefs (because we are that kind of cool!).
As you may know, xrefs allow you to link to a piece of content without having to know where it actually lives. In DocBook you link to the id of the section/etc.
AsciiBinder does not support xrefs today. AsciiDoc has syntax for them, but the processing that AsciiBinder does to build the site precludes us from using it.[1]
I believe I can get us something like this working though. Is there an interest?
= Xrefs in AsciiBinder
A plugin will be written (I have a rough Proof Of Concept done) that overloads the AsciiDoc xref syntax. We would now be able to do the following:
xref:title_with_underscores_case_insensitive[optional text to use for the link text - otherwise the title is used]
This would link to the page that has that title.
But what about collisions? If two pages have the same title, you will need to be more specific. Using the Dir entries from the _topic_map.yml you would specify:
xref:dir/title_with_underscores_case_insensitive[optional text to use for the link text - otherwise the title is used]
This may or may not work fully if you have a / (slash) in your title. If we want xrefs back, I am willing to sacrifice this :) are you?
What do you think?
1: To get proper id parsing we would need to do an id fetching parse on every document and then run our standard parse. While this isn't necessarily computationally expensive, I am not sure it is worth doing unless we can somehow get the information from Asciidoctor. I don't really want to implement an AsciiDoc parser ...
PS: If we implement this, I'd like to either figure out how to do it as a plugin that is optionally includeable (and therefore easy for me to fork) or I'll need to add a bit of extra functionality for my use case. Specifically, I combine multiple source file repos together, so I'll need something like
xref:content-set@dir/title_with_underscores[] to work. I believe I can do this in a way that potentially provides use to others by allowing content-set to be interpreted as a top-level directory to restrict searches too.
By chance I had a conversation yesterday in person with several Red Hat technical writers. We wound up discussing xrefs (because we are that kind of cool!).
As you may know, xrefs allow you to link to a piece of content without having to know where it actually lives. In DocBook you link to the id of the section/etc.
AsciiBinder does not support xrefs today. AsciiDoc has syntax for them, but the processing that AsciiBinder does to build the site precludes us from using it.[1]
I believe I can get us something like this working though. Is there an interest?
= Xrefs in AsciiBinder
A plugin will be written (I have a rough Proof Of Concept done) that overloads the AsciiDoc xref syntax. We would now be able to do the following:
xref:title_with_underscores_case_insensitive[optional text to use for the link text - otherwise the title is used]
This would link to the page that has that title.
But what about collisions? If two pages have the same title, you will need to be more specific. Using the Dir entries from the _topic_map.yml you would specify:
xref:dir/title_with_underscores_case_insensitive[optional text to use for the link text - otherwise the title is used]
This may or may not work fully if you have a / (slash) in your title. If we want xrefs back, I am willing to sacrifice this :) are you?
What do you think?
1: To get proper id parsing we would need to do an id fetching parse on every document and then run our standard parse. While this isn't necessarily computationally expensive, I am not sure it is worth doing unless we can somehow get the information from Asciidoctor. I don't really want to implement an AsciiDoc parser ...
PS: If we implement this, I'd like to either figure out how to do it as a plugin that is optionally includeable (and therefore easy for me to fork) or I'll need to add a bit of extra functionality for my use case. Specifically, I combine multiple source file repos together, so I'll need something like
xref:content-set@dir/title_with_underscores[] to work. I believe I can do this in a way that potentially provides use to others by allowing content-set to be interpreted as a top-level directory to restrict searches too.