Conrefs in xml files disappear in generated book file

Report · Jan 21, 2010

I'm using FM 8 in Tech Comm Suite 1 in a Windows XP environment.

I've used a conref in a number of my topics. The conref is a note tag. I have just generated a book file and the conrefs are not displaying in my chapter files. Why?

Thanks.

Report · Jan 21, 2010

Hi...

Conrefs in FM8 were a little flaky under certain conditions. Are you up on the latest FM patch .. it should be 8.0p277.

I assume that when you reopen the topic file, the conref is properly built? Does the conref target live in a file that's included in the map or is it separate from the map?

When you build the book and go to the location where the conref should exist, is the <note> element still there (in the Structure View window), and if it is can you check the @conref attribute value .. is it pointing at something reasonable?

Do you have other conrefs in your files that are working?

Sorry for all the questions, but there are lots of reasons that this may not work.

...scott

Scott Prentice

Leximation, Inc.

www.leximation.com

Report · Jan 22, 2010

Scott,

Thanks for your quick response. A colleague and I spent hours on this yesterday.

My answer to your questions ( I don't seem to be able to format my responses to differentiate them from your questions - sorry):

Conrefs in FM8 were a little flaky under certain conditions. Are you up on the latest FM patch .. it should be 8.0p277. No, I'm on 8.0p266 and am a little hesitant to download something when I'm trying to meet a release deadline. I've been burned before by downloads.

I assume that when you reopen the topic file, the conref is properly built? Does the conref target live in a file that's included in the map or is it separate from the map? Below are the steps that we used to create the conref.

Here is what we did (again, sorry for the lack of numbering):

We created a separate topic for the conref note. We selected concept as the topic type.

We inserted the note tag within the paragraph tag in the conbody.

We created the text of the note.

We then requested an ID to identify the note and then inserted some descriptive text as a preface to the note id number. For example, cr_note_lock_id101M720KD5Z.

We saved the conref to a separate file that we maintain for conrefs. This is outside of the ditamap file for which we are generating the book.

We went to the task topic that calls the conref and placed our cursor at the point of insertion. Even though you can insert conrefs just about anywhere, we made sure that we inserted the conref in a location for which a note tag was appropriate.

We selected DITA > Insert Conref from the FM main toolbar.

We navigated to the location of the conref file,then selected the note element tag. This was easy to identify since we had inserted identifying text.

We then saved the file and generated the book file.

The conref did not display in the file. We reviewed the structure view and the ID of the note tag displayed what appeared to be a path to the location of the conref. It showed as \Conref\cr-note_lock_unlock_model.msl#cr_note_lock_unlock_id101LH01)C5Z/cr_note_lock_unlock_id101M720K05Z.

I'm not quite sure what you mean by the @conref attribute value. I'm assuming it's what I referred to as a path in the step above.

None of the other conrefs are working either, but I used the same conref throughout this book.

Thanks again for your interest in helping us out.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Mary K. Greer

Information Developer - Learning Management Solutions

Intelligent Automation Solutions Client Services

Convergys

407.771.8187

Report · Jan 22, 2010

Hi Mary...

I'd definitely suggest upgrading. Issues with conrefs were fixed in one of the patches .. don't know if this was the one or not, but this patch has been out there and in use for a long time now and I'd think that it should be fine. You can always roll back to a previous patch level if needed.

If the conref doesn't display properly in the topic file, it's not going to display in the book. I'm thinking that perhaps your conref file (the one that contains the target of the conref) is not formatted properly .. or not named properly. from your description, it looks like the file may be named "cr-note_lock_unlock_model.msl" .. these files must be DITA XML files and should be named with ".xml" or ".dita" file extensions. The topic type doesn't matter .. typically you'd use a "topic" topic for your conrefs since that'll hold most any element .. but it should woth with a "concept" topic as well.

It looks like the topic ID of this file is "cr_note_lock_unlock_id101LH01)C5Z" .. does it really have a right parenthesis in it (if so I'd delete it)? You can see the topic ID by looking in the Structure View window and expanding the attributes for the root (concept) element. Use the Attributes dialog to see the attributes if they are too long to fit in the Structure View window. Since a topic can hold lots of conref targets, typically the topic ID would be something more generic .. you don't need the "cr_note_lock_unlock_" portion .. but that shouldn't cause a problem.

My reference to the @conref attribute is basically the value you provided .. by convention, when you see an "@somename" that means "somename attribute".

I'd start by creating a conref to an element that's in the same file. This is the most basic structure and should work in all cases .. get that working and then move on to making a conref to something in an external file.

Let me know how it goes.

...scott

Report · Jan 26, 2010

Okay, Scott, this is what we've got:

We have created a conref that is a note. The file name is cr_note_lock_unlock.xml. We attached an ID to the note (101M720K05Z). This note is contained in a table that has an icon in the left column and the contents of the note in the right column. The note contents are enclosed in ph tags with change bars. The note is viewable in the topic if we select Special > Filter by Attribute > Show All. This conref is inserted within

tags inside a stepresult tag.

When we generate an FM Document from a ditamap, we are able to see the conref; however, when we generate a book file, we are not able to see it.

In the generated book file, all that we can see are two sets of empty note tags; in the FM Document that was generated from the ditamap, we see only one note tag that contains the conref.

We examined the DITA Reference Manager dialog box which we used to insert the conref. When we selected the note element tag, the following is displayed in the Element Data list box:

cr_note_lock_unlock_id101M720K05Z | NO CONTENT

Is that enough for you to go on?

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Mary K. Greer

Information Developer - Learning Management Solutions

Intelligent Automation Solutions Client Services

Convergys

407.771.8187

Report · Jan 26, 2010

Hi Mary...

You've introduced a number of new conditions that add to the puzzle.

First .. did you install the latest patch? You really should.

Second .. there are/were issues with conrefs in tables .. I'd try making a really simple conref to a <li> or <p> that's just in a topic body. Keep it simple and work up to the more complex structures. I don't know if the <ph> tags are causing part of the trouble, but I'd get rid of them for now.

I'm not sure why you're using the Filter By Attribute, but that shouldn't have any effect on things (well, it could, depending on certain settings, but we won't go there for now). Are you saying that if you don't run this command, the conref isn't visible?

I'm not totally understanding the separate line .. "tags inside a stepresult tag" .. are you referring to the conref source or the conref target? That is .. the file that contains the element that is being conreffed or the file that contains the element with the @conref attribute?

Generating an FM Document creates a single file for the whole map, while the other creates multiple documents. This shouldn't cause any differences, but if you're still on the older version, this could be part of the conref bug.

In the book component that's generated, you want to examine the value of the conref attribute on the <note> element (assuming that's what you're conreffing). Look in the Structure View, and expand the attributes for the <note> element, dbl-click the conref attribute and see what it shows for the value. is it pointing to an XML file or a FM file? Is the path to the file actually pointing to a proper location?

The Reference Manager will report "NO CONTENT" when you're trying to reference a table cell .. are you sure you've put the ID on the right element?

I really think you need to get the conref out of the table and don't use the <ph> elements .. just try making a simple conref, and see if that lives through the conversion.

Lemme know!

...scott

Report · Jan 27, 2010

Scott,

Answers to your questions are below. Let me know if samples can be sent.

Thanks for all of your time and interest.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Mary K. Greer

Information Developer - Learning Management Solutions

Intelligent Automation Solutions Client Services

407.771.8187

Report · Jan 27, 2010

Hi Mary...

Where is "below"?

Feel free to upload samples to my inbox at .. http://leximation.com/inbox

Cheers,

...scott

Report · Jan 27, 2010

Scott,

I've decided to use the forums to respond to you. It allow me to use formatting, which I have used to indicate my responses (in bold) to your questions.

You've introduced a number of new conditions that add to the puzzle.

First .. did you install the latest patch? You really should. Yes, I did install the latest patch and am now up to 8.0p277.

Second .. there are/were issues with conrefs in tables .. I'd try making a really simple conref to a <li> or <p> that's just in a topic body. Keep it simple and work up to the more complex structures. I don't know if the <ph> tags are causing part of the trouble, but I'd get rid of them for now. I probably need to clarify that the entire note is the conref, and not the contents of the note. I selected a note format since the conref is being used in a task and there aren't a lot of options as far as paragraph formats in a task.

I'm not sure why you're using the Filter By Attribute, but that shouldn't have any effect on things (well, it could, depending on certain settings, but we won't go there for now). Are you saying that if you don't run this command, the conref isn't visible? If we do not run the filter by attribute, we cannot see the conref.

