Renaming cross reference link

New Here ,
Mar 08, 2020 Mar 08, 2020

Copy link to clipboard

Copied

Hello, 

 

I have documentation for my code that I maintain in Doxygen (general description + API reference). Our documentation team working with FrameMaker so I generate an XML output for them which were imported to FrameMaker using some template file which I do not fully understand. We reached good maturity and it works well except I cannot generate internal references with a custom naming. i.e. with the XML input below :

<ref refid="group__ip__class_1gaad23d5c191f1ede03638140cb21ca31f" kindref="member">actions</ref>

I would expect that link text will be action, but currently, action just attached as a text after the link with link text taken from element referenced by refid.

 

I have found many ways to control a text of link text here, but all of them as far as I understand working with target link text and do not provide a way for the custom text from the ref element.

 

I can modify my XML in a way it's needed and can manipulate templates in FrameMaker (almost 0 knowledge here).
Any suggestions will be greatly appreciated.

Thanks, Ilya.

TOPICS
Structured, XML author

Views

1.1K

Likes

translate

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Adobe Community Professional ,
Mar 08, 2020 Mar 08, 2020

Copy link to clipboard

Copied

Typically, in a FrameMaker cross-reference, you do not directly specify the test that you want to appear as the cross-reference text. You use building-blocks in your cross-reference format that will determine which text from the target will appear. For example, the <$elemtext> building block displays the target element's text as the cross-reference text.

 

If you want to specify your own text that may be different from the target, you could use the <$attribute[attrname]> building block and specify the desired target text (for example, "actions") as an attribute value. In this case, you could have an attribute on your target element called xref-text. Then the building block for your cross-reference format would be <$attribute[xref-text]> and you would leave it out of your <ref> element.

 

Here is a list of possible building blocks with element and attribute types highlighted. If you need further help setting this up, please let us know. Thanks.

 

image.png

Likes

translate

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
New Here ,
Mar 09, 2020 Mar 09, 2020

Copy link to clipboard

Copied

Hello,

 

Thanks for the suggestion, I will try it today. 

Just a quick question.  In your suggestion to add an attribute with link text the attribute needs to be added to the ref element or refid element? 

Is the following XML is an expected input? 

<ref refid="group__ip__class_1gaad23d5c191f1ede03638140cb21ca31f" kindref="member" link_text="actions"/>

And the expected building blocks will be <$attribute[link_text]>

 

Regards,

Ilya. 

Likes

translate

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Adobe Community Professional ,
Mar 09, 2020 Mar 09, 2020

Copy link to clipboard

Copied

Your <ref> element is correct, except the link_text attribute doesn't go on it. It will go on the target element that has the matching id of "group__ip__class_1gaad23d5c191f1ede03638140cb21ca31f".

Likes

translate

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Adobe Community Professional ,
Mar 09, 2020 Mar 09, 2020

Copy link to clipboard

Copied

Here is a mockup of how it all fits together in FrameMaker:

 

image.png

Likes

translate

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
New Here ,
Mar 09, 2020 Mar 09, 2020

Copy link to clipboard

Copied

Thanks,

But this is not exactly what I'm looking for.

I want to have 2 different link names for the same referred object so I cannot put it in the reference object it must be defined on the link itself.   

For example:

I have a definition of the structure in C code. 

If I refer to this structure from over C code (as a parameter to function for example ) I want to refer by structure name, but if I refer from the text describing the feature I want to provide a more human-readable name. 

Doxygen, HTML, and Word support such functionality natively I hope that it can be done in FrameMaker as well. Basically, if I write in definition custom text it's doing what is supposed to do , question how I retrieve this text from the <ref/>  node automatically. 

 

Regards, 

Ilya. 

 

 

 

 

 

 

 

 

Likes

translate

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Adobe Community Professional ,
Mar 09, 2020 Mar 09, 2020

Copy link to clipboard

Copied

Just define two separate Cross-Reference formats in your FrameMaker template. One will use the attribute value and the other will use <$elemtext>. Add a format attribute on the <ref> element which will tell FrameMaker which Cross-Reference format to use. You can set up your Read/Write rules so that the format attribute will tell FrameMaker which Cross-Reference format to use, based on the format attribute.

Likes

translate

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
New Here ,
Mar 09, 2020 Mar 09, 2020

Copy link to clipboard

Copied

This is not trivial... 

 

In the XML file generated by Doxygen, I don't know the difference between those 2.

In the Doxygen input file it will be: 

\defgroup ip_class IP Class 

 

 \ref ip_class or \ref ip_class "actions"

 

but in XML I will get it already processed to : 

 

<ref refid="group__ip__class_1gaad23d5c191f1ede03638140cb21ca31f" kindref="member">IP Class</ref>

or 

 

<ref refid="group__ip__class_1gaad23d5c191f1ede03638140cb21ca31f" kindref="member">actions</ref>

 

 

I can reformat the ref  to:

 

<ref refid="group__ip__class_1gaad23d5c191f1ede03638140cb21ca31f" kindref="member" link_text="Link Text"/>

 

maybe I even can push the "Link text" to the referenced object attribute, but I will not know which one.

Sounds I need to give up on custom text idea, I assumed it's a trivial thing, sounds like it's not. 

 

Thanks anyway. 

Ilya. 

 

 

Likes

translate

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Adobe Community Professional ,
Mar 09, 2020 Mar 09, 2020

Copy link to clipboard

Copied

Don't give up so fast. Let me know when you might have time for a web meeting so I can look at your setup. I am pretty sure you can make this happen if you have some control over how your xml is created. Please contact me off-list: rick at frameexpert dot com.

Likes

translate

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines