XREF Oddity

[Eric Lachance]

Hello All,

I'm having a pretty odd issue with cross-references in my document. First, this is the style I'm using:

Code: Select all

MadCap|xref
{
	mc-format: '{quote}{paratext}{quote} (page {page})';
}

@media non-print
{
	MadCap|xref
	{
		mc-format: '{paratext}';
	}
}

And when I create a cross-reference, this is what I get in the XML source:

Code: Select all

<MadCap:xref href="Managing your configuration files.htm">"Managing your configuration files" (page 1)</MadCap:xref>

I'm generating two outputs, one being WebHelp, the other being PDF. However, while the WebHelp output is fine (it's just the link, blue underline, as expected), the PDF output is really odd. First, it doesn't use the correct page (it leaves page 1). Second, the link itself is pointing towards a local HTML on my hard drive (C:\data\My Projects\Content\Managing your configuration files.html) instead of pointing to the page in the PDF itself. Even weirder, the link is invalid. It tries to point towards the location of the project (C:\Data is the location of "My Documents" on my PC), but it doesn't do it right : it should be C:\data\My Projects\PROJECT NAME\Content\Managing your configuration files.html !

I'm at a loss here, is this a known bug, or am I doing something wrong? I tried putting the style in the @media print section, that didn't change anything.

[LTinker68]

Is the behavior happening in the built output or in the Preview window?

[Eric Lachance]

Is the behavior happening in the built output or in the Preview window?

I hadn't tried the preview (since it was obvious that cross-references wouldn't work in preview mode), but I just tried and I get the same behaviour. One difference though, this time the physical path to the file, in the link, is the correct one.

[LTinker68]

I hadn't tried the preview (since it was obvious that cross-references wouldn't work in preview mode)...

Not everyone gets that, so I wanted to rule that out first.

You might want to open the topic containing the xref in the Internal Text Editor and make sure there isn't a problem with the tag itself. I think I had a case in the past where there was a blank xref or something so it looked ok in the editor but didn't work right. You might also want to double-check that it's pointing to the correct item.

Also, what output are you using the non-print medium with? I generally recommend not using that medium because it doesn't work the way people expect it to. I'd stick to using the default medium for online output, use the built-in print medium for printing from online output, and create a custom medium for PDF output. Or, you could have two stylesheets, one for the online outputs (including printing from the online output) and one for the print outputs (PDF, Word, Framemaker).

[Eric Lachance]

Lisa,

Though this particular project is small, I am planning for the future and I am not sure having 2 style sheets will be very easy or fun to manage. So I consider a PDF to be "print" and a webhelp to be "non-print". I'm assuming that this was the intent of the feature (though I do know that these are standard CSS functions). Note that I did specifically put the xref CSS in the "general" area, and overwrote it in the non-print for the WebHelp, so it's definitely not a question of print vs non-print.

In terms of the code, it's exactly as I wrote up there, the xref tag does have an href, and it's properly being seen by the non-print CSS in my WebHelp output, so I know it's only when doing the PDF.

I'm really puzzled

[LTinker68]

I can't get to http://www.w3c.org from work so I can't verify that non-print was intended for browsers so much as it was intended for other media besides a standard web browser. So do you define styles in three mediums -- default, print, and non-print -- or just the print and non-print mediums?

And when I mentioned double-checking the xref, I didn't mean double-checking it's style -- I meant double-checking what it's referencing, the href attribute of the xref tag. From the href of your example before, it appears to be cross-referencing to a topic and not a bookmark within the topic. I noticed that the topic name has spaces in it -- I got into the habit a few years ago of not using spaces in file names because some browsers had problems with it. If you rename the topic file name to not have any spaces in it, and choose yes to the option to update the links, then rebuild, does that resolve the print output's issue with the xref?

[Eric Lachance]

Ok... it's official. I'm no longer puzzled. I'm pissed.

Here's the XML Source code:

Code: Select all

        <p>Test: <MadCap:xref href="Overview.htm">"Overview" (page 1)</MadCap:xref><br />
		Test: <MadCap:xref href="GettingStarted.htm">"Getting Started" (page 1)</MadCap:xref> </p>

There has been no change in the CSS files - that remained the same as previously. I have two xrefs, one right after the other, both are pointing to files that exist, and that do not have spaces in them.

Here's the @#$%@#$^:
The FIRST one WORKS. The SECOND one DOESN'T.

