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