Creating a text reference to figures

[daz]

How do I create a text reference to a figure? So if I update a document with more figures, it will automatically make changes to figure references.

Thanks in advance.

[adrian]

Hi,

I don't understand the context of this question.
Could you provide more details, what type of XML document are you using(DocBook, DITA, etc) or is it something custom?

A simple example would also be useful.

Regards,
Adrian

[daz]

Hi,
I'm creating a xml document using DITA.
I've inserted dita image, and tagged it with a <fig> element and <title> element. I'd like to reference the <title> in my paragraph text.

That way if I update the document with more dita images, I won't have manually update image references in my body text. I hope this make things clearer. See below to what I currently have done:

Code: Select all

<p>The LAN screen configures the network settings of the device as shown in Figure.</p>

    <p>

      <fig><title>Basic Tab</title>

        <image href="../images/web_config/WNS_web_firm2_20_6/Basic/6-10-2010%20LAN.png"

          id="image_d9c0b42f-9e21-4964-93ba-28b08bee30ee"/>

      </fig>

    </p>

[adrian]

Hi,

Tag the text title with a <ph>(phrase) element and give this ph element an id(Either generated or manually assigned to be easier to identify).
Then you can insert in the paragraph(or other locations) a content reference(DITA -> Insert Content Reference) to that phrase.

e.g.

Code: Select all

<p>The LAN screen configures the network settings of the device as shown in Figure<ph conref="basicTabID"/> .</p>

        <p>

            <fig><title><ph id="basicTabID">Basic Tab</ph></title>

                <image href="../images/web_config/WNS_web_firm2_20_6/Basic/6-10-2010%20LAN.png"

                    id="image_d9c0b42f-9e21-4964-93ba-28b08bee30ee"/>

            </fig>

        </p>

Regards,
Adrian

[daz]

Hi Adrian,
I've tried what you have suggested but get this error:

Conref was not expanded:
The source element "ph" with class value "- topic/ph " is not a generalization of target element "body" with class value "- topic/body " .

[sorin_ristache]

Hello,

The error message says that the value of the conref attribute of the ph element is the same as the value of the id attribute of a body element. Please make sure you set the id value from a ph element (not a body element) as the value of the conref attribute as in the above example. As specified in the error message the element with the conref attribute (in the above example <ph conref="basicTabID"/>) must be a DITA generalization of the element with the id attribute (in the above example <ph id="basicTabID">Basic Tab</ph>) and you can check that by looking at the class attribute in the Attributes view.

If you still get an error please post a complete sample DITA topic document for reproducing the error.


Regards,
Sorin

[daz]

Hi sorin,
ok I got it working. However it references the <title> tag of the fig. I would actually like to reference the <fig> tag. However this doesn't seem possible?

[sorin_ristache]

A content reference is a placeholder for other element which means the element that will replace the placeholder must keep the DITA topic valid. This is why the element with the conref attribute must be a generalization of the element with the id attribute.

In your particular case if you want to reuse the title of the figure in a paragraph (the p element) using a ph element in both the figure title and the paragraph seems perfect to me. A fig cannot be the target of the conref attribute because a fig cannot be validly inserted in p.


Regards,
Sorin

[daz]

Hi Sorin,
Thanks for your help. It's much appreciated.
I probably haven't been 100% clear what I'm aiming for.
When I tag a DITA image with a <fig> element, I also insert a <title> element. I can see Figure: inserted when viewed in the oxygen author and then I add a title to the figure.

