Details
-
Improvement
-
Resolution: Unresolved
-
Major
-
None
-
17.10.14, 18.8.0
-
None
-
Unknown
-
Description
The names and descriptions of the macros that show content coming from elsewhere, and of their parameters, are what the Insert Macro and Edit Macro dialogs show to explain them. Several repeat the macro name or use developer terms, so a user cannot tell the macros apart or what to type in a field.
The macros to change, with the file where most of the fix is done:
- include: defined in IncludeMacro.java, descriptions in ApplicationResources.properties.
- display: defined in DisplayMacro.java, descriptions in ApplicationResources.properties.
- context: defined in ContextMacro.java, descriptions in ApplicationResources.properties.
- template: defined in TemplateMacro.java, descriptions in ApplicationResources.properties.
- uiextension: defined in UIExtensionMacro.java, descriptions in ApplicationResources.properties.
- uiextensions: defined in UIExtensionsMacro.java, descriptions in ApplicationResources.properties.
The main problems:
- Display and Include have nearly the same description, so a user cannot tell which one to pick.
- The descriptions of template, uiextension and uiextensions repeat the name, like "Insert a template.", in English, French and German.
- The section parameter of display and include does not give the format of a section id, like HMySection.
- Developer terms are shown as is: "the passed page" and TransformationContext for context, ExtensionPoint for uiextensions.
KOs covered
| Macro | Criterion | Parameters | Problem |
|---|---|---|---|
| context | D1 wording | It is a developer macro, since its only category is Development, but "Context" is generic and does not say what the macro does: it runs its content as if another page were the current one. The documentation describes it as "Executes content with another document set as the current document", which is clearer than the name, like the generic name of the Display macro. | |
| context | D2 summary | The description "Executes content in the context of the passed page." repeats the name, "Context", and only adds "the passed page", which is a programming term. The first sentence of the documentation, "Executes content with another document set as the current document", says more. The Include and Display macros have a description that says what they add to the page. | |
| context | C1 clarity | document | The description "The reference to the page the content will be executed in." does not say what an empty value does, although both calls of the XWiki sources outside the tests leave it empty and keep the current page, like {{context restricted="true" source="script:tip"/}}. |
| context | C1 clarity | source | The description "the reference of the content to insert (e.g. string:*bold*, script:myvariable)" gives two examples of the "type:value" syntax but does not list the other types, and does not say that the source replaces the content. The error "Unsupported source type [foo]" is the only way to learn the other types. The French name and description are left in English, a translation matter. |
| context | C1 clarity | transformationContext | The dialog shows the name "TransformationContext" in camel case, and the description "The Transformation Context mode to use. Valid values are "current", "document" and "transformations"" repeats the name and lists the values without saying what each one does, or which one to pick: the three modes change which XDOM the macros inside the content see, and "transformations" executes the macros of the other page. |
| display | D1 wording | The Quick Actions entry and the dialog title are only "Display", a generic verb that does not say what is displayed, while the documentation shows one use, displaying another page; include, the same kind of macro, has the entry "Include Page". Type "display" in the Quick Actions menu: the entry "Display" comes between Icon, Footnote and Live Data entries, with nothing telling that it shows a page. | |
| display | D2 summary | The description "Display other pages into the current page." is the same sentence as the include macro, "Include other pages into the current page.", and does not say what makes display different, that the page is rendered in its own context. A user choosing between the two cannot tell them apart. | |
| display | C1 clarity | page | Hidden, but shown when the macro already sets it, like {{display page="Sandbox/TestPage1"/}}. The Edit Macro dialog of that macro then shows two alternatives, "Select parameter Resource" with a Page field and "Select parameter page" with another Page field, both with the description "The reference of the page to display.", with no way to tell them apart. |
| display | C1 clarity | section | The description "An optional id of a section to include in the specified page." uses "include", the term of the other macro, and does not say that the id is "H" followed by the heading title without spaces, like HMyHeading, so the user cannot guess what to type. The descriptor annotation gives the hint "e.g. 'HMyHeading'", but the translation that replaces it drops it. |
| include | D2 summary | The description "Include other pages into the current page." says what the macro adds, but it is the same sentence as the Display macro, "Display other pages into the current page.", so it does not tell a user which of the two to pick. | |
| include | C1 clarity | author | The name is shown as "Author." with a trailing period, and the description "The author to use to execute the content when context is "Current"." refers to the context parameter, which is deprecated and hidden from the dialog, and does not explain the values Auto, Current and Target or that they decide the rights the included content runs with. |
| include | C1 clarity | page | Hidden, but shown when the macro already sets it, like the first example of the documentation, {{include page="Sandbox/TestPage1"/}}. The Edit Macro dialog of that macro then shows two alternatives named "Page" with the same description "The reference of the page to include.", page and reference, with no way to tell them apart. |
| include | C1 clarity | section | The description "An optional id of a section to include in the specified page." does not say that the id is "H" followed by the heading title without spaces, like HMySection, so the user cannot guess what to type. The German description explains it. |
| template | D2 summary | "Insert a template." repeats the name and does not say what the macro adds to the page: the output of the Velocity template of the given name, found in the skin or in the files of XWiki, rendered where the macro is. The French and German descriptions repeat the name the same way, "Insérer un template." and "Eine Vorlage einfügen.". | |
| template | C1 clarity | name | The label "Name" and the description "The name of the template" repeat each other and do not say what a template name is: the file name of a Velocity template, like pdftoc.vm, looked up in the skin, in the templates folder of the WAR and in the JARs, with its extension. The description gives no possible value for a free field. Open the Edit Macro dialog of {{template name="pdftoc.vm"/}}. |
| uiextension | D2 summary | "Insert a UI extension." repeats the name and does not say what the macro adds to the page: the output of the UI extension registered under the given identifier, rendered where the macro is. The French and German descriptions repeat the name the same way. | |
| uiextensions | D2 summary | "Insert UI extensions." repeats the name and does not say what the macro adds to the page: the output of every UI extension registered on the given extension point, rendered where the macro is. The French and German descriptions repeat the name the same way. | |
| uiextensions | C1 clarity | extensionPoint | The dialog shows the label "ExtensionPoint", the ID written in camel case, because the English translation of the name is the ID itself, while French and German have "point d'extension" and "Erweiterungspunkt". |
Impact found on macro fluidity
These 18 KOs come from the WYSIWYG usability audit of the macros, under the criteria C1 clarity, D1 wording, D2 summary of its usability criteria. The page of each macro, linked in the table, has the full notes and the steps to reproduce. Fixing them means changing the translations of the macros and, for a name or a category, their definitions.