Not quite understanding DITAVAL and conditional processing..

[nam]

I have watched the videos on setting up conditional profiles, and have read up in DITAVAL, but I cannot figure out the secret handshake. As I understand it, and as it is implied by the fact the oXygen "Editor/Edit Modes/Author/Profiling/Conditional Text" window allows me to define my own conditional text values (Click Profiling Attributes <New>, enter DITA, enter any attribute name and display name, and add the values the element can be,) then create a profiling condition set and add the attribute you just defined, apply your changes and everything looks swell.

Now, try an add the attribute to an element. It doesn't show up in the list of available attributes.

Ok. Plan B. Create a new DITAVAL file. Load it up with your attributes and their values, exclude or include. Go back into the "Editor/Edit Modes/Author/Profiling/Conditional Text" window and add the DITAVAL file you just created in the Profiling Condition Sets. Apply your changes.

Again, try an add the attribute to an element. Oh...sorry. But here's a copy of our home edition...

What's the secret handshake? Why don't these attributes show up in the list? Can we define our own or not, and if not, why can we add them in the window?

All I want to do is pull in a paragraph that has a ModeOfOperation value of "manual" or "batch". That shouldn't be this difficult. Must I use the OtherProps attribute, and if so, what happens when I need more customized properties??

[Radu]

Hi Neil,

The DITA vocabulary defines 4-5 attributes which can be used for profiling (filtering content) when publishing output:

http://docs.oasis-open.org/dita/v1.2/os ... l#condproc

Or you can create a DITA DTD specialization which adds additional profiling attributes. But you need some DTD knowledge in order to do this and all your team would need to use that particular specialization to edit and validate DITA content:

http://drmacros-xml-rants.blogspot.ro/2 ... ional.html

Coming back to the Preferences->Editor / Edit modes / Author / Profiling/Conditional Text page.
This page has a very flexible way of allowing you to add any attribute because it is generic, the same preferences are used for any XML vocabulary.
But adding an attribute here will not automatically create a DITA specialization for you. It is just a way to instruct the XML editor what profiling attributes you are using, but the editor does not modify the DITA schemas for you in order to declare those new attributes.
If you edit a DITA topic in the visual Author mode, and you right click somewhere in the content, the context menu has an entry called Edit Profiling Attributes. That specific actions allows you to set in a visual manner a set of attributes which have been previously defined in the Editor / Edit modes / Author / Profiling/Conditional Text page. This is the main purpose of that preferences page.

More answers below:

Oh...sorry. But here's a copy of our home edition...

I do not understand this.

What's the secret handshake? Why don't these attributes show up in the list? Can we define our own or not, and if not, why can we add them in the window?

As stated above you need to create your own DITA DTD specialization, Oxygen does not create one for you. If you create a specialization and use it to the topics, the Attributes view from Oxygen will show those specialization attributes for each element allowing you to edit them.

All I want to do is pull in a paragraph that has a ModeOfOperation value of "manual" or "batch". That shouldn't be this difficult. Must I use the OtherProps attribute, and if so, what happens when I need more customized properties??

You can either use the base profiling attributes or make a DITA DTD specialization.
For example if you decide to use "otherprops" and in the Editor / Edit modes / Author / Profiling/Conditional Text you define those two custom values for it, both the Attributes view and the Edit Profiling Attributes action will show your custom values.

Regards,
Radu

[nam]

Thanks, Radu. I sort-of got it working by redefining the otherprops thing. (Sort-of, in that sometimes it works, sometimes not, but I can figure that out.)

So the upshot of your explanation is that although the oXygen Window allows you to enter anything you want, it really doesn't allow you to define anything you want, and without that definition, it won't work. I would think that the window should only pull in definitions that are in the DTD. I wasted a bunch of time trying to figure something that would never work. Maybe it's me, but I find that unnecessarily confusing.

Should I submit a "feature request?"

[Radu]

Hi Neil,

You fully understood the situation. We also have a video demonstration about profiling DITA with Oxygen here:

http://www.oxygenxml.com/demo/DITA_Profiling.html

Two more comments below:

I sort-of got it working by redefining the otherprops thing. (Sort-of, in that sometimes it works, sometimes not, but I can figure that out.)

If you can come up with a small example of what does not work we could try to help with some advice.

I would think that the window should only pull in definitions that are in the DTD.

The problem is that there is no single fixed place where the DTDs could be placed. The DITA topics and maps have references to the DTDs in the DOCTYPE header, references which are mapped through the XML catalogs set up in Oxygen to DTD locations. By default the DTDs used for editing standard DITA topics are located in OXYGEN_INSTALL_DIR\frameworks\dita\DITA-OT. But this does not force users to have the DTDs there. Users could edit DITA topic specializations and have the DTDs somewhere else.
So for an opened topic or map Oxygen can precisely find out which DTDs are used. But the preferences page applies globally and values proposed in it cannot be tied to a certain opened XML document.

When in the Editor / Edit modes / Author / Profiling/Conditional Text preferences page you press the New button to add a new attribute, the dialog which pops up has a small note at the top:

Code: Select all

Note: The attribute must already be defined in the DTD....

We added that note because you are not the first one to stumble across this problem. Should we make the note more striking, maybe use bold font for it?

Regards,
Radu

[nam]

Should we make the note more striking, maybe use bold font for it?

Perhaps. I went back in and saw the note this time - I totally missed it before. My question is, though, if the attributes are already defined in the schema that the project is using, why doesn't oXygen automatically import them? I assume that oXygen uses whatever schema you have specified, not just the default DITA schema. So if the attribute is defined there, I shouldn't have to define it again inside the development environment. That opens up opportunities for mistyping and forgetting items.

Isn't that what what having a schema is for?

[Radu]

Hi Neil,

There is no project-level defined schema. Each XML topic references its own schema.
For example a DITA XML topic usually has the DOCTYPE declaration:

Code: Select all

<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">

Usually an XML editor (Oxygen including) takes the value of the PUBLIC ID -//OASIS//DTD DITA Topic//EN and finds an XML catalog which maps this value to a DTD. By default the XML catalog is this one:

OXYGEN_INSTALL_DIR\frameworks\dita\DITA-OT\catalog-dita.xml

which maps the value to the DTD located in:

OXYGEN_INSTALL_DIR\frameworks\dita\DITA-OT\dtd\technicalContent\dtd\topic.dtd

A DITA concept has another public ID value in its DOCTYPE declaration which maps it to another DTD.
And so on, each DITA topic type and map type has another DTD which will be used for validation, content completion and publishing.

So even with the default behavior there are a bunch of top-level DTDs which provide support for editing all topics within a DITA project.
But this is the default behavior, users can create their own DITA specializations (some which might have extra specialization attributes) and provide catalog files and DTDs for them. The DTDs do not have to be all in one particular place on the local hard drive.
The rules with XML editors is that there are no rules. There is a maximum of flexibility which leads to problems like the one you encountered.

Regards,
Radu