Oxygen XML Forum

Author mode uses CSS to display parentheses before and after <indexterm> content. (Oxygen XML Author 17.1.)

I'm sure I'll get over it, but I find this behavior disconcerting to the point of being annoying, especially since those CSS-injected parentheses have exactly the same display attributes as the actual, editable content:
For now, I've commented out the display and content properties in the offending CSS:
in

author\frameworks\dita\css\core\-topic-metadata-indexterm.css

Why are these parentheses in Author mode a good idea?

If the answer is related to nesting of indexterm elements, then I'd prefer to see that nesting represented in Author mode by a combination of line break and indent.

Why is it a good idea to display those parentheses in a way that makes them visually indistinguishable from the editable content?

Finally, it occurs to me that this behavior - this CSS - might not be native to Oxygen; it might be a customization. The Oxygen XML Author installation that I am using has been customized to work with third-party software; this might be one of those customizations, so, with apologies, I might be raising this issue in the wrong place, with the wrong people.

Hi Graham,

Indeed the default way in which the CSS-based Author visual editing mode in Oxygen renders indexterms is the one you specified.
I guess we somehow wanted to suggest that you are using metadata which is not part of the actual published content.
I added an issue on our side to reconsider this decision. If you have a suggestion about how we could better style index terms, it is as always welcomed. We did not want to add line breaks because index terms may also appear in paragraphs and we did not want to break the flow of the paragraph.
Are you usually defining index terms only in the prolog metadata section or also in paragraphs?

Regards,
Radu

Hi Radu,

Are you usually defining index terms only in the prolog metadata section or also in paragraphs?

Usually only in the topic prolog. Occasionally in the topic content, such as paragraphs. Not yet in maps, although that might happen in the future.

We did not want to add line breaks because index terms may also appear in paragraphs and we did not want to break the flow of the paragraph

Good point. I'd forgotten about that, because I so rarely do that these days (in DITA; I did that more often in earlier markup languages). Thanks for reminding me.

The "third-party-specific" DITA style guide that I am required to follow (hint: transpose each letter of "HAL" forward one position in the alphabet) recommends placing "in content" indexterm elements at the beginning of an element. So, in the context of that style guide, breaking the flow of a paragraph might actually be a good thing, to highlight (what that style guide describes as) the bad practice of inserting index terms in the middle of a sentence.

If you have a suggestion about how we could better style index terms

In Author mode, I would prefer index terms to be separated from the "inline" content (such as paragraph text) by vertical white space, with nested index terms indented under their parents. Perhaps even with a different background color*. For me, that separation would improve the readability of the content in Author mode. I'd suggest replacement CSS, but I need to get back to other work (perhaps I'll get time later).

