I'm in the process of trying to setup a new build process for our first attempt at using DITA and Arbortext. It's a first for both of these, currently everything else is in Frame.
So I build our documents on a central shared machine and Arbortext lives on the writers local machine. I need to make sure that we are both using the same DTDs between the two of us. So I know that under typical SGML/XML circumstances I can point the catalog at a central area.
How dependant is all the extra DITA support based upon the DTDs shipped with Epic? I believe I'm using a newer DTD than what is shipped, because I'm getting validation errors in the build process of topics that were authored directly in Epic. Anyone have pointers on how to integrate these two environments?
Arbortext Editor (aka Epic) and its DITA Application are quite good about using Public IDs and catalogs to resolve DTD references. So, if you get your catalog(s) on to the Catalog path list before the catalogs that are distributed as part of the product, I would expect everything to work.
A possible exception to this is the rdstyle document type that is used internally during Arbortext composition or any xxx-rdstyle document types that you may have created. But this is only a concern if you have created or added new specializations beyond those provided by OASIS and even then only if you are doing your composition from within the Arbortext product. It sounds as if you are using the DITA Open Tool Kit for composition, and if that is the case, the rdstyle and xxx-rdstyle doctypes don't matter. And even if they did matter, there is only an issue if you do not include the new specializations in the ditabase document type or if you add new topicref specializations. If you do either of these things, then some customization of the rdstyle or xxx-rdstyle document types may be needed.
You can look at the catalog files that the Arbortext DITA Application uses. They are all located in the .../application/com.arbortext.dita/doctypes folders, mostly in the ditabase, map, and bookmap sub-folders. Please don't change these files, but you can override them with your own catalog files.
You can check the Catalog path by looking at the Document tab on the Session dialog (Help-->About Arbortext Editor-->Session). You can change your catalog path list from the "File Locations" category on the Editor's Preferences dialog (Tools-->Preferences). You need to make any changes to the catalog path list early before any DITA documents have been opened since open DTDs are cached and won't necessarily be reopened again during the same Editor session.
You can set an initial value for catalog path using the APTCATPATH environment variable. Be sure to include the %D symbolic parameter after your own catalog path entries, so that the Editor will pick up all of the DITA and non-DITA catalogs it needs. Arbortext catalog processing is explained in online help, see Arbortext products overview-->Structured documents-->Working with catalog files or enter help 6563 in the Arbortext Command window.
Changes to the OASIS DITA DTDs and schemas have been mostly or perhaps entirely backward compatible and mostly forward compatible as well. So, I'd be surprised if you are running into version problems with your DITA DTDs, but I guess it could happen.
What version of Arbortext Editor are you using? The current release (5.3 M040) includes a very up-to-date version of the final/official OASIS DITA 1.1 DTDs and schemas including recent errata. I don't think there is anything newer. Older releases included the most recent OASIS DITA DTDs and schemas at the time of the release, although the 5.3 M020 and 5.3 M030 releases may not have included the most recent errata. Arbortext Editor 5.3 F000, M010, M020, and M030 all included the OASIS DITA 1.1 DTDs and schemas before they had been finally and officially approved by the OASIS process. Arbortext Editor 5.2 included the DITA 1.0.1 DTDs and schemas. Epic Editor 5.1 included the earlier IBM versions of the DITA DTDs.
If you run into problems using your own catalogs with the Arbortext DITA Application, please let us know. If there are problems, we'd like to get them fixed as soon as we can.
Ok, I just got Epic M40 installed and I've been able to look at the files myself. So I opened the ditamp file and clicked on the topic in question to open it. The step in this file is empty it just has the conref.
When I do a check completeness it does complain about a missing <cmd> or <cmd/> and the source text from the conref is in line as expected.
When I click into this step I only get a list of the following tags to insert:
choices choicetable info stepresult stepxmp substeps tutorialinfo
I positioned the cursor before and directly after the generated text and nothing is allowed, on the line following the generated text and just before the step end tag is where I get the above list of allowed tags.
Note that I'm using Epic right out of the box as a fresh install with no customizations, just reading these existing files the writer created.
When I open this file and delete the conref, the cmd tags show up (sometimes) in line because they are required. Put the conref back the tags disappear and when I save the <cmd> is missing in the text file.
When I edit the file in text and add the <cmd>, then open it in epic, the cmd tags don't show, but when I delete the conref, they do show up. Paste the conref back in and save and the cmd tags seem to stay in the text file.
Looks like there might be some problem with the hiding and showing of these tags when a conref is involved. My writer might have deleted the <cmd> tags the first time before inserting the conref.
If you want to edit the conref content, you need to edit the DITA task document that contains that content. You can double click on the conrefed element in the referencing document and the referenced document will open in a new Editor window.
Eliot has 5.3 M040. 5.3 M050 hasn't been released yet, but should go out "soon". No changes to the OASIS DTDs or schemas between 5.3 M040 and 5.3 M050.
I agree with Eliot's comments on conref and cmd.
As far as validating goes, when you are working with conrefs things can be a little confusing. While the conref content is displayed within the referencing document, the conref content itself isn't validated as part of the referencing document. It is validated as part of the referenced document if you validated that document. Conref requires checking of the element being conrefed as well as some information that is associated with the topic or map that contains the conrefed content, but it doesn't require the validation of the actual conrefed content since in theory that has to be valid given the other checks.
While you can use Arbortext Editor to create and edit DITA documents that are composed using the DITA Open Toolkit, the OT isn't part of the Arbortext products and isn't supported directly. You won't be able to use plug-ins that you develop for use with the OT directly with Arbortext Editor. That probably isn't a problem since you aren't using Styler and Arbortext Editor's own composition.
It is hard to know what recommendations to make about working with customizations associated with specializations and Arbortext Editor without knowing a lot more about your specializations and what your customizations are doing. But generally you won't need customizations on the Arbortext side if you are just using Arbortext for editing.
From your note it sounds as if you have some DITA specializations that you developed. For those you probably don't want to deal with them using catalog path and instead you want to install them in one or more doctype directories within a custom directory. You may have already done this. There may be some integration issues if you want to use the Resolved Document for Editing with your specializations and you don't include your specializations in a customization of the ditabase document type. There would be integration issues related to the Resolved Document for Styling if you were using Arbortext Editor for composition, but since you aren't, that isn't an issue.
The online help for Arbortext Editor has a lot of information about custom directories, installing new doctypes, installing new DITA doctypes, and integrating new DITA specializations into the Resolved Document for Editing and the Resolved Document for Styling. For the DITA information you want to look at "Help-->Authoring DITA documents-->DITA document types-->Adding specialized DITA document types" or enter "help 6486" at the Editor's Command Window.
I'm not able to follow this. From just the written description I can't tell when you are talking about the tags in the referencing document and the tags in the referenced document.
You can turn the display of conref content on and off using the "View-->Content References" menu item. That can be useful to show you what is actually in the referencing document. Turning conref display off and on again can also cause error or warning messages to be displayed that aren't always displayed when a conref is first processed when a document is initially opened. Turning conref display off and on can also refresh the display of the conref contents in the referencing document if you make changes to the referenced file using an editor other than Arbortext while the referencing document is open within the Arbortext Editor.
A document that uses conref can be valid, but incomplete. That is, it doesn't include some required tags, but it is otherwise valid. This doesn't cause problems because the missing required tags are probably being included as content from the referenced file. The referenced content isn't really in the referencing file. And to make matters more confusing, the referencing file may include content that is ignored when conref is used causing the content in the referencing document to be effectively, but not actually, replaced with the content from the referenced file. Adding or removing a conref can cause displayed content to come and go or to change. Turning content reference display on and off via the View menu can also cause the content to appear and disappear. As you can tell, this can all be a little confusing (and you haven't even tried to conref a row in a table yet, something to look forward to in the future).
Something you may already know, but which may help a little if you don't, is that Arbortext Editor displays conrefed content using generated text. There are pros and cons to this approach, but it means that while the conrefed content can be displayed as part of the referencing document, it can't be edited as part of the referencing document. It also means that while you don't normally see them both, that both the referencing element and the referenced element are part of the referencing document for the purposes of styling for screen display, but only the content from the referencing document and not the content from the referenced document is present in the referencing document for purposes other than screen display.
Hope this helps.
Because this is hard to talk about without a visual display and/or some sample documents to look at, you might want to consider opening a customer call with the PTC Support staff. You should do this for sure if you think that Arbortext Editor isn't performing correctly.
The writer was using m10 so that might be where the problem starts.
I guess I'm surprised that the editor is hiding the empty <cmd> when the conref is used. Maybe turning off the generated text would leave the empty cmd displayed? I haven't tried that yet. As an XML guy it bothers me that this is being hidden.
Where this would get a person in trouble is where a step was inserted outside Epic and it was missing this cmd tag and has a conref. In Epic it's going to look like a correct configuration until I hit the Check Completeness. I was also getting what I thought was strange results when I was trying to insert tags into this step. Again because the <cmd> tag was hidden, my list of tags to insert was missing cmd in the list because it was there, just hidden.
All of this is talking about a single file with a step that conrefs text from another file and what I see when the conref attribute is filled in or not. With conref filled in, I see the generated text, with it empty, I see the <cmd> tag - I think I should always see both.
DITA conrefed content is displayed in a fashion that is very similar to the way that xincluded content is displayed--that is, you can select the display of the xinclude fallback markup or the referenced content, but you never see both. In a future release we plan to make conref content work even more like xincluded content--it won't use gentext, you'd be able to edit the referenced conref content from the referencing document directly, the referenced conref content would be considered part of the referencing document for validation, ....