Not Considering

Modify Pub Manager so it does not try and resolve xrefs that are conditionalized out of the pub

Publication Manager (version 11.1.2) tries to resolve all xrefs when releasing the publication, even if the content containing the xref is conditionalized out of the publication. If there is content that contains xrefs, but the content is conditinalized out of the pub, the pub publishes fine, and if everything is released, it results in a Release Candidate. But if I attempt to release the pub, it throws an error, saying that it contains hypertext links that cannot be resolved.

The use case: we produce HTML-based output that contains many maps. We want to include xrefs that link the reader to content in other maps when they are using the HTML output. But we also produce PDFs for each of the individual maps. Therefore, in each location where we reference content in another map, want to include two paragraphs: one that includes an xref to the other content, and one that includes a citation to the other content. Both of the paragraphs are conditionalized (HTML and PDF). When we produce the HTML output, we include the paragraph with the xref. When we produce the PDF output, we include the paragraph with the citation. This all works great. We can produce the output with no problem. But it falls apart when we try and release the publication that contains the individual map for which we produce the PDF output. Pub Manager will not release it. It says there are unresolved cross references. There really aren't because they are conditionalized out of the publication. Pub Manager needs to be changed to NOT try and resolve xrefs during the release phase that are conditionalized out.

Dana Murphy

  • We are in dangerous waters, but we still need to get to the other shore. The tool needs to be better at helping us "audit" our publications, but we also need better guidance (and usability) to get away from publication-centric content management.

  • From my point of view, item #4 would be a big step in the wrong direction. We happen to use shared baselines extensively, and the idea of messing with the integrity of the baseline does not sound like a good idea. It is already possible to move a publication from one baseline to another, so the scenario you are outlining could be accommodated using existing functionality. Then you could name the breakaway baseline however you wanted ("Snapshot-yyyy-mm-dd-of-[Original baseline]").

  • I'd tend to suggest "remove inline links and use reltables," and incidentally, use multiple maps and publications, rather than treat DITA like Docbook, and try to do everything in one publication and map file, with complex, heavily conditionalized topics. Move complexity out of the topics. Reuse simple topics in multiple places. If you use conditions, then try to use them at the map file level, rather than inside topics, which is what Tony Self suggested with ditavals over a decade ago.  But I know that is not an easy change, and my company is not in a position to cast stones from our ideal practice, either....

  • Thank you for your response, Frank. I fully agree with your first point that if the pub is a Release Candidate, it should be able to be released without any further validation.  And I agree that if a topic in a Release Candidate is changed, the pub status should change to "Out of date." I also like the idea of an Admin being able to "unrelease" a pub.  I also agree with your third point about just releasing outputs. We don't explicitly freeze baselines. We simply release the output. The baseline is frozen automatically. Thanks for looking into this.

  • The biggest problem today is that we *only* know if links, hyperlinks, variables, and so on are valid if you publish the entire document. Only during publishing, we know which objects will be in the resulting document. Because you can put conditions everywhere, combined with the fact that you can nest objects multiple levels deep, it is very hard to do this on the fly. For that reason, the “Release” mechanism today tries to ensure that every object in the baseline is valid, even though it might be conditioned out. It doesn’t take the published output into account.

    Personally, I want to make the process less strict and easier to understand. Below you can find my ideas on how it could work:

    1. Ensure that if the status says “Release candidate” it can be released without additional validation
      • Today, we only change the status from “Release candidate” to “Out-of-date” if someone selected a new condition in the Conditions tab.
      • If a user makes a change to a topic, changes the metadata, or selects a new version in the baseline, the status is not changed to “Out-of-date”. Technically, this is not correct because you did make changes that would invalidated the published output.
      • This would need to be changed and any changes that would make the published result no longer accurate, should move the status to “Out-of-date”.  Like this, there is no more need to do additional validation when releasing a publication. In other words, it will always be safe to move a “Release candidate” to “Released”, even without additional validation!
    2. Make it possible to “unrelease” a publication
      • If users with the necessary permission want to modify the context (~ conditions), they should be able to “Unrelease” the publication.
      • This enables them to make their change, republish and release again
    3. Get rid of the difference between releasing an output and freezing a baseline
      • You just release an output!
      • This will make it easier for users as they only have one concept they need to understand
    4. One complexity: What should happen if the baseline is shared between different publications
      • Today, you cannot release an output or freeze a baseline if there are, for example, non-released objects in the baseline that are only relevant for another publication. This can happen because the baseline is shared between multiple publications.
      • My proposal would be that we take a snapshot of the baseline when you release one of these publications, use that snapshot of the baseline for the publication you have released and disregard all objects in the baseline that are not relevant to this publication.
      • The drawback (but maybe also an advantage) is that from that moment on publications that used to share a baseline and were consistent in which versions were used, start having their own life cycle and can drift apart.

    Feedback welcome as always.

    Frank