Problem/Motivation
From #2810871: Explain fields configuration and private discussion with @miro_dietiker, we still need to improve some wording for the Diff settings UI.
Text/UI wording is never easy to define, thus we need to discuss properly to give to the user better/short/clean/concise descriptions.
From the parent issue (comment #21):
1.
Yeah, these "per category settings details-wrappings" could be easier for the end user/self-explaining, but then for the visual_inline_theme aren't the label "VISUAL INLINE LAYOUT SETTINGS" and the description "Theme used for Visual inline layout when comparing revisions." too much/repetitive ?
Not sure, but imo, if we would keep it like this, I'd suggest removing the description (or at least saying something more "useful", like the Leading/Trailing examples ?)
2.
About "Leading context lines", "Trailing context lines" and their descriptions, not sure which better wording we can use to not repeat things. Maybe just "Leading" and "Trailing" as select labels and keep the descriptions (?)
3.
More:+++ b/diff.module @@ -78,11 +78,14 @@ function diff_help($route_name, RouteMatchInterface $route_match) { + return '<p>' . t('This table provides a summary of the field support found on the system. For every field a diff plugin can be selected and configured. This settings are applied to Unified and Split fields layouts.') . '</p>';As you said once "We want to avoid the diff word in the UI" (comment #15.2), how can we change this "For every field, a diff plugin can be selected and configured." ?
Also imo this new help text is too long, but if it is fine, then: "This" --> "These".
+++ b/src/Form/GeneralSettingsForm.php @@ -98,11 +82,12 @@ class GeneralSettingsForm extends ConfigFormBase { +Unnecessary new line.
+++ b/src/Plugin/diff/Layout/VisualInlineDiffLayout.php @@ -25,6 +25,7 @@ use Symfony\Component\HttpFoundation\RequestStack; + * description = @Translation("Visual layout, revision comparison is made as the content is rendered for the user."),Not sure what you mean by "made as the content is rendered for the user".
Private chat:
[...]
the (visual inline) plugin triggers an entity view / rendering.
instead of field based view / rendering / value comparision.
The user usually doesn't know the term rendering though.
Dunno, it's an admin screen, so we might be fine to use those terms.
It might be healthy to do it there. We found the word "Visual inline" for the end user, but in the plugin description, it's the time to explain what it means..
I was even thinking about removing "Inline" from the plugin label because "Visual" might be clear enough.
Proposed resolution
- discuss about the best wording to display to the end user/site builder
- upload the patch
- review
Remaining tasks
User interface changes
Improved some wording in /admin/config/content/diff/general and /admin/config/content/diff/fields
Before:

After:

API changes
Data model changes
| Comment | File | Size | Author |
|---|---|---|---|
| #11 | diff_2817159_settings_11.interdiff.txt | 2.78 KB | miro_dietiker |
| #11 | diff_2817159_settings_11.patch | 8.67 KB | miro_dietiker |
| #9 | provide_better_description_wordings-2817159-9.patch | 6.73 KB | tduong |
| #9 | interdiff-2817159-7-9.txt | 230 bytes | tduong |
| #7 | provide_better_description_wordings-2817159-7.patch | 7.07 KB | tduong |
Comments
Comment #2
tduong commentedProvided some suggestions for most of the points mentioned in the IS, but still the diff word is present in the field_list and I've just noticed also the general_settings help texts. Still needs discussion.
About the Visual layout settings detail form, I've tried to use an ajax to display the selected theme description, but somehow when I switch to admin the description is not changed, I guess I'm missing something. Any suggestions how to fix it? Do you approve it?
I've provided a description for the Visual plugin, hope this makes sense. I've seen that entity type is also used in the diff.field_list page, and view mode is also used in the entity type edit page, so I thought these words are fine for the end user (?)
If we decide to actually remove "inline" from the "Visual inline" plugin label, this needs more work (find where visual_inline is used and replace it with jsut visual, ...)
Comment #3
tduong commentedShortly discussed with @Berdir about the Visual layout settings form, and a static description which explains what happens when one or the other option is selected is better than what I've tried to do. Reverted ajax and themeHandler changes and provided a static description.
Comment #4
johnchqueNot really sure about this change, then the option label should be also "Default"?
Comment #6
johnchqueUnrelated change. Will be fixed in #2817185: Fix test fail in HEAD
Comment #7
tduong commentedTrue, I needed it before to avoid adding more checks just to change from standard to default and get the related description.
Reverted it.
What about the other touched wordings ?
Comment #8
johnchquethen this change is not needed either. :)
we want to be consistent here, let's use standard here too then.
Besides that looks good.
Comment #9
tduong commentedLeftover fixed. Thanks :)
About the second one, I think that it's fine because the theme actually is called default. "Standard" was a hardcode "label" suggested once by @Berdir for an issue (#2799597: Select theme for diff display, comment #24.2).
Comment #10
miro_dietikerIMHO we should list them with their name. It's not an implicit assignment. It's an
admin/appearance clearly talks of default and admin theme. It doesn't use the term "standard" so we should stay with "default".
Comment #11
miro_dietikerRenaming the settings default.
Comment #13
miro_dietikerCommitted. :-)
Comment #14
tduong commentedGood point :)
What about renaming "Visual inline" in just "Visual" topic ?
Comment #15
johnchqueI would vote for keeping it as "Visual Inline".
Comment #16
miro_dietikerIf you want to discuss this, open a new issue. :-)
Comment #17
tduong commentedNew discussion opened: #2818233: Discuss about "Visual inline"/"Visual" plugin label :P