I've noticed it doesn't add a figure no. in the .dita file as it seems to do that when you use a transformation scenario (in my case I'm using the dita map pdf).

What I would like to insert is a reference to the Figure no. in p. Because I know with future dita file updates, I may add or remove dita images. That way all figure references in the p will automatically be updated.

I apologise as I'm quite the newbie to xml. Ideally I would like for it to be setup so it's easier for future document updates.

Thanks again

[sorin_ristache]

Hello,

In that case I think you need a cross reference (the xref element), not a content reference. The figure number is generated automatically in the output by some XSLT stylesheets. You need not worry about the specific numbers as they are automatically generated in consecutive order based on the order of figures in the XML source file and the order of the topicref elements in the DITA map file. Just insert a cross reference from the paragraph to the figure and this will be transformed to a hyperlink in the output (PDF, XHTML, JavaHelp, Eclipse Help, etc). You insert a cross reference quickly in Author mode by selecting with the mouse the text that should link to other element (the text Basic Tab Figure in the next example), clicking on the action Cross Reference from the Author toolbar, specifying the file that is the target of the reference (in this case the same as the file containing the reference) and selecting the ID of the target element (figure-id in the next example code).

Code: Select all

<topic id="topic-id">

  <title>Topic title</title>

  <body>

    <p>The LAN screen configures the network settings of the device as shown in Basic Tab Figure.</p>

    <p>

      <fig id="figure-id">

        <title>Basic Tab</title>

        <image href="test.png"/>

      </fig>

    </p>

  </body>

</topic>

Edit this DITA topic in Author mode, select the text Basic Tab Figure and follow the steps that I outlined above. The cross reference will be created as in the following code:

Code: Select all

<topic id="topic-id">

  <title>Topic title</title>

  <body>

    <p>The LAN screen configures the network settings of the device as shown in <xref href="#topic-id/figure-id" format="dita">Basic Tab Figure</xref>.</p>

    <p>

      <fig id="figure-id">

        <title>Basic Tab</title>

        <image href="test.png"/>

      </fig>

    </p>

  </body>

</topic>

Regards,
Sorin

[daz]

Hi Sorin,
Thanks I tried doing as you mentioned. It didn't seem to work when outputting the dita files to pdf format. All it did was highlighting the text in a different color (obviously referencing the figure.

Actually I don't need a hyperlink to the figure.
All I need in the body text is when mentioning a figure it automatically inserts the figure number (e.g. 1,2,3 etc). The same process when <fig> numbering is automatically generated based on the order of figures in the XML source file and the order of the topicref elements in the DITA map file.

[daz]

I should clarify in that all i need in the body text is only the <fig> element numbering inserted when referencing to a figure.

[sorin_ristache]

Hello,

Inserting the figure number also in the paragraph where the figure is referenced is not done automatically. The XSLT stylesheets that transform the DITA XML topics to XSL-FO (needed for generating the final PDF result) must be customized for that. The starting points are the stylesheets [Oxygen-install-folder]/frameworks/dita/DITA-OT/demo/fo/xsl/fo/topic2fo_shell_1.0.xsl and [Oxygen-install-folder]/frameworks/dita/DITA-OT/demo/fo/xsl/common/topicmerge.xsl. Maybe you can find some expert users who already did that customization on the dita-users mailing list.


Regards,
Sorin

[tomjohnson1492]

I'm not sure if I have the same question, but I'm trying to get output that looks as follows:

See Figure [x] for more information.

[image]
Figure [x]


Here's my code:

<p>See <xref href="#concept_lcw_fkl_q4/image1" type="fig"/> for details.</p>

<fig id="image1">
<title>Oxygen Sample Webhelp</title>
<image href="oxygen.png" placement="break"/>
</fig>

The output says "See Figure [x] for more information," but there's nothing below the image that says "Figure [x]" at all. There's a link that points to the image, but the image itself lacks the figure reference. There is text indicating the figure in the PDF output. Am I to assume that with the webhelp output, there's no need for the image to have "Figure [x]" in the caption because the text reference hyperlinks to it?

[sorin_ristache]

That is correct, in the Webhelp output there is no label like Figure [x] preceding the figure title, and a link to the figure does not include any figure label. In Webhelp as in all other XHTML-based formats generated from DITA XML sources the text of the link is simply the text between the link tags (for example link text in case of <xref href="#concept_lcw_fkl_q4/image1" type="fig">link text</xref>), without a preceding label.

The PDF output contains a label in the figure title but that label is not included in a link to the figure. A customization would be needed in the DITA PDF transformation for including the figure label in the text of the link to that figure, as specified in my previous post.


Regards,
Sorin

[tomjohnson1492]

Thanks for the info.