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 <m1...@earthlink.net
<mailto:m1...@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="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: docbook-apps-unsubscr...@lists.oasis-open.org
<mailto:docbook-apps-unsubscr...@lists.oasis-open.org>
For additional commands, e-mail:
docbook-apps-h...@lists.oasis-open.org
<mailto:docbook-apps-h...@lists.oasis-open.org>
