Adding figure references to images.

[Kat se gat]

I couldn't seem to find an answer in the Flare PDF guides so mebbe one of you good people can advise me.

Let's say I have an image on a page. In the template I'm using I copied an unordered list and changed the figure reference <p> to this: <p class="Figure" style="text-align: center;" MadCap:autonum="Figure 1-1 ">Add my figure comment here.</p>

The screenshot shows what it looks like. Let's say that on page 80 further on I want to add a reference back to that figure, something like, "Refer to figure 10-4 for blah blah blah". How do I do that? If I added another image before my example image the figure number would need to change (automagically?) and so I'd like the reference on my fictitious page 80 to reflect whatever the new figure number is.

I'm sure this all quite easy but I can't see how to do it in Flare.

[Lydia]

I would use a crossreference with my own style, e.g. MadCap|xref.Figure. This style has the mc-format set to '{paranum}' and you could any generic text to it you want to use every time. You can also add {paratext}, which would then give you the text of the figure caption.

[Kat se gat]

Lydia, I tried adding an xref and I was able to get it to work, leastways, my xref printed the topic name and it's page number which was fine. I can't quite see how to link to the figure. In other words if I had some figures on a page how would I create the xref so it prints say, "see Figure 4-3 on page 26" and for the other one "see Figure 4-1 on page 26"?

Then if I moved figure 3 before figure 2 it would print "see Figure 4-2 on page 26"?

I'm almost thinking that I need to do something like this: add something to figures 1 and 2 and give them internal names like "MyFigA" and "MyFigB" and then when I want to refer them somewhere else I'd use something like "see [MyFigB] and while you're there look at [MyFigA] as well." I know it doesn't work like that but that's about as good as I can express it if you can decode what I'm getting at?

[Nita Beck]

Peter, you need to insert a bookmark at each figure title that you want to direct an xref to. Then, when you create the xref, direct it to the specific bookmarked figure title and, as Lydia says, select the xref format you've set up for xrefs to figures (e.g., xref.Figure or whatever you call it).

Yes, if you move an image and its figure title to a diff location, such as above another image and its figure title or even to another topic altogether, Flare will automatically manage the renumbering of the figure title AND of the generated xrefs.

Sorry so short. HTH.

[Kat se gat]

Nita. A bookmark, eh? I'd have never guessed that. Let me see what I can unearth in the help documents about them. Thanks for the heads-up on them.

I sort of saw what Lydia had in mind after I read it a few times. So, the sum of the bookmarks and the styling should do it for me. Time to roll up my sleeves.

[Nita Beck]

A bookmark, eh? I'd have never guessed that. Let me see what I can unearth in the help documents about them.

Check this out: http://webhelp.madcapsoftware.com/flare ... rences.htm Especially under "Automating Links Based on Commands," look at the third example. It goes into great detail, including talking about needing to have the bookmark in place so that the xref has a destination.

[Lydia]

Hello Peter,
I should have mentioned the bookmark part . Indeed this is needed to (cross)reference the figure caption. Then, when you move figures or insert new ones, numbering and the reference will update. Note, that the cross-reference does not update automatically in Flare. It will update in your output, though. If you want xreferences updated in Flare, go to the Tools ribbon and click "Update Cross-References" in the Update section. This updates the xreferences in your current topic (not all topics!).

[Kat se gat]

Ladies, many thanks for your valued input. I will research it all in more depth.

[Kat se gat]

Sorry ladies, I am being as dense as a piece of granite rock. I'm sorry to say that I still don't get it. I read and reread Nita's link to the Flare help but my understanding of it completely eludes me. Here's what I tried and still fail on:

I add an image. Underneath it, I copied and pasted a <p> from elsewhere in the document which also emits a "Figure X-Y...". As I understand things, adding that <p> is like inserting a cross reference? I tweaked the text ever so slightly and generated and viewed the PDF output. As expected, the text below the image says something like "Figure 1-1 my image". Back in the IDE, I added a bookmark called MyFigA to the <p>. Generating the PDF and viewing it looks identical. All good so far, methinks.

I went to another topic and added a new paragraph and in that paragraph I added some trivial text and then added a hyperlink. I selected the bookmark. Viewing the PDF output lets me click on the hyperlink and it jumps back to the page where my figure is. But, it doesn't output something like "See Figure 1-1 on page 6" for example. I'm sorry to say, despite my best efforts I still can't work that bit out; hence my brain is (today at least) made of granite or something denser still. I did try adding a subclass to the Madcap xref style (I called mine MyFigureALooksLikeThis) but I'm having a total brain fart.

I don't know if it's possible to upload a zipped project but do you have a minimal project you could give me that shows how to do it? I just need something very trivial but demonstrable that I can tear to pieces and try and unravel what is to me "The Great Stumbling Block As Narrated by Granite Kop."

[emsachs]

2 pieces. The easy one first.

On the Insert menu/tab is an option "insert cross-reference". That lets you select a file and optional bookmark for your cross-reference to point to. You can also choose a style for your cross-reference in the section below.

To get the right text for your cross reference, you must create a cross-reference format. You do this using the Stylesheet. In this case, you will want to create a format that somehow resolves to Figure x.y on page z. For instance, i have a figure paragraph that has autonumbering that says Figure 1.2. Then I have a cross reference format that mc-format in the stylesheet set to
{paranum} on page {page}


There are a lot of moving parts in Flare, but eventually it sorts itself out.

[Lydia]

