single-sourced xrefs
Posted: Thu Jun 25, 2009 10:07 am
(Vista, Flare 4.2)
Our project includes 40 targets, 20 TOCs, 1600 topics, and 400 snippets. The targets differ by product name branding as well as by medium (print or online).
Example targets:
- AAA User Guide PRINT
- BBB User Guide PRINT
- CCC Module Guide PRINT
- BBB User Guide ONLINE
- etc.
...where AAA, BBB, and CCC are product names for that target's output, and PRINT and ONLINE are the target mediums
Our topics and snippets are in conditionalized folders. For example, the topic "Name Keys" is in the User Guide folder, conditionalized for the User Guide manual (which corresponds to three targets above, differentiated by brand and medium). We did this conditionalizing so that our online targets would not include all 1600 topics. So the BBB User Guide ONLINE topic only includes User Guide topics, which number less than 400.
This setup doesn't work when topics are shared across TOCs. For example, the aforementioned "Name Keys" topic is used in both User Guide and Module Guide TOCs. Thus, if we follow a strict protocol of excluding all manual-specific conditions except the target-specific manual, then the Module Guide targets won't include "Name Keys." We work around this problem by writing down where all shared topics are located (folder structure determines conditions applied) and adjusting the target condition exclusions accordingly. Not ideal, but kind of workable. So the Module Guide target includes not only its 150 topics but the 400 User Guide topics as well, just to catch that "Name Keys" topic. That is the first issue I feel compelled to mention before getting into the xrefs. If you have suggestions for fixing this conditionalizing topic/snippet scheme for our 1600-topic/400-snippet project, please let me know.
Now the xrefs. The two BBB targets above point to the User Guide TOC. (The TOC entries for the front matter topics are conditionalized as Print Only and excluded from the online target.) Here are some problem xref situations in this scenario.
1. xref to an excluded topic (by virtue of condition tag either applied to topic or to topic's parent folder; typically used when referencing another manual in the documentation set)
2. broken xref (topic is included but was moved)
In both situations, Flare automatically turns the xref to plain text, keeping the print-only page reference that is normally discarded for online outputs, resulting in a "page 1" reference in all outputs (print or online). Are these known issues? Preferred output would be to remove the bad page reference from all outputs (and notify author in error log of broken xref...leave it at that).
In our dynamic world of single-sourcing, MadCap would do well to help authors maintain precision in xrefs and let the final appearance of those xrefs vary according to whether that xref is accessible from the final output. That is, let us create the xref without having to remember the structure of the doc set and whether the topic will be included in every instance where the xref is visible (as in a snippet).
Oh please tell me I overlooked something in Flare!
Our project includes 40 targets, 20 TOCs, 1600 topics, and 400 snippets. The targets differ by product name branding as well as by medium (print or online).
Example targets:
- AAA User Guide PRINT
- BBB User Guide PRINT
- CCC Module Guide PRINT
- BBB User Guide ONLINE
- etc.
...where AAA, BBB, and CCC are product names for that target's output, and PRINT and ONLINE are the target mediums
Our topics and snippets are in conditionalized folders. For example, the topic "Name Keys" is in the User Guide folder, conditionalized for the User Guide manual (which corresponds to three targets above, differentiated by brand and medium). We did this conditionalizing so that our online targets would not include all 1600 topics. So the BBB User Guide ONLINE topic only includes User Guide topics, which number less than 400.
This setup doesn't work when topics are shared across TOCs. For example, the aforementioned "Name Keys" topic is used in both User Guide and Module Guide TOCs. Thus, if we follow a strict protocol of excluding all manual-specific conditions except the target-specific manual, then the Module Guide targets won't include "Name Keys." We work around this problem by writing down where all shared topics are located (folder structure determines conditions applied) and adjusting the target condition exclusions accordingly. Not ideal, but kind of workable. So the Module Guide target includes not only its 150 topics but the 400 User Guide topics as well, just to catch that "Name Keys" topic. That is the first issue I feel compelled to mention before getting into the xrefs. If you have suggestions for fixing this conditionalizing topic/snippet scheme for our 1600-topic/400-snippet project, please let me know.
Now the xrefs. The two BBB targets above point to the User Guide TOC. (The TOC entries for the front matter topics are conditionalized as Print Only and excluded from the online target.) Here are some problem xref situations in this scenario.
1. xref to an excluded topic (by virtue of condition tag either applied to topic or to topic's parent folder; typically used when referencing another manual in the documentation set)
2. broken xref (topic is included but was moved)
In both situations, Flare automatically turns the xref to plain text, keeping the print-only page reference that is normally discarded for online outputs, resulting in a "page 1" reference in all outputs (print or online). Are these known issues? Preferred output would be to remove the bad page reference from all outputs (and notify author in error log of broken xref...leave it at that).
In our dynamic world of single-sourcing, MadCap would do well to help authors maintain precision in xrefs and let the final appearance of those xrefs vary according to whether that xref is accessible from the final output. That is, let us create the xref without having to remember the structure of the doc set and whether the topic will be included in every instance where the xref is visible (as in a snippet).
Oh please tell me I overlooked something in Flare!