Welcome to Telelogic Product Support
  Home Downloads Knowledgebase Case Tracking Licensing Help Telelogic Passport
Telelogic DOORS (steve huntington)
Decrease font size
Increase font size
Topic Title: Cross-Referencing in DOORS
Topic Summary: Is it possible to import, create, maintain and export cross-references in DOORS
Created On: 2-Jun-2005 10:44
Status: Post and Reply
Linear : Threading : Single : Branch
Search Topic Search Topic
Topic Tools Topic Tools
Quick Reply Quick Reply
Subscribe to this topic Subscribe to this topic
E-mail this topic to someone. E-mail this topic
Bookmark this topic Bookmark this topic
View similar topics View similar topics
View topic in raw text format. Print this topic.
Answer This question was answered by Andrew Foster, on Monday, June 20, 2005 10:55 AM

Answer:
In my experience I have found the most effect way to cross reference within a DOORS module is to replace paragraph references (e.g 3.2.1.1) with Object Identifiers (e.g SRD_123). As these are unique, don't change through the life of the object, and don't get reused, I don't have to concern myself within updating anything if I insert data at a later date.
 2-Jun-2005 10:44
User is offline View Users Profile Print this message


Graham Joyce

Posts: 6
Joined: 5-Feb-2004

I'm struggling to manage cross-referencing in DOORS. Whereas it is very easy to reference a specific figure/table/paragrapgh in WORD by creating an 'cross-reference' (which automatically orders and can be updated), I can't find a way of maintaing this in DOORS.

If importing to DOORS from WORD, cross-references seem to be lost. If starting in DOORS, with a view to exporting to WORD, I can't find an easy way to create cross-references.

I'm sure there must be a clever combination of internal linking and DXL to achieve the end result, has anybody managed to do this before? It's very easy to import/export graphics, tables, etc. in and out of DOORS, but it seems very difficult to refer to them in a robust way that bridges the gap between the two pieces of software.

Can anybody help?

Many thanks,

Graham

Edited: 2-Jun-2005 at 11:12 by Graham Joyce
Report this to a Moderator Report this to a Moderator
 2-Jun-2005 19:42
User is offline View Users Profile Print this message


Louie Landale

Posts: 2070
Joined: 12-Sep-2002

Doors will have hard coded references. The Table or OLE can have "Figure 3.2.1.1-1" label in the Text. The other object refers to that explicitely, perhaps ".. as per Figure 3.2.1.1-1". When Exported to MS-Word, those words are normal and are not "referenced" as per the Word insert-reference command.

The problem is managing the reference number in DOORS manually. If you insert a new OLE above the old one within the same section, you'll have to manually renumber the labels and references following it manually. That's why the scheme uses the Paragraph Numbers in the reference, 3.2.1.1. Choose a depth (4 in this case) and stick with it.

Getting exported Word to actually have References is a much more complicated issue. And its ultimately undesirable since the only reason to have them is so they can change dynamically, but then the exported Word file would NOT match the DOORS module.

- Louie
Report this to a Moderator Report this to a Moderator
 3-Jun-2005 17:15
User is offline View Users Profile Print this message


Andrew Foster

Posts: 3
Joined: 21-Feb-2005

Answer Answer
In my experience I have found the most effect way to cross reference within a DOORS module is to replace paragraph references (e.g 3.2.1.1) with Object Identifiers (e.g SRD_123). As these are unique, don't change through the life of the object, and don't get reused, I don't have to concern myself within updating anything if I insert data at a later date.

-------------------------
Andrew Foster
Senior Consultant
Telelogic UK Limited
Report this to a Moderator Report this to a Moderator
 20-Jun-2005 11:53
User is offline View Users Profile Print this message


Graham Joyce

Posts: 6
Joined: 5-Feb-2004

I've had a bit of a play around, and this is definately the best way to cross-reference in DOORS. For quick navigation, an internal link can also be used (from the object with the reference to the object with the OLE). This links can also be used to highlight 'Dead References' when Figures and Tables are deleted. For people who can live with non-sequential Table and Figure numbers, this will also export to WORD.

For people who can't live with non-sequential Table and Figure numbers, I'm sure there must be a clever combination of DXL and WORD macro to turn this into a caption/cross-reference combination. I plan to have a go at this soon, I'll let you know how I get on. For anybody else who may know how to do this sort of thing, I think the general approach is as follows....

