Conform user-interface text to conventions for trailing punctuation

[brainchild0]

Following #2075, which revised grammar, the current request concerns use of punctuation in user strings, so that they follow conventions familiar for graphic interfaces.

Note that this request does include some further revision to grammar (d791e52, d69622d) not included revision to language not included in #2075.

The other changes are the following:

• Remove full stops (.) trailing widget labels (f223088, 4cb011d).
• End with ellipsis ('...') for all menu entries that open windows or other applications (c713a1c, 4cb011d).
• Remove trailing colons (':'), which had appeared in the GitHub section of the image uploader section of the preferences window (c713a1c).

---

• Bug fix?: no
• New feature?: no
• Breaking changes?: no
• Deprecations?: no
• New tests added?: not needed
• Fixed tickets: n/a
• License: MIT

[fxha]

Thanks for your suggestions. All buttons (el-button, button, ...) and entries in help.js shouldn't include ending ellipsis, even if a dialog or URL is opened and we should also keep the ending dots if not followed by :.

[brainchild0]

I can restore the colons in the GitHub window, but then it would be inconsistent with other parts of the application and general conventions. What would be the reason for such a preference?

Keeping full stops in cases only when no colon follows is complicated because the colons are generated by the toolkit, not part of the application string. This observation suggests that the toolkit shares my the assumption that no full stop terminates a widget label, which is usually a word or short phrase rather than a full sentence. Based on the layout specification files, what rule would you suggest to distinguish which strings should end in full stop, and why would you suggest that any should have one?

[brainchild0]

Conventions are mixed for help menus (see below). I'll revert help.js if it is the preference.

---

[fxha]

I can restore the colons in the GitHub window, but then it would be inconsistent with other parts of the application and general conventions. What would be the reason for such a preference?

There are colons because it's listed as text/input, the text refers directly to the text input below like in documents Name: <text field>.

Based on the layout specification files, what rule would you suggest to distinguish which strings should end in full stop, and why would you suggest that any should have one?

All strings that aren't on ranges (range elements) should end with a full stop because we end the phrase. I would say, we could go without if the element is design as <checkbox><text> with an optional description on top.

Conventions are mixed for help menus (see below). I'll revert help.js if it is the preference.

I'm unsure whether we should use ellipses on menu entries or not but we should remove it from buttons. Actually I'm fine with that because it indicate that the entry opens an external dialog, link etc.

[brainchild0]

I see that many applications use colons for the labels, but do so for drop-down menus as well as text boxes. I would suggest keeping this consistent, that is, using them in both cases or neither. (I personally think that colons used in this way are unnecessary and distracting, but convention certainly supports their inclusion.)

Full stops are never used.

Ellipses are sometimes omitted in an application, but most mature, stable, quality applications use them for both menu items and buttons that open new windows. Some but not all application specifically omit them in the help menu.

Presently, the toolkit inserts colons in some cases, whereas in other cases they are given in the application strings. I strongly suggest that in all cases they are either inserted by the toolkit, if at all, or given in the strings. The mixed model is likely to generate confusion, diminish maintainability, and result in bugs.

[brainchild0]

I have restored the colons, which we can keep until we have a clearer convention for when they would be used and what rule the toolkit has in displaying them.

I am reluctant to make the other changes without a more careful review.

[fxha]

I see that many applications use colons for the labels, but do so for drop-down menus as well as text boxes.

That may be true but we are only using colons if there is a value (such the font size) behind it. Then, you could add colons to all strings because it's always followed by a checkbox or other interactive element.

Ellipses are sometimes omitted in an application, but most mature, stable, quality applications use them for both menu items and buttons that open new windows. Some but not all application specifically omit them in the help menu.

I think this is pure preference and, for sure, it makes the menus cleaner and indicate external links. Please readd the ellipsis on menu items but not on buttons, sorry for the inconvenience.

Presently, the toolkit inserts colons in some cases, whereas in other cases they are given in the application strings. I strongly suggest that in all cases they are either inserted by the toolkit, if at all, or given in the strings. The mixed model is likely to generate confusion, diminish maintainability, and result in bugs.

I don't see any problems here as we only insert colons on ranges that indicate a value. We might refactor the range element later and move the colons to the string for better clarity and to be more consistent 👍 Please open an issue or change it on this PR for this if you want.

[brainchild0]

• But no colons for check box labels (which follow the box), but only for drop-down menus and text boxes (which precede the control)...
• So should I keep 8dd5308 or reverse it (again)?
• Regarding ellipses in the dialog boxes, yes, I agree it is preference. It is not wrong to omit them. But I find from inspection of applications on my system that more of the quality applications have them. Choosing to include them may make the application look higher quality and better planned. But I will remove them in this request, as you asked.

[fxha]

Please keep 8dd5308, add colons before drop-down menus (to be consistent with text boxes) and add ellipsis on menu entries (external links or dialog).

Regarding ellipses in the dialog boxes, yes, I agree it is preference. It is not wrong to omit them.

For now, we should keep the buttons without ellipsis. I think it's fine to add ellipses on setting button but then we have to include ellipses on editor buttons as well that look strange to me (e.g. side bar Open Folder).

[brainchild0]

I agree about consistency with dialog boxes versus side bar, but I had added ellipsis in both. See the recent 7935b20, which removes them from both places (after I added them earlier).

The problem with adding colons for text boxes is that the toolkit is currently adding text after the label, which in many cases includes a colon. I can open a ticket to address these questions after this request is merged, but I think what you're asking is outside the scope of this change set.

[fxha]

The problem with adding colons for text boxes is that the toolkit is currently adding text after the label, which in many cases includes a colon.

If you talk about the linked image below, just change {{description}}: to {{description}} from this line and correct all strings on <range elements inside src/renderer/prefComponents. But I agree to create a separate PR for this.

[brainchild0]

The objective of this request is to transition the use of punctuation toward standard uses for user interfaces. It is intended as a natural pairing with #2075 and targeted for the same release.

A fully satisfactory solution would depend on adopting a few clear conventions for the project, and likely making a few design changes to achieve them, including more consistent use of templates in the Vue.js pages. With HTML and style sheets, a range of options, including character styling and positioning, are available, in addition to string templates.

For now, I am hoping to include a clear, simple, safe, regression-free, and well-contained change set in the upcoming release.

Presumably the suggested change to the range template is intended to accompany changes to some but not all of the user strings. Instead, I prefer to find a proper solution after this request would be merged. I am happy to open a ticket at that time for discussion.

A very small change to the template that might be included in this request is represented in 03cfe8a. This change removes the colons from the range labels. Even if the colons are appropriate in the labels, I would not characterize this change as a regression because the colons should separate the labels from the controls, not the parts of the labels from one anther as they currently do.

For now, I suggest the following:

1. Make any combination (all, some or none) of the following changes, as you prefer, to this request:
   • Include 03cfe8a.
   • Reverse c2ab861.
   • Reverse 7935b20 and 13d91ba.
   • Reverse 8dd5308.
2. Merge this request into develop.
3. Merge or rebase into the planned release.

[brainchild0]

I created an example of how to improve the templates in preferences box. (See screen captures and change set.)

Hopefully we can just push in this change set and then resolve how to proceed.

[fxha]

Please add ellipsis in help menu like in c2ab861 and include 03cfe8a if you want. Then, I can merge the PR later and release v0.16.2.

[brainchild0]

I'm not excited about any template changes in this change set. I have restored the ellipses in the help menu.

Please merge as soon as the tests pass, and you are able to do so.