I'm not totally understanding the separate line .. "tags inside a stepresult tag" .. are you referring to the conref source or the conref target? That is .. the file that contains the element that is being conreffed or the file that contains the element with the @conref attribute? It is the conref source.

Generating an FM Document creates a single file for the whole map, while the other creates multiple documents. This shouldn't cause any differences, but if you're still on the older version, this could be part of the conref bug. I generated the FM document after the patches had been applied, so that's not the problem.

In the book component that's generated, you want to examine the value of the conref attribute on the <note> element (assuming that's what you're conreffing). Look in the Structure View, and expand the attributes for the <note> element, dbl-click the conref attribute and see what it shows for the value. is it pointing to an XML file or a FM file? Is the path to the file actually pointing to a proper location? In the generated book file, two sets of empty note tags are displayed. The conref attribute in each note is pointing to the xml file. It looks like this:
..\Conref\cr_note_lock_unlock_model.xml#cr_note_lock_unlock_id101LH010C5Z/cr_note_lock_unlock_id101M720K05Z

The Reference Manager will report "NO CONTENT" when you're trying to reference a table cell .. are you sure you've put the ID on the right element? I put the ID on the note itself, not the table. When I select note as the element tag, the ID is displayed followed by NO CONTENT.

I really think you need to get the conref out of the table and don't use the <ph> elements .. just try making a simple conref, and see if that lives through the conversion. The conref isn't in the table. The entire table is the conref.

