Re: using olinks everywhere?

Thanks very much for the detailed answers from many people! Exactly the 
kind of info I need. I even got a bonus with the inter-PDF linking 
information, which will come in handy if I ever decide to try that again.

Barton, I am not running 4.3 and 5.1 docbook in the same build. They are 
run separately so there's a minimum of problems. I'm also converting 
everything to 5.1 soon, so that will help.

Mark

On 7/10/2020 6:17 AM, Barton Wright wrote:
> The 5000-page doc set I support 
> <https://docs.tibco.com/pub/str/10.6.0/doc/html/index.html> is heavily 
> olinked between books. It’s a glorious thing for end-users, because we 
> never have to repeat basic information in one book, we just 
> cross-reference to it with an olink to a location in another book.
>
> Our DockBook XML files are one file per article or part, and we 
> Xinclude each book’s files into the index.xml <book> file for the book.
>
> We still use link and xref for same-page (same file) cross-refs, but 
> all other cross-refs are olinks. Olinks are a PITA to work with, 
> require strict discipline, and they double your doc set build times 
> because you have to run two XSL passes over the entire doc set: one to 
> build the olink database, the other to build the HTML for each book. 
> However, the value for end-users and the avoidance of repeated text 
> for you are worth it.
>
> The trick to making an olink system work is setting up your 
> <targetset> XML file (that uses Norm Walsh’s targetetdatabase.dtd). 
> This file is a description of the ultimately /installed and 
> deployed/ folder structure of your doc set. Then, as an authoring 
> convenience, keep your /development/ folder structure identical to the 
> eventual /deployed/ folder structure, with one book’s files in each 
> parallel folder.
>
> The strict discipline required is that each combination of 
> /targetdoc/ plus /targetptr/ attributes in your entire olink database 
> must be globally unique. If you have duplicate attribute combos in 
> different places, say, books A and B, pages AA and BB, then a 
> cross-ref to B+BB ends up pointing to the first instance encountered 
> during the doc build, A+AA, which is almost certainly not what you want.
>
> We set up a policy of naming our DocBook files and their containing 
> folders so that cross-referencing to them is as easy as possible, and 
> so that ID combos are always unique. The <targetset> file will name 
> /folders/ as locations. We then have a strict policy that the ID for 
> each <article> or <part> file is the exact same as the file’s 
> basename. That way, you don’t have to stop to look inside a file to 
> obtain the /targetptr/ attribute to point to in your olink, you just 
> look at a folder listing in your OS. The /targetptr/ attribute of an 
> olink to the top of each article file is always the basename of the file.
>
> Further, our policy is that <section> IDs always begin with the 
> article ID. So file *expr-eval.xml* has an <article> ID of 
> *expr-eval*, and section IDs take the form *expr-eval_/sectionname/*. 
> This, again, is to make all section IDs globally unique and to cut 
> down on having to look much inside target files to find the cross-ref 
> /targetptr/ attribute. Yes, this means that you can cross-ref down to 
> the section or subsection level in a page. Or to a table, figure, 
> paragraph or even to a single listitem in a list, as long as it has an ID.
>
> We use XXE as our DocBook editor and love it to pieces. However, we do 
> not use XXE’s built-in support for olinks for various historical 
> reasons. In editing, we construct the olink by specifying the 
> /targetdoc/ and /targetptr/ attributes for each one. Your mileage will 
> vary, depending on your editor and build system.
>
> I would love to claim credit for setting up the system described 
> above, but all praise goes to one Denis Bradford, a former tech writer 
> at our company from a decade ago.
>
> Further notes:
>
>   * PDFs. Yeah, you can’t cross-ref from one PDF into a page or
>     section inside another PDF — or not without profound PDF-fu above
>     my level. Make sure your doc build system for PDFs substitutes
>     reasonable text in place of each olinked cross-ref, or the mastery
>     of your prose will end up garbled in your PDFs.
>   * An olink system can be limiting. For example, we would love to
>     switch to a modern-looking, three-panel webhelp HTML system with
>     each book in the TOC panel and all cross-refs working as expected.
>     (This is what happens in the Eclipse Help version
>     <https://docs.streambase.com/sb16/index.jsp> of our doc set.)
>     However, there is never time to experiment with drastic changes to
>     the doc build system and preserve olink effectiveness at the same
>     time.
>   * You can build one olinked book individually, but its cross-refs to
>     other books might become stale without rebuilding the olink
>     database for entire doc set at the same time. You end up building
>     the entire doc set more often than not.
>   * I have no experience with mixing DocBook 4 and 5 olinks in the
>     same olink database. It should work fine, but you’re on your own
>     there.
>   * I’m amazed that you /can/ mix namespaced and non-namespaced XSL in
>     the same doc build system. You’re a wizard.
>   * You can upgrade your DocBook 4.3 files to 4.5, the last supported
>     version of DocBook 4, by just editing the number in the DOCTYPE
>     line of each file, and adjusting the version of XSL you’re using
>     to match. It was painless for us to do that.
>
>
>
>> On Jul 10, 2020, at 2:12 AM, Mark Giffin <[email protected] 
>> <mailto:[email protected]>> wrote:
>>
>> I have a large collection of user guides in Docbook 4.3 and 5.1, and 
>> they have a top-level Docbook files with a <book> element, and 
>> sub-chapters are pulled in using xincludes like this:
>>
>> <book id="book_1" lang="en" xmlns:xi="http://www.w3.org/2001/XInclude">
>>     <bookinfo>
>>         <title>my title</title>
>>     </bookinfo>
>>
>>     <xi:include href="overview.xml"/>
>>     <xi:include href="platform.xml"/>
>>     <xi:include href="components.xml"/>
>>     <xi:include href="install.xml"/>
>> etc.
>>
>> In the interests of simplicity for authors, we have the idea of using 
>> only <olink>s for linking across these books. Does anyone know of any 
>> problems with using only olinks?
>>
>> Thanks,
>> Mark
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: [email protected] 
>> <mailto:[email protected]>
>> For additional commands, e-mail: 
>> [email protected] 
>> <mailto:[email protected]>
>>
>