Hi Peter, I hope that your brain is in a less dense state after a night of sleep. Sorry that this thing is giving you so much troubles.
It looks as if the basics aren't clear. Forgive me if they are and if this sounds stupid.
Say you want to link from A -> B.
B is where you set the bookmark.
A is where you put the link, which could be a hyperlink or a cross-reference.
You seem to have said that you put the crossreference at B, which is not how it would work.

To illustrate or give you an example you were asking for:

Code: Select all

<body>
        <h1 MadCap:autonum="1 ">crossreferences</h1>
        <p>Here is a picture</p>
        <p class="FigureTitle" MadCap:autonum="Figure 1-1: "><a name="MyPicture"></a>My first picture</p>
        <p>and then way down in the document or in a different universe I cross reference the picture like this</p>
        <p>So please look at <MadCap:xref href="#MyPicture" class="Figure">Figure 1-1:  My first picture</MadCap:xref></p>
    </body>

You can copy and paste this in a topic and work with it.

The CSS you will need:

Code: Select all

p.FigureTitle
{
    mc-auto-number-format: 'CF:Figure {chapnum}-{n+}: ';
    page-break-before: avoid;
}
MadCap|xref.Figure
{
	mc-format: '{paranum} {paratext}';
}

I hope this gives you something to start with.

[Kat se gat]

Sorry to report that the space between my ears is still full of rocks. I tried what you documented and I'm still not getting it to work. Sorry!

My screenshot is a hastily written scribble. I feel like I'm getting close but I really am stuck. Even a good night's sleep didn't help.

[Nita Beck]

No worries. I understand "brain freeze"! Just try this...

In a topic, add an image and add a paragraph beneath it that will serve as the figure title. Now put the cursor back at the start of the paragraph and use Insert > Bookmark to insert a bookmark. I tend to name my figure bookmarks something like this: "fig_sys_config_diagram" (for a diagram of the configuration of a system). Lastly, make sure to apply your figure title style to this paragraph so that it'll get the auto-numbering you've set up for figures.

Next, in some other topic, you'll add a cross-reference to the figure title you just bookmarked. Position the cursor where you want the cross-ref to appear and use Insert > Cross-Reference. Select "File in this project" (I'm going on memory, so don't quote me...) and select the topic that contains the figure. Then about halfway down the Insert Cross-Reference window, click the button that looks like a page with a red bookmark over it. That'll now show you all the bookmarks in the selected topic. Select the bookmark for the figure title. Lastly, near the bottom of the window, select the format for the cross-reference. If you haven't yet created a specific format for cross-references to figure titles, just select the MadCap|xref format for now. (I'm leading you through a little demo here, so you can see how the bookmark and cross-reference play together.)

Now do a build of your target with these two topics in it. In the output, go to that second topic and find the cross-reference to the figure title and click it. You should now be taken to the first topic right to the figure title.

OK; the above is the mechanics of where and how to insert the bookmark and then where and how to insert a cross-reference to that bookmark. Now let's discuss how to set up the necessary styles in your stylesheet so that you'll get the look you're after for your cross-references. And for good measure, I'll cover auto-numbering too.

Here are some relevant styles in one of my projects (with only the salient bits shown):

Code: Select all

p.FigureTitle
/* This assigns an auto-number to my figure titles. The auto-number will render like this "Figure 3-1 " */
{
	mc-auto-number-format: 'CF:Figure {chapnum}–{n+} ';
}

MadCap|xref.Figure
/* This formats a cross-reference to a figure title to yield something like "Figure 3-1 MyTitleHere". */
{
	mc-format: '{paranum}. {paratext}';
}

@media PDF
/* This is the medium I use for PDF output. */

	MadCap|xref.Figure
	{
   /* This yields a cross-reference to a figure title that reads like this: "Figure 3-1 (page 47)". */
		mc-format: '{paranumonly} ({pageref})';
	}

Just try these ideas in a practice topic, even a practice project.

[Kat se gat]

Nita, I think (under caution and granite rocks permitting) that I might have made a breakthrough of sorts. I almost got it working 99% but I think I taco'ed the styling in the document which rendered it mostly black pages where the TOC items would go. Clearly my hasty copy-and-paste technique was at fault. However, under the image I had both the bookmark and the numbering style malarkey. Deep down in the document I added a cross reference to it and it said something like "" on page 6, in other words no mention about Figure 1-1 for example. Clicking it took me to the right spot. That was using your style sheet items but like I say, I mucked it up a bit. The important thing is that I am getting the right cause and effect, only the text displayed at the cross reference went AWOL.

For now, I need to try it again on a new test project and with more time I can look at things in close detail and make incremental instead of temperamental changes.

I will also do some research into auto numbering as well. Although the view from inside my bonce is still a little hazy I'm grateful that it's no longer the dense fog I've been stumbling through the last few days.

Thanks to all for your patience and advice. Much appreciated (beers all round and a glass of wine for the ladies).

[andy_smith]

I've just read this with some incredulity having come from the world of FrameMaker. (Sorry, I'll get me coat.)

I'm a bit stunned that it's not possible to do this without having to first insert a bookmark. I'm hoping that this might have changed since this thread was created in 2015.

Since the figure caption already has a defined location in the document is it not possible to create a link directly to that caption?

Having worked with other authoring tools where linking to figures is pretty much mandatory there is usually something like a context sensitive right click option on the caption. It's been a while since I did this, and the last system I worked in was structured Frame (sorry, I really will get me coat in a minute) where I'm sure it was easier, but am I imagining that it was only structured documentation that allowed this?

I'm expecting to put my cursor where I want to link from (within the same document) and select right click and see my figure listed there rather than go hunting through the content folders or lists of bookmarks. Am I asking too much?