Thanks.

Report · Jan 27, 2010

Hi Mary...

Jumping to your last comment .. "The conref isn't in the table. The entire table is the conref." .. maybe I missed it in earlier posts, but this changes everything. You're conreffing a "table" not a "note". The table may be used as a note or contain a note, but it sounds like you're making a conref to a table element. is this correct?

I believe that FM8 DITA has problems with conreffing tables. I can't validate this right now .. it may just be problems conreffing rows or cells .. I don't remember.

If you can only see the conref by using the Filter By Attribute command, something is *very* wrong.

When you generate the book and the FM document, are you generating those files to the same folder as the original map or DITA file? I ask because I'll bet that the value of the conref attribute .. "../Conref/<and so on>" may not be valid from the location that the new file has been created. FM8 DITA has a problem resolving references in book builds if the files aren't all in the same folder. I believe that it doesn't "fix up" the paths properly so that the references can update properly after the book or document has been created (this was fixed in FM9). I'll bet that if you create the book or document in the same folder as the original XML document that contains the conref reference, the conref will appear.

Do feel free to upload a ZIP of your sample DITA files to my inbox (listed in previous post).

However .. you might want to check out DITA-FMx (my plugin). This fixes the FM8 limitations as well as providing lots of other nice authoring and publishing features.

http://leximation.com/dita-fmx/

The 30-day trial should give you plenty of time to make sure it does what it's supposed to.

Cheers,

...scott

Scott Prentice

Leximation, Inc.

www.leximation.com

Report · Jan 27, 2010

Hi Mary...

Got your sample files.

OK, your structure is note/table .. a table within a note element .. you are conreffing a note element. In theory this *should* work and does for me under certain circumstances. I think your problem is your directory structure. FM8 DITA does not do a good job at resolving references in complex (or not so complex) directory structures. If you put all of the files in one folder (map, topics and conref source files) .. it will most likely work (if you build the FM document or book to that folder as well).

I'm running out right now so can't do any more extensive testing. Let me know if this helps at all .. I can check it out more tomorrow if you'd like.

Cheers,

...scott

Report · Jan 28, 2010

Scott,

In a word: SUCCESS!

The conrefs now are displayed properly in my book file if I put the tasks, conref, and ditamap in the same file location, and then generate a book in the same file location. Thank you so much for making this connection for us. How do we get rid of the fact that we cannot see the conref unless we do a filter by attribute?

