OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [docbook-apps] using olinks everywhere?


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




[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]