This time instead of pointing to a file in the wrong path... it doesn't point to anything, it's like if it was static text.

Can someone explain to me what the hell is wrong with this thing?

[Nita Beck]

I have had this happen in my print outputs, too. It always turns out that I have neglected to include the destination topic in the print output's TOC. Flare can't resolve the link to a spot in the output 'cause that spot doesn't exist in the output. So, verify that you've got that topic in the TOC...

Oh, one more thing: If your xref format includes a page number, Flare will always show the "dead" xref has pointing to "page 1." I have made it a best practice when I'm finalizing print output (well, specifically PDF; I rarely output to Word) to search in the PDF for "page 1." That'll yield things like "page 16", but I blast past those looking for "page 1". It's rare that I xref to something that's really on page 1, so this is a quick way to find the "dead" items.

[Eric Lachance]

Nita, thanks. That's exactly what it was (why I chose the only page that didn't output is beyond me)...

I'm still a bit frustrated though - I got it working, but only thanks to this great community - the software was absolutely no help at all. No warnings, no indications whatsoever of what was wrong. If this forum didn't exist, I would have thrown Flare out the window a long time ago.

I mean, I found 2 bugs on the first day of my trial period. That's pretty bad.

[Nita Beck]

Eric, I can completely commiserate with your "new user" difficulties. I started using Flare at V1.0, though not for paying gigs. I actually disliked it a lot at the start... and even long afterward! I used to call myself "The Reluctant Propellerhead" among my tech writing pals. But I kept at it, and then, with V4.0, a lightbulb over my head started to illuminate. Gradually it got brighter and brighter. Next thing I knew, I was completely sold on the supreme value of this ingenious tool, and I convinced my clients that we needed to switch. (It's not simply a matter of my deciding to switch, BTW. There are conversion costs with migrating legacy content, and I needed my clients' buy-in to proceed. But I digress...)

The learning curve is indeed very steep for many of us. But I, for one, think the tool is well worth mastering. I can do SO much more with this tool than with any of the others I've used in my very long time in this profession.

Let me offer you a few pieces of advice as you start out:
-- Start with a small project, if possible. (You might be past this stage already...)
-- Allow yourself time to grow in your Flare expertise. Don't try to master everything at once.
-- Write things down. Document your design decisions. You will NOT remember everything you did in a particular Flare project, and you will give yourself a huge leg-up for down-the-road maintenance if you keep detailed, orderly notes.

[Eric Lachance]

Thanks for the tips Nita.

I am, actually, starting with a relatively small project. That is, a 30-page user guide for a simple, "user-friendly" software (though if it was that user friendly, it wouldn't need a manual, right? ).

The next step on will be to convert our existing documentation (7 manuals for a 5-software suite) into Flare. I'm actually well under way of that, all that I have left is to insert indexes form the legacy system into the HTML files I'm "manually" converting to Flare's XML format (not that hard, a few replacements here and there). That's a few thousand pages of text, so it's quite massive and pretty scary to know I'm the only one managing that.

Then I'll have to single-source the hell out of all of that, and that's going to take quite a while to master

[Nita Beck]

Sounds like my kind of project!

Two last bits of unsolicited advice that are especially helpful for conversion projects:
-- Do things in batches: chapters, sections, whatever.
-- Devise some sort of mechanism to track your progress through those batches, be it a spreadsheet or a checklist in a Word doc. It is SO easy to get lost in the Flare forest among all the trees. Having a checklist lets you instantly see how much stuff you've got left to process, and it helps to ensure that you do the same tasks uniformly across the legacy material.

I'll send my bill in the morning!

[Eric Lachance]

Thanks again Nita.

Most of what I would have to do is repetitive tasks - and I don't do repetitive tasks. It's not that I don't want to, it's that I tend to devise some automated processes that will do them for me. As my programmer friend would put it: I spend 2 hours doing a script that will save me 10 seconds per day over the course of the next few years.

In this case, I'm using the product that this documentation is about (PlanetPress Watch, and automation tool) to grab the files necessary in my legacy format, "massage" it into xml, adding the TOC, headers, indexes, etc, and be done with it forever. Then, all I need to do is create a stylesheet for the existing data and it's more or less done.

The single sourcing conversion though... I have 2 other books to read, and a lot of planning to do, it's not for tomorrow. Actually, because of major changes in the software itself it may be easier for us to just start from scratch, which will be much more effective

Cheers, and have a good weekend!