Conrefs must be picky little animals, since we've not had any problems at all due to file structure prior to this ordeal. We keep all of our ditamaps in one folder; graphics are kept in a separate folder, and tasks, concepts, topics, and conrefs are in subfolders under a folder called XML. We've been able to successfully generate large books with no problems until now.

I posted a query to the forum over a year ago asking how people manage their files. I thought the query would render a deluge of responses, but I only got one response.

I would think having everything reside in one folder must make it difficult to find files unless a very strict naming convention is put in place.

I would appreciate your take on how files should be managed.

Thanks again, you wonderful man!

Report · Jan 28, 2010

HI Mary...

That's great news!

This is a fundamental problem with FM8 DITA, and has largely been fixed in FM9. It is also fixed in FM8 if you use DITA-FMx.

The problem is that FM8 DITA does not fix up the reference paths after a book conversion.This will be a problem for all types of references .. xrefs, images, and conrefs. The value of the @href or @conref will remain unchanged through the conversion process, even though the file's location may change due to the aggregation of the separate topic files into single chapter files. This can happen because of the location that you're building the book, but can also happen if your topic directory structure causes the content to move from one directory to another when the files are combined.

Another problem that you'll probably run into with FM8 DITA is that the @href value for xrefs remains pointing at the original XML file rather than the new FM file. The xrefs will "look" OK, and will function in Frame (with a CTRL+ALT+CLICK), but when you make a PDF the links will be broken since the XML files aren't part of the PDF. This is also fixed in FM9 as well as with DITA-FMx.

Personally, I'm not a big proponent of complicated directory structures with DITA. When you try to move/rename files, you're bound to have all sorts of linking problems if you've got special folders for each topic type and use. I prefer to have one directory that holds all of the files for a given project. If you have multiple projects that share content, then you can have a "shared" folder that is a sibling to the project folders. Put the maps in the same folder as the topics or in a parent folder. The maps should never be "below" content (you should never have a "../" that starts an @href in a topicref). Soemthing like this ..

+ projects/

. . - shared_content/

. . - shared_images/

. . + project1/

. . . - images/

. . + project2/

. . . - images/

. . - project1.ditamap

. . - project2.ditamap

When you build the book .. create it in the "projects" folder and your references *should* all work properly (other than the xref problem I mention).

You should never need to look for files in the "project" folders. Always access the files via the maps. If you've got lots of files or want to break things up for easy access by multiple writers, create submaps for each chapter (or even sub-submaps for sections within chapters).

Cheers,

...scott

Report · Jan 28, 2010

Scott,

You've certainly given us quite a bit to consider re: file structure. We will probably institute a new file structure based on your recommendations after the current release. At that point, we'll be able to explore DITA-FMx, too.

Can you tell us how to fix the filter by attribute problem? We don't want to have to remember to have that turned on in order to see the conrefs.

Sorry to be such a drain on your time.

Mary

Report · Jan 28, 2010

Hi Mary...

The Filter by Attribute issue isn't one I've seen. The only thing I can think of is that possibly you've applied conditions/filtering to a file, and those conditions are being saved in the XML as PIs (Processing Instructions). I'm not seeing any PIs in the files you sent so that may not be the issue. I'm a bit stumped by this one.

Perhaps you can describe the problem as you see it when opening and working with files? What's not visible when you open a file? Only in books or topics as well? What do you do to "fix" the problem?

BTW .. one more point on the suggested file structure. For conrefs, you don't need to create a separate "container" for each conref source. You can just have one "conref" file that contains all of the conrefs for a project. Some people put all of hte conref source chunks in a 2-column table (first column is a label that describes the conref, and the second column is the actual conref source) .. this won't work for a conref that is a table (you can't nest tables) .. but you can still have multiple conrefs in one file. Also for conrefs that aren't shared between projects, just have the "conref" file in the project folder itself. No need to put it in a separate place.

Cheers,

...scott

Report · Jan 31, 2010

Scott,

I'm going to open a new discussion about filtering by attributes so that other users can search on it. I will pick up where we left off.

Conrefs in xml files disappear in generated book file

1 Correct answer