single-sourced xrefs

This forum is for Single-Sourcing your Flare content to multiple outputs.
Post Reply
pdenchfield
Propellus Maximus
Posts: 574
Joined: Tue Oct 03, 2006 7:56 am
Location: Seattle, WA
Contact:

single-sourced xrefs

Post by pdenchfield »

(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!
GregStenhouse
Sr. Propeller Head
Posts: 330
Joined: Tue May 13, 2008 3:27 pm
Location: Christchurch, New Zealand

Re: single-sourced xrefs

Post by GregStenhouse »

pdenchfield wrote:If you have suggestions for fixing this conditionalizing topic/snippet scheme for our 1600-topic/400-snippet project, please let me know.
I think you need to adjust your mindset from target-specific folders, to what is common and what isn't. A folder structure like the following might be more appropriate:
\Shared All
\Shared AAA BBB
\Shared BBB CCC
\Only CCC
etc

Note that the folder structure in the content explorer does not really matter when it comes to outputting your targets. For print outputs, the TOC determines what makes it in. For online targets, conditions determine what makes it in, and I really think you should be conditonalising at the topic/image level (rather than folder level). Esepcially if you have topics that are reused across folders.

Another option for you might be global project linking. This would give you more control over what is included or not (i.e. you can import from a "parent" project that has all common files, and base the import on condition, filename, part filename, and/or folder).
pdenchfield wrote:(Vista, Flare 4.2)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 "pag 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).
There is something called "unbinding" xrefs. You need to apply conditonal text to the xref tag, then select Exclude Action as "Unbind". That means the <a> link will be removed, but the text will remain if the conditon is excluded. Another thing to try might be {pageref} (context sensitive cross references). They may behave differently if broken in an output. Finally, if you use global project linking to import only the relevant files for a target, you can run reports that search for broken xrefs. That will at least point the authors towards where they are, to then go and conditonalise in the parent project.

Hope that gives you a few ideas
Cheers
Greg
pdenchfield
Propellus Maximus
Posts: 574
Joined: Tue Oct 03, 2006 7:56 am
Location: Seattle, WA
Contact:

Re: single-sourced xrefs

Post by pdenchfield »

Thanks, Greg. I have passed on the suggestion for a "shared" folder and applying tags to topics instead of folders (though it's much easier to apply once, if a folder's topics are only used for a particular TOC/target...but guess that's not true - still thinking on it).

Regarding the context-sensitive cross-references, it would be great if Flare added a setting in the language skin that would allow me to display just the heading text when (1) the referenced topic is excluded from the target and (2) the target is print.

Current language skin settings for Format > Cross Reference - with asterisked addition by me:
Format - by default just the heading
Format for Print - by default heading and page number
**Format for Print When Topic is Excluded** - (my suggested addition) just the heading
Below Reference - below
Above Reference - above
On Page Reference - on page
On Previous Page Reference - on previous page
On Next Page Reference - on next page
On Facing Page Reference - on the facing page

Example: Topic A has an xref to Topic B: See "Topic B" on page 1 in the BB Manual. Target AA (PDF type), which points to the TOC containing Topic A, excludes the condition that is applied to Topic B, so that topic will not be included in the ouptut and the xref won't work, which is expected. Currently the "page 1" is displayed even though the xref doesn't work. If I use an xref format that includes {pageref} for context-sensitive cross-reference behavior and Flare somehow is able to keep track of excluded topics as well as the print nature of the target to apply the correct format (Format for Print When Topic is Excluded), then the page number reference "on page 1" will happily be omitted from the PDF so it reads ... See "Topic B" in the BB Manual - rather than ... See "Topic B" on page 1 in the BB Manual.

I will submit a feature enhancement request. Appreciate all the suggestions!
pdenchfield
Propellus Maximus
Posts: 574
Joined: Tue Oct 03, 2006 7:56 am
Location: Seattle, WA
Contact:

Re: single-sourced xrefs

Post by pdenchfield »

Hi all, I'm on Flare v5 now and cannot reproduce the "page 1" problem with new content, although I saw it in my old files when building a PDF target. After updating the xrefs, however, the "page 1" problem went away. (Even though the code didn't look any different...?) So...I guess Flare v5 resolved the "page 1" issue in broken xrefs!
Post Reply