1) Each Figure and Table exists as an OLE in DOORS. Within the same object (either before or after the OLE) the 'Caption' is typed in the Object Text, using the unique identifier of the object (e.g. "Figure SRD1254 - Model Schematic").

2) In the text, the Figure/Table is referenced as follows, "As shown in Figure SRD1254".

3) When exported to WORD, DXL and/or a Visual Basic WORD macro can be used to recognise each OLE, and strip off the Caption text. The first part of the Caption text (i.e. before the "-") identifies which type of caption it is (e.g. Table or Figure). A suitable Caption is then inserted before/after the Figure/Table with it's WORD generated auto-numbering, and the remaining Caption text (e.g. Figure 1 - Model Schematic).

4) As part of the DXL/macro, a temporary matrix is created matching the WORD auto-numbering to the DOORS reference (e.g. [Figure 1 , Figure SRD1254]).

5) Once all the Tables anf Figures are in place, the entire document is then searched for DOORS references (e.g. "Figure SRD....") and when one is found a cross-reference is generated to the appropriate Caption using the temporary matrix. It may help the coding to have some sort of symbol in the referencing text (e.g. Figure%SRD1254), but this may not be necessary.

6) If all this works, you should get sequentially numbered, cross-referenced Figures and Tables.

The difficult bit is obviously automating steps 3-5, but I think the general approach is sound. I'll have a play with DXL and Visual Basic and let you know how I get on. If anybody else has any success, do let me know.

Thanks to Louie and Andrew for your help.

Graham
Report this to a Moderator Report this to a Moderator
 20-Jun-2005 17:28
User is offline View Users Profile Print this message


michael Barnes

Posts: 85
Joined: 12-Nov-2003

Whilst this is the best way to cross-reference in DOORS, it does not address the problem stated: how to cross-reference in the document that is produced from DOORS.

In a document the reader needs to have a reference that can be found easily. There is no way for the reader to know where in the document the referenced object is.

I would agree with the response from Louie:
    Allocate fixed numbers and stick to them.

    To keep the numbers in order, when inserting a new figure/table, add another "dot" level or increment the appropriate dot-level. Thus you might have: 1, 2, 2.1, 2.1.1, 2.2, 3.


This generally takes little effort
Report this to a Moderator Report this to a Moderator
 29-Jun-2005 16:49
User is offline View Users Profile Print this message


Jonathan Marshall

Posts: 27
Joined: 10-Apr-2003

In my customised Export to Word script, I handle captions and cross references by using the object identifiers.

The system supports captions anywhere within the Object text using a fixed format to identify the text as a caption:

[wd(F|T)Caption: Caption Text]

selecting F or T defines whether its a table or a figure caption.

During the export these pieces of text are replaced by Word Captions which means that they can be automatically indexed by Word at the front of the document with clickable links when converted to PDF

Cross references can be put anywhere else in the text and refer to the object identifier which contains the caption. As in:

"Blah blah... see (Figure|Table) SRD-123"

In case there is more than one caption in an object you can also append a counter. So this would refer to the second caption in SRD-123:

"Blah blah... see Figure SRD-123-2"

The system also allows cross referencing to headings using the object identifier:

"see section SRD-321"

Cross references are replaced during the output to word with the correct word caption or heading number. I haven't tried to make these clickable Word cross references yet but I may get round to that sometime.

Jon

-------------------------
Jonathan Marshall
EADS Astrium
Report this to a Moderator Report this to a Moderator
 30-Jun-2005 12:33
User is offline View Users Profile Print this message


Hazel Woodcock

Posts: 78
Joined: 6-May-2005

A half baked idea, which probably needs a little bit of layout DXL.

For objects that need the reference display the DOORS Object number in a column.
For objects that reference them (obviously through a suitably named link module), display the Object number in an analysis column.
The reference will appear in Word after the object text, so you just say 'as in reference' or similar.  Using the object number gives the position in the document structure.

The trick is to only display the references where they are wanted, and not everywhere.  (Just when there is a suitable incoming link?).  Also you won't get a 'live' link in Word.

Report this to a Moderator Report this to a Moderator
 12-Jul-2005 15:02
User is offline View Users Profile Print this message


Graham Joyce

Posts: 6
Joined: 5-Feb-2004

Jonathan,

Your "customised Export to Word script" sounds exactly like what I was planning to produce. Is this a work in progress, or do you have it up and running? Have you produced this within DOORS using DXL, or have you developed some software of your own? Is the code something you are able to share?

