Cross references referring to other user guides

[GaryUK]

We have a large help file which we also use to produce printed output, however the printed manual would be over 1000 pages if we printed it all in one document. Hence, we have split the printed documentation into 3 separate guides. So far so good... until you want to refer to something in another guide.

Cross references work fine in the one big help file, or if the topic is in the same printed guide. For example, it will say "For more information, see "xyz" on page 92. But obviously xrefs can't point to topics in the printed documentation if it isn't in the same document. In these cases, we want it to say 'For more information, see "xyz" in the System Administration Guide' (or whatever guide).

So far, the only way I have been able to do this is to insert a conditional hyperlink to cater for the help, followed by a conditional string (retyped topic heading + "in the System Administration Guide"). This is very time-consuming and error-prone.

I have tried creating xref classes for each manual with literal text in the xref definition referring to the name of the relevant guide, but there are two problems with this:
1. It generates build errors which I am loathe to inhibit because legitimate topics could be missing and I'd want to know about them.
2. The literal text does not appear anyway because the xref is invalid, so it just doesn't handle the xref at all.

Surely this is a fairly common phenomenon. Does anyone have any better way to do it?

[LesNoiz]

This may be a good use for snippets. Create one for each guide, set them to print only, and insert where required.

[LesNoiz]

Also, you say "But obviously xrefs can't point to topics in the printed documentation if it isn't in the same document." Sure they can, as long as the topics are in the same project. You will get an error in the logs indicating that the link is outside the target. I just ignore those.

[GaryUK]

Thanks. I think the conditional snippet idea is great for the printed part of the reference. It will also allow me to use variables for the names of the guides because they could change.

I'm a bit worried about the error messages though. One day there will be a topic that really isn't there that I should know about. I've worked hard to eradicate all messages because the documents will be built on another machine using the command line build. We haven't started doing that yet (that's another can of worms) but I fear it will throw up messages and break the build. If I inhibit that kind of message (V10.1) then I will never know about legitimate problems.

I also tried the "Generate multiple documents for native XPS/PDF output" option with one all-inclusive print target, but that gave me a pdf per chapter. Pity it doesn't work per volume.

I've already done all the hard work so I don't think it's worth going back at this stage and making changes that will result in errors, but it's something to consider for new projects. Thanks for your input

Gary