Using Arbortext and the DITA OT v1.4.1

[ptc-953343]

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?

..dan

[jogden]

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.



-Jeff Ogden

PTC/Arbortext DITA Development Lead

[ptc-953343]

I asked the DITA side of my question on the DITA
user group and this is the answer I got from
Elliott Kimber base of my error message/question appears first:

[ptc-953343]

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.

..dan

[ptc-953343]

Some more notes.

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.

..dan

[jogden]

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.

-Jeff

[jogden]

Dan,



I can't seem to send e-mail to you directly.



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.



-Jeff

[jogden]

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.



-Jeff

[ptc-953343]

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.

..dan

[jogden]

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, ....



-Jeff