I will be attending a DXL course in the near future, and will hopefully become more proficient, but any code you can share on this specific issue would be a huge help in getting me started.

Even if you are not able to share your code, it is good to hear somebody has found a solution to this problem, and that I'm not barking up the wrong tree - so many thanks.

Regards,

Graham Joyce
Report this to a Moderator Report this to a Moderator
 13-Jul-2005 20:41
User is offline View Users Profile Print this message


Greg Lacefield

Posts: 13
Joined: 23-Oct-2003

We use something similar to Jonathan's approach, but go one step further with a custom RTF exporter to reach a solution for which I think many of you are looking--a document that manages to:
  • sequence itself so that table and figure numbers do not have to be manually maintained in DOORS;
  • provides you with automated Tables of Tables (TOT) and Figures (TOF);
  • allows authors to insert a cross-reference from any point A to any point B in the document such as not to disrupt the natural language flow;
  • provides references which are useful in either electronic or paper format, which implies that they can be looked up in a conventional manner, i.e., manually via section numbers, not simply by Object IDs;
  • is fully hyperlinkable.
In addition, for our own reasons which are out of scope of this post, we have divided some of our documents into multiple modules which we then piece together in Word. Depending on our target customer and/or product, any combination of these modules may be incorporated into a given document. For this reason, we have the additional requirement that the cross-references must be resolved in Word itself, since section numbering is unknown prior to aggregation.

The solution, in one word, is bookmarks:
  • To facilitate the caption requirements, OLEs are captioned in either the same object or an object above with a special command syntax that indicates the position of the caption, e.g.,
      (caption: figure Structure Diagram)
  • To facilitate the natural language requirement, cross-references can appear anywhere in the Object Text and reference any object, not just captions, with another special syntax, using the Object ID of the target, e.g.,
      (xref: SRS_125)
  • When the module is exported, for each object:
    • Since the Object ID is always included in the export, the exported OID text is tagged as an RTF bookmark. Since bookmarks in a document must be unique, it is named for the OID itself.
    • Caption command syntax is converted to sequence number fields using the caption sequences and styles.
    • Each caption's number and text are created as separate bookmarks that are based off the object's bookmark name. So an object that is bookmarked "SRS_125" and contains a caption would also have bookmarks created named "SRS_125_NUM" and "SRS_125_TEXT".
    • Each xref is expanded into several hyperlinked RTF reference fields (REF) which are different forms of a reference to the corresponding RTF bookmark (or, in the case of a caption, bookmarks). These typically include a section number reference, section heading reference, and object ID reference for ease of lookup by a reader. So

        See (xref: SRS_125) for details.

      in the Object Text gets expanded to

        See section 1.2.5, "How to Build Cross-References Into DOORS", SRS_125 for details.

      where each of "1.2.5", "How to...", and "SRS_125" are actually RTF fields which Word can update. Likewise, references to captions

        ...as shown in (xref: c SRS_130).

      in the Object Text may get expanded to

        ...as shown in Figure 1-3, "Exporter Process Flow".

  • Once exported, then, the file is inserted into our standard engineering document template, we press F9 twice (once to update all fields, the second to update the TOT and TOF based on the updated fields from the first update) and we have a document that is fully cross-referenced with proper sequencing, includes hyperlinks for these references, and contains a full TOT and TOF.
Unfortunately, the DXL for exporting and researching the corresponding RTF syntax must remain exercises left to the reader. We started with the RTF exporter included with DOORS and customized it accordingly.

This is the basic approach, though, and it works for us. We no longer manage any fixed numbering at all, and we have functional output. Since every object is bookmarked, each document has hundreds if not thousands of bookmarks, but our experience has been that Word seems to handle this OK. The only thing we need to ensure is that xrefs don't go stale, but you have to do that for any scheme. Our solution for this is another script that scours the module and flags objects which contain xrefs to objects that do not exist.

Enjoy,

Greg

Edited: 14-Jul-2005 at 00:20 by Greg Lacefield
Report this to a Moderator Report this to a Moderator
Statistics
20925 users are registered to the Telelogic DOORS forum.
There are currently 1 users logged in.
The most users ever online was 15 on 15-Jan-2009 at 16:36.
There are currently 0 guests browsing this forum, which makes a total of 1 users using this forum.
You have posted 0 messages to this forum. 0 overall.

FuseTalk Standard Edition v3.2 - © 1999-2009 FuseTalk Inc. All rights reserved.