* While I'm here, although this deserves its own thread: I would prefer the default background color for topic content in Author mode to be white; or at least, closer to white than the current gray, which still (perhaps I'll get over it) sends me the bordering-on-subliminal message that the content is somehow "selected" (even though, consciously, I know it isn't).

If you don't like the idea of index terms introducing vertical space, then please consider revisiting those CSS-injected parentheses; at least, change their display attributes so that they are clearly distinguishable from editable content. The following rule should apply to all CSS-injected content in Author mode: it should be visually distinct from editable content (for example, it should be displayed in a different color).

Suggestion (although I'd still prefer line breaks and indenting): instead of wrapping index terms with parentheses, insert a separator before each nested index term; a glyph that does not typically appear in content - for example, a right-pointing triangle - with different display attributes (such as color) to further distinguish it from the editable content. I'm aware that indexterm elements can be nested in the middle of the content of another indexterm element, so you might argue that nested indexterm elements should be wrapped (delimited before and after), but I consider that bad practice. I place nested indexterm elements at the end of the parent indexterm. I'm curious whether there are any use cases where nesting an indexterm in the middle of the content of another indexterm is a good idea. I suspect that this is only allowed - only valid - because of the difficulty (in cases, impossibility) of expressing certain constraints in particular schema languages.

metadata which is not part of the actual published content.

Call me a pedant, but I question your use of the word "published" here. If I flip to the back of a PDF generated from this DITA, I see those index terms. In my book , that's "published".

Regards,
Graham

Hi Graham,

Thanks for the indexterm ideas, I added them to the opened issue.
About this remark:

* While I'm here, although this deserves its own thread: I would prefer the default background color for topic content in Author mode to be white; or at least, closer to white than the current gray, which still (perhaps I'll get over it) sends me the bordering-on-subliminal message that the content is somehow "selected" (even though, consciously, I know it isn't).

So by default when you are editing a DITA topic Oxygen should show it in a page-like layout where the internal part of the page is white and the outer part of the page is a light gray. Do you have the same rendering on your side?
On the toolbar there should be a Styles drop down on which you can select the Full width style to remove the outer edge completely.

Regards,
Radu

Hi Radu,

Do you have the same rendering on your side?

No. I am currently editing a DITA reference topic. The internal part of the page is gray, rgb(251, 251, 251).

I suspect I am experiencing behavior caused by a "third-party" customization; or, perhaps, your customization on behalf of that third party.

Using the Oxygen CSS Inspector (nice touch, I like it), I can see that ibm-topic.css (okay, the secret's out ) contains the rule:
which means that the background color is inherited from this rule in -page.css:
as opposed to the following rule (which is shown striked-out in the Oxygen CSS Inspector) in -page.css:
I haven't yet tried to tweak this CSS to get a white background. The gray background irks me, but I need to press on with actually editing content.

Are you (Syncro Soft; Oxygen; Radu) responsible for ibm-topic.css (for example, did you create/tweak it on IBM's behalf), or should I talk to someone else about this customization? (I have a contact for that.)

On the toolbar there should be a Styles drop down on which you can select the Full width style to remove the outer edge completely.

The Styles drop down in my installation of Oxygen has clearly been customized, because it lists various IBM-specific options; it does not contain a "Full width" (or similar) option.

What you've told me indicates to me that you might not be responsible for, and don't necessarily get to see, the customizations that I'm seeing in my installation of Oxygen. I know that Oxygen is, deliberately, highly customizable by users. Still, this is interesting (and, to be frank, disappointing) to me: that customizations have been made to the behavior (or appearance; specifically, the white page background) of my installation that, in my opinion, are a retrograde step from the default that you describe (and that I would prefer).

Regards,
Graham

Hi Graham,

So:

Are you (Syncro Soft; Oxygen; Radu) responsible for ibm-topic.css (for example, did you create/tweak it on IBM's behalf), or should I talk to someone else about this customization?

No, we do not do any paid customization work for our clients, we just help them with advice.
Indeed once you set "background-color : inherit" on the topic (which is also the root element), it will overwrite the "background-color : white ;" color set on the root.
Older versions of Oxygen did not have that page-like layout (with white inside the page and gray outside of it) so possible the IBM customization was created for an older version (and it worked properly) but once newer versions of Oxygen (I think Oxygen 17.0 and newer) added by default a page layout the same customization started looking funny. Maybe there is a newer IBM customization available for newer Oxygen versions... I also have some IBM contacts whom I could ask if you want...

Regards,
Radu

Hi Radu,

I also have some IBM contacts whom I could ask if you want...

Yes, please. That's very kind of you, I would appreciate that. I have no influence there (I am not an IBM employee); I do not have direct contact with the person who performs this customization; neither do I have access to the related internal IBM issue reporting system or user forum.

Your input will carry more weight, and you will likely have a more direct contact.

A note of caution, though, on my behalf: while I want to contribute constructively, both for my benefit and for the benefit of other Oxygen users (especially those using the same customizations), I absolutely do not want to be viewed as a troublemaker: not by you, and certainly not by IBM. My livelihood depends on it. Sincerely, without irony: I would far rather live with that gray background and keep my job.

Regards,
Graham

Hi Graham,

No problem, I will not mention your name or this thread post. Also my contacts are great, they are very responsive to suggestions.
Could you upload a screenshot somewhere (or send it to support@oxygenxml.com) with how the default editing environment looks like on your side? I would show them the image as an example.

Regards,
Radu

Hi,

About the background color, here's what my contact from IBM said:

Yes - I recently made that change from light gray to white in our 4.6.24 upcoming release - based on your <oXygen/> XML Author 18.0, build 2016051118 release.
I noticed that something switched the previous white background to light gray.
So I looked for a spit to fix that - finding this rule & overriding it in our "base" topic CSS.

/* page overrides to use full width. Overrides -page.css */
:root{
border: none;
margin-top: 0em;
margin-bottom: 0em;
width: auto;
padding-top:0em;
padding-right:0em;
padding-left:0em;
padding-bottom:0em;
background-color : rgb(255 , 255 , 255) ;
}

from our C:\DITATools\IDWB\author\frameworks\dita\css_classed folder

Regards,
Radu

Nice one, thanks Radu! I'll get that release from my IBM contacts when it's available.