Profiling/conditional text configuration

[mbakeranalecta]

A few questions/issue with this.

1. In the interface, it says "Note: The attribute must already be defined in the DTD or in the associated schema before referring it here." The docs say "To ensure the validity of the document, the attribute must be already defined in the document DTD or schema before referring it here."

I'm not entirely sure what that means. My guess is that it means that Oxygen does not check to see if the attribute you define here actually occurs in your schema. It just inserts it. (It will, of course, report a validation error on the result.) If so, both the interface and the docs could make this much clearer by saying something like:

"Only define profiling attributes here that actually exist in your schema. This feature does not add profiling support to XML vocabularies that do not have it already."

(The second sentence is addressing what I'm guessing was the misunderstanding that led to these warnings being inserted in the first place.)

Of course, if this is not what it means, then it should say something else.

1. A common language issue regarding "referring". Usage of these terms can be tricky in English, but in this case, the correct usage is "referring to". This, and saying "referred" where "referenced" would be the correct usage, are common issues in the docs.
2. If my assumption about 1 is correct, then it seems like there is another restriction that should be mentioned here. This facility should only be used for languages where profiling attributes are allowed on every element. Oxygen will not check if the attribute is allowed on a particular element and only allow you to profile elements where it is allowed. (I assume this, since there is no way to restrict the attribute to a particular XPath.) Correct?
3. What happens if the values of the profiling attribute are defined in the schema, or, in DITA's case, in the subject schema? Will Oxygen pick up those value automatically, or do you have to duplicate them here? Will it allow you to insert values defined here even if they are not defined in the schema?

[raducoravu]

"Only define profiling attributes here that actually exist in your schema. This feature does not add profiling support to XML vocabularies that do not have it already."
(The second sentence is addressing what I'm guessing was the misunderstanding that led to these warnings being inserted in the first place.)

You understood perfectly, we had novice users adding in the Preferences page for DITA for example a non-existing profiling attribute called "version" and then complain that it is marked as an error in the topic after they apply the attribute to an element. So the profiling attributes described here need to be a subset of the profiling attributes allowed by the vocabulary. Your suggestion for the message is very good, I will add an issue to change the current message. My only complaint is that when translated to languages like German such a message might be very long and cover a large part of the dialog where is appears. Maybe we could only add the first sentence to the dialog with a "More details" link which shows a dialog with a complete description. So what's your take on this?

Funny thing is that we also had users define such a profiling attribute entry in the Preferences for attributes which belong to the DITA vocabulary but are not profiling attributes like for example "outputclass". They knew they could not filter content based on it. But what they actually wanted was an easy way to edit the attribute using the "Edit Profiling Attributes" dialog which is more user-friendly than the Attributes view.

Of course, if this is not what it means, then it should say something else.
A common language issue regarding "referring". Usage of these terms can be tricky in English, but in this case, the correct usage is "referring to". This, and saying "referred" where "referenced" would be the correct usage, are common issues in the docs.

I understand.

If my assumption about 1 is correct, then it seems like there is another restriction that should be mentioned here. This facility should only be used for languages where profiling attributes are allowed on every element. Oxygen will not check if the attribute is allowed on a particular element and only allow you to profile elements where it is allowed. (I assume this, since there is no way to restrict the attribute to a particular XPath.) Correct?

Yes, when the user shows the "Edit Profiling Attributes" dialog for a certain element right now we do not check if that element allows on it the profiling attributes that the dialog can set. We have the means to check this but we do not do this, it might get complicated when the user selects multiple elements and decides to set common profiling attributes on all of them.
For example the DITA title element does not allow profiling attributes on it but users can still add them using "Edit Profiling Attributes" and afterwards receive a validation error in the editor if they do.

What happens if the values of the profiling attribute are defined in the schema, or, in DITA's case, in the subject schema? Will Oxygen pick up those value automatically, or do you have to duplicate them here? Will it allow you to insert values defined here even if they are not defined in the schema?

The DITA Subject Scheme Map defined in the root map always takes priority to impose profiling attribute names and values. So if it exists it overwrites everything in the Oxygen Profiling Preferences. As you saw our User's Manual has a Subject Scheme Map defining values for "product" and those values are used when the user is edited the attribute either in the Attributes view or in the "Edit Profiling Attributes" dialog.

[mbakeranalecta]

I agree on using just the first sentence with a link to more. I actually structured the two sentences with the idea in mind that the UI might only have room for the first one. I think some users will get it from the first sentence, while others will need the second (and some will need still more). Unfortunately, there are some ideas that are just too complex, or too contrary to the user's expectations, to be fully explained in the interface. Understanding where the boundaries are between DITA markup, DITA processing, and an Editors interface capabilities is really hard, especially for people who are used to an all-in-one application like Word or FrameMaker.

I get people wanting an easier way to enter attributes. I have often wished that the attributes dialog would pop up more like the attributes view. I really want to be able to see at a glance what attributes are available, which are required, which have values already, and I want to be able to add and edit them without having to use the mouse. Forms provide the most general solution to this, but it would be nice to have something more generic as well.

I'll document the other information in the config topic.

[mbakeranalecta]

On further experimentation, in 16.1 I find the following:

• In DITA, at least, Oxygen will not display colors and styles for non-DITA profiling element, even if they are defined here.
• There is no way to edit or delete a custom style once you have defined it. If you create a new style "foo" with a value "bar" and then hit the edit button to edit it, you can edit the colors, but not the doctype, attribute name, or value. There is also no way to delete the individual entry. The only way to get rid of custom entries is to hit Restore Defaults, which wipes out everything.

Given this, it actually seems impractical to develop your own styles and colors. All you can really do effectively is change the colors applies to the defaults or those loaded via a DITAVAL file. Perhaps the New button should go away until there is full functionality to add, edit, and display custom colors and styles?

[raducoravu]

One observation about your changes to the user's manual:

 The DITA Subject Scheme Map defined in the root map of your document will be used in place of anything defined using this dialog.

We have to keep in mind that Oxygen can be used to edit multiple XML vocabularies, some of the users using the preferences page or reading the user guide do not know what DITA is. Maybe the phrase could be something like "If you are using the DITA XML vocabulary, the DITA Subject Scheme...."

[mbakeranalecta]

Right. I will amend accordingly.

Any thoughts on the difficulties of actually creating colors and styles for other attributes?

[raducoravu]

I will start fresh, we had an internal talk about this this morning. I think I said something stupid earlier about the Subject Scheme being used to control the styling in the "Colors and Styles" page.

So the thread is about the Oxygen Preferences->"Editor / Edit modes / Author / Profiling/Conditional Text / Colors and Styles" page which can be used to assign various font variants and colors to elements which have certain profiling attributes with a certain value.

This particular page has a tree table with two categories: "Defined attribute values" and "Other".
The entries in the "Defined attribute values" section are automatically synchronized with the profiling attributes and values defined in the parent preferences page "Profiling/Conditional Text". So they cannot be removed from the list, they can only be reset to render nothing for the specific value. When modifications are made in the "Profiling/Conditional Text" page, this category gets synchronized with them.

Then we have the "Other" section. This section serves the following purposes:

1. If an opened DITA Map has a Subject Scheme Map attached, the profiling attributes and values will be taken from it, bypassing completely the "Profiling/Conditional Text" preferences. If you want to style a certain attribute value coming from the Subject Scheme Map in this case you will need to use the "New" button in the add "Colors and Styles" and add a new entry.

I added a bug and we will work to also add a "Delete" button to the "New/Edit/Clear Style" buttons group allowing you to delete this extra entry. The "Delete" button will be disabled when you select entries from the first category.

2. It is possible that somebody saved these "Colors and Styles" settings at Project Level and then gives his project to somebody else to load. That user who loads the project containing the options does not have matching entries in the "Profiling/Conditional Text" page so the preferences saved in the project will appear in the "Other" section.

[mbakeranalecta]

Thanks,

I think I was getting confused between the two dialogs myself. I'll go back and review everything about both of them and bring it up to date with the information you have provided.

[mbakeranalecta]

Okay, I was definitely getting confused between the two dialogs. I'm not sure if that is a result of working on them separately or if there is an inherent confusion here. I think maybe the New button on the colors and styles page is confusing, as it suggests that you can add a new attribute/value pair here when really you can't.

However, I am finding the whole setting really confusing now. Here is what I have tried:

I went into the subject schema and added an new value for product:

          <subjectdef keys="editorWombats">
            <topicmeta>
              <navtitle>Wombat Editor</navtitle>
            </topicmeta>
          </subjectdef>

When I do this, the new value shows up in the Edit Profiling Attributes dialog:

But it does not show up in the Conditional text settings:

That, by itself is confusing.

Then I tried adding a value through the conditional text settings:

This value immediately shows up in the colors and styles list and I can add a style for it (but the wombatEditor value does not show up and I can't style it):

This value will not show up in Edit Profiling Attributes dialog, and it will raise an validation error if you enter it by hand. However, the defined style will be applied to it:

It is obvious enough why if you understand how validation works, but this will be really confusing to someone who comes from a FrameMaker or Word background.

Then, based on the information above, I want into the colors and styles dialog and hit New. When I started to create a new entry, I found that the new value I introduced in the subject schema was pre-populated in the list:

This raises two questions:

1. If it can be pre-populated in this list, why can't it be pre-populated in the main colors and styles table?
2. Why are the Document type, Attribute name, and Attribute value fields combo boxes (also accepting freeform text) rather than drop down lists (restricted to known entries). There does not seem to be a use case for freeform entry here. (Then again, if there is no case for freeform entry, there is no case for this not being just a table of known entries.)

But I also have a larger question.

The profiling/conditional text preferences page in the userGuide project is populated with the values of the product variable, but it seems like this is incidental to the fact that the same values are defined in the subject schema. So Oxygen is not really using these values to do profiling in the editor. Maybe the only reason they are the same is that they were imported from the DITAVal files or entered by hand at some point.

In effect, as you said, they are being ignored in the presence of the subject schema.

But really, they are not. They are not being ignored, because the colors and styles settings are based on these values, not on the subject schema values. So when Author applies profiling to an element, it is drawing the list of legal values from the subject schema and the list of colors and styles from what is defined in the dialog, even though it is just coincidence that the names are the same.

If you wanted to have the color and style definitions match those in the subject schema, you would have to do through the "other" list.

If I've got this right, it is going to be pretty hard to explain.

Basically, it seems to me that in the presence of a subject schema file, these dialogs should be populated from the subject schema file and the add/edit/delete buttons should be disabled.

I'm also not entirely sure about what the "Import from DITAVAL" button does. Does it do a one time import from a DITAVAL file, or does it create a connection to the DITAVAL file so that if the DITAVAL file changed, the list here would change automatically. I suspect the former, but that is inconsistent with how the subject schema influences the Edit Profiling Attributes dialog.

[mbakeranalecta]

One other thought. Should this setting perhaps be a doctype specific setting (under Document Type Associations) rather than a global setting? The settings are all doctype specific.

[mbakeranalecta]

Just realized that there is an Import from DITAVAL button in the same position on both pages. I think this may have contributed to my getting confused between the two pages. It seems odd that you would have to do the import twice. If you are importing from a DITAVAL file that defines colors and styles, why not do that in one step? This would not prevent the user from redefining the styles for themselves.