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.

[mbakeranalecta]

One more thought occurs to me. Based on the use cases I am aware of, there does not seem to be a real need for the "other" section or the New button on the colors and styles page, because you could always add other attributes on the profiling/conditional text page, which would add them to the colors and styles page automatically.

Or is there a use case I am missing?

[raducoravu]

Mark, you got everything about right.

Please see some more answers/details below:

If it can be pre-populated in this list, why can't it be pre-populated in the main colors and styles table?

A Preferences page can contain either global settings or settings loaded from the current project. The Subject Scheme Information is very volatile, for example by default it depends on the current map opened and selected in the DITA Maps Manager. If you select another DITA Map in the DITA Maps Manager, it can refer to another Subject Scheme map and you get another set of profiling attributes and values which can be applied on the edited topics. So this is why we cannot take the information we obtain from the current detected Subject Scheme map and bring it to the Preferences dialog.

I intended this feature of obtaining controlled profiling attributes and values from the Subject Scheme Map as a feature which can perfectly replace the settings globally defined in the "Profiling/Conditional Text" preferences page in the "Profiling Attributes" list. So if you as a user define such a Subject Scheme map for your DITA project and share it with the others, nobody will ever need to make a change to the "Profiling/Conditional Text" preferences page in the "Profiling Attributes" list. Unfortunately the Subject Scheme information cannot: 1) Define profiling condition sets. 2) Define styles for each profiling attribute value.

So for these the user needs to edit the corresponding preferences pages.

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

When you add a new style mapping (Document Type, attribute name, attribute value triplet) in the Other section of the " Colors and Styles" preferences page it usually is added because the user has a Subject Scheme map and because of this he did not make changes to the "Profiling/Conditional Text->Profiling Attributes" list. So those entered attribute names and values will not be defined in the parent page.

  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. 

For our user manual, the "Profiling/Conditional Text" preferences page is also saved at project level with the same values which are defined in the Subject Scheme Map. It is redundant but it was probably done so that in the "Colors and Styles" Preferences the values would appear on the spot. In such cases the "Edit Profiling Attributes" will always prefer the Subject Scheme Map.

  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. 

Yes.

  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. 

For the "Profiling/Conditional Text" page the list of Profiling Attributes and values will be detected from the DITAVAL (without being self-synchronized with the DITAVAL changes). The list of Profiling Condition Sets will also be updated to define condition sets for each DITAVAL. Each condition set points to the DITAVAL file location, so in this case the change in the DITAVAL is enough to modify the condition set.

  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.    

We have an opened issue that a document type configuration should be able to come with a predefined list of profiling attributes, sets and styles. So maybe in the future, when you will edit a document type located in the "Document Type Association" preferences page, you will have these two additional pages there. This would be better than the current approach but sometimes a framework configuration bundled with Oxygen cannot be directly edited because it is usually saved in places like "OXYGEN_INSTALL_DIR\frameworks\dita\dita.framework" and on Windows such files cannot be modified by regular users. Again, another problem is that when the document type comes with certain profiling options and the global configuration has others we would need to define a protocol of merging these.

  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. 

As far as I know the main idea is that a preferences page should not influence another preferences page. It's like your changing some setting in one page and another page which you cannot see is also changed. We also wanted to split the "Colors and Styles" in a separate page because we considered that maybe the styling colors are more of an user-specific option and its parent page contains more group-specific options which should remain fixed in the workgroup.

  One more thought occurs to me. Based on the use cases I am aware of, there does not seem to be a real need for the "other" section or the New button on the colors and styles page, because you could always add other attributes on the profiling/conditional text page, which would add them to the colors and styles page automatically. 

Indeed you could also add the attributes defined in the Subject Scheme in the "Profiling/Conditional Text" page. It's kind of redundant but it achieves the same purpose.

[mbakeranalecta]

I certainly understand the problem with the volatility of subject schema maps. The problem, of course, is that the user will still want to style them, and currently the feature to do that is both hard to find, hard to understand, and hard to use -- particularly because the interface ties it to a function that is being silently ignored when a subject schema map is present.

Unfortunately the Subject Scheme information cannot: 1) Define profiling condition sets. 2) Define styles for each profiling attribute value.

So for these the user needs to edit the corresponding preferences pages.

But the same volatility problem applies here as it does for the definition of the values themselves. This makes things very confusing, because on Profiling/Conditional Text->Profiling Attributes" you have a list of profiling attributes at the top that is being ignored, and a list of profiling condition sets at the bottom that is being used. I would recommend moving the profiling condition sets onto a separate preferences page to reduce the confusion here.

You could then put a label on the Profiling/Conditional Text->Profiling Attributes page that clearly says, "Profiling attributes defined here are ignored when a DITA Subject Schema map is present in the active DITA map."

As far as I know the main idea is that a preferences page should not influence another preferences page. It's like your changing some setting in one page and another page which you cannot see is also changed.

Yes, but in fact that is exactly what happens now, because if you add an attribute on the Profiling Attributes page, it is immediately added to the list on the Colors and Styles page.

Perhaps the thing to do would be to break that connection so that nothing is added to the colors and styles page by default. Then add three import buttons to that page:

• Import from Profiling Attributes
• Import from DITAVAL file
• Import from Subject Schema

In effect, this makes all the definitions "other" in the sense that the settings are not synchronized with profiling attributes defined anywhere else. This could be an advantage, since currently if you remove a profiling attribute, its corresponding colors and styles definition gets deleted (and has to be created again from scratch if you put it back). Having colors and styles defined for attributes that are not currently active does no harm.

This would get rid of the need for a New button and give you a single consistent list that is easier to understand.

sometimes a framework configuration bundled with Oxygen cannot be directly edited because it is usually saved in places like "OXYGEN_INSTALL_DIR\frameworks\dita\dita.framework" and on Windows such files cannot be modified by regular users.

Have you given any thought to installing frameworks in the user's home directory by default rather than the install directory? Or maybe mirroring the framework structure in both places so that any modifications the user makes to the framework are stored in the home directory (which is read first). That way modifications could be made without creating a complete copy of the original framework, and could be preserved across upgrades. Essentially this would mean storing deltas to the defaults the way you do with preferences.

[georgebina]

Hi Mark,

I think the best way to see these is that the options provide some defaults. If the root DITA map (the map that provides the editing context for topics) specifies values for profiling attributes with a subject scheme map then oXygen will use those instead of what is specified in the options. There is a similar situation with a default schema that can be specified at the framework level, but oXygen will use the schema specified in the document instead, if a reference to a DTD or schema is present in the document.

Best Regards, George

[mbakeranalecta]

Okay, I can describe it that way.