docscii icon indicating copy to clipboard operation
docscii copied to clipboard

Add support for olink DocBook element

Open fbolton opened this issue 7 years ago • 1 comments

One of the eccentricities of the JBoss Fuse library is that we use olink elements a lot, not only for linking within a book, but also for linking between different books in the same library. Now, these are different cases, so I will go through them separately.

First, using olink to define a link to an element in the same book. Here is an example of this olink syntax:

<olink targetptr="TargetID"/>

Which can easily be rendered in AsciiDoc as:

<<TargetID>>

Second, using olink to define a link to an element in a different book in the same library. Well, we don't really have a proper solution for this case at the moment (thought it will probably be solved soon in the context of Docs 2.0). My strategy to deal with this kind of olink is to preserve the metadata through the conversion to AsciiDoc and then deal with it later. Here is an example of this olinksyntax:

<olink targetdoc="TargetBookID" targetptr="TargetID"/>

I suggest converting it to AsciiDoc as follows:

link:olink:TargetBookID/TargetID[]

This is legal AsciiDoc syntax, but will not be processed, since olink: is an unknown scheme. This would give me a handy placeholder which I can search and replace some time in the future, when we have worked out a more permanent solution.

fbolton avatar Mar 07 '17 09:03 fbolton