Re: [docbook-apps] using olinks everywhere?

[Mark Giffin <m1879@earthlink.net>]

    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Â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Â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 <m1879@earthlink.net> 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=""/>
ÂÂÂ <xi:include href=""/>
ÂÂÂ <xi:include href=""/>
ÂÂÂ <xi:include href=""/>
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: docbook-apps-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org