• State Suggested Answer
  • Replies 2 replies
  • Answers 1 answer
  • Subscribers 138 subscribers
  • Views 1644 views
  • Users 0 members are here
Options
Related

Publication Manager tries to resolve all xrefs when releasing publications, even if conditionalized out

Dana Murphy

We produce "doc sets" that include multiple sub-maps. The doc sets are published as SuiteHelp (HTML).  From within the sub-maps we want to include xrefs to the other sub-maps. We also produce PDF output for each of the individual sub-maps. Where we are including xrefs to other sub-maps, we want to instead include a citation when we are producing the individual PDFs (because, of course, you can't link to topics outside the map). To accomplish this, we include both the xref and the citation, them conditionalize them to include the appropriate one for the type of output, HTML or PDF.  This all works great until we attempt to release the PDF output. During the release phase, Publication Manager tries to resolve ALL xrefs, even if they are conditionalized out of the output you are releasing. So the PDF output cannot be released because it can't resolve the xrefs.

Has anyone else run into this issue, and if so, have you found a workaround? We are considering not releasing those publications, that is, just leave them as a Release Candidate.  The main downside I see is that objects might be updated (new versions created), then inadvertently included in the previous version of the publication. (When a publication is a Release Candidate, you can still create a new version of it.)
Rate translation
×
Suggest better translation
×
Parents
  • 0

    I believe the DITA (1.2 and earlier) approach for this use case is to use @scope="peer" in your xrefs between independently published submaps.So, instead of <xref href="[guid].dita"/>, you will have: <xref href="webhelp.company/pub/map/topic.html" scope="peer" format="html"/>

    I dont know the particulars of all the tools involved, but here is what I'd expect, from a DITA rendering perspective:

    • Workflow should not complain about any unresolveable hrefs when @scope="peer" is used.
    • When publishing the full doc set to HTML, links work as  you desire.
    • When publishing individual PDFs, you may need to still filter these xrefs out and filter in your citations
    • If you ever publish the entire doc set as PDF, it may work as you expect, or you will have to use the same swap done for individual PDFs.

    The drawback is that you dont get any link management for the cross-publication xrefs. This was not an issue for my team when we used this approach to interlink independently managed eclipseHelp plugins in a hosted "Infocenter".

    DITA 1.3 provides more guidance on the concept of "cross-deliverable referencing", but I've not seen the nuts and bolts yet.


    HTH,

    -seth park
  • 0 in reply to seth park
    Thanks for your response, Seth.

    I had previously tried setting the scope attribute to “peer.” However, Publication Manager still reports unresolved xrefs during the release phase with that setting.

    I also tried setting the scope attribute to “external,” but the links did not work in the final HTML output (they were trying to link to the GUID with an .xml extension instead of the needed .html extension).

    I noticed that in your post you suggested setting the format to html, so I also set the format attribute to “html”. That didn’t work either; the links just didn’t work. But, I figured out that when the scope if set to “external,” if I add .html to the GUID in the href attribute, the links work in the HTML, and when they are conditionalized out for the PDF output, Pub Manager doesn’t try to resolve them during the release phase. So that worked! Some fickle stuff.

    As you mentioned, we do lose the xref validation if the scope is set to peer (same with external), but we might be able to live with that.
Reply
  • 0 in reply to seth park
    Thanks for your response, Seth.

    I had previously tried setting the scope attribute to “peer.” However, Publication Manager still reports unresolved xrefs during the release phase with that setting.

    I also tried setting the scope attribute to “external,” but the links did not work in the final HTML output (they were trying to link to the GUID with an .xml extension instead of the needed .html extension).

    I noticed that in your post you suggested setting the format to html, so I also set the format attribute to “html”. That didn’t work either; the links just didn’t work. But, I figured out that when the scope if set to “external,” if I add .html to the GUID in the href attribute, the links work in the HTML, and when they are conditionalized out for the PDF output, Pub Manager doesn’t try to resolve them during the release phase. So that worked! Some fickle stuff.

    As you mentioned, we do lose the xref validation if the scope is set to peer (same with external), but we might be able to live with that.
Children
No Data