|
| Summary: |
Improve the names, descriptions and categories of the comment, content, footnote, putFootnotes, html, id and toc macros |
| Issue Type: |
 Improvement |
| Affects Versions: |
17.10.14, 18.8.0 |
| Assignee: |
Unassigned |
| Components: |
Rendering |
| Created: |
22/Oct/26 12:10 |
| Priority: |
 Major |
| Reporter: |
Charpentier Lucas |
| Description: |
The names, descriptions and categories of these rendering macros, and of some of their parameters, are what the Insert Macro and Edit Macro dialogs show to explain them. Some names are code identifiers or instructions, several descriptions repeat the name or use a wrong term, and comment is in a category where a user does not look for it. The macros are defined in xwiki-rendering, where their categories are declared, but most translations are in xwiki-platform. The macros to change, with the file where most of the fix is done:
The main problems:
- The names Id and Put Footnotes are a code identifier and an instruction, and Comment is confused with the page comments of XWiki.
- The descriptions of footnote and toc repeat the name, and the descriptions of content and html use wrong terms, execute and XHTML.
- comment is in the Development category, where a user writing a hidden note does not look.
KOs covered
| Macro |
Criterion |
Parameters |
Problem |
| comment |
D1 wording |
|
"Comment" is confused with the page comments of XWiki, which this macro does not add, especially in the Quick Actions menu where users look for a feature by its name. The pretty name should at least be reconsidered, to say that the text is hidden from readers. |
| comment |
D3 category |
|
The macro is in the Development category, like html and velocity. A user writing a hidden note in the page does not look for it there; a note for other editors belongs to the annotations feature instead. The category should at least be reconsidered. |
| comment |
C1 clarity |
$content |
The description "Comments." does not say that the text is hidden from readers and only visible to editors. |
| content |
C1 clarity |
$content |
The description "The content to execute" uses a wrong term: the content is parsed in the syntax given by the syntax parameter and displayed, not executed. The French translation repeats it, "Le contenu à exécuter". |
| content |
C1 clarity |
source |
The description "the reference of the content to insert (e.g. string:*bold*, script:myvariable)" does not say that the source replaces the content of the macro. The descriptor in the source code says it, "instead of the content of the macro", but the translation dropped it. |
| footnote |
D2 summary |
|
"Generates a footnote to display at the end of the page." repeats the name and only adds where the note goes. It does not say what the reader sees where the macro is inserted, a superscript number linking to the note, nor that the notes are listed at the end of the page, or where a {{putFootnotes/}} macro is placed. |
| html |
C1 clarity |
clean |
The description "Indicate if the HTML should be transformed into valid XHTML or not." uses a wrong term: since XWiki 14.1 the cleaning follows the HTML version of the rendering, HTML 5 by default, not XHTML. It also does not say that unchecking it has no effect without script right, see the Security section of the documentation. Shown in the Edit Macro dialog of {{html}}<p>Text</p>{{/html}}. |
| id |
D1 wording |
|
The name "Id" is a code identifier, not the user's word for what the macro adds. The description itself says that "In HTML for example this is called an Anchor", and the French and German names are "Ancre" and "Anker". In English, the Insert Macro dialog and the Quick Actions menu show "Id". |
| id |
D2 summary |
|
"Allows putting a reference/location in a page. In HTML for example this is called an Anchor. It allows pointing to that location, for example in links." is three sentences and 26 words, with technical terms, "reference/location" and "In HTML". It does not say plainly that the macro adds an invisible anchor that links can jump to. |
| id |
C1 clarity |
name |
The description "the identifier string" is technical and does not say what the name is for, the anchor name that a link targets with anchor="...", nor what value is expected, like a single word without spaces. The French "Le texte de l'ancre à insérer" and German "Die sogenannte ID des Ankers" are clearer. |
| putFootnotes |
D1 wording |
|
"Put Footnotes" is the macro ID split into words, an instruction to the macro rather than what it produces: users would look for "Footnotes" or "Footnote list". The French "Afficher les notes de bas de page" and the German "Zeige Fußnoten an" repeat the verb. |
| putFootnotes |
D2 summary |
|
"Displays all the footnotes from the page. If missing, all footnotes are displayed by default at the end of the page." does not say that a page shows only one list of footnotes, the last putFootnotes, nor that the editor already adds one at the end of a page with footnotes. So on a page that has footnotes, an inserted putFootnotes is silently lost: the macro just inserted disappears with no message and the list stays at the end. |
| toc |
D2 summary |
|
The description "Generates a table of contents." repeats the name, and does not say that the macro lists the headings of the page as links to them. |
| toc |
C1 clarity |
start |
The name "Start" does not say that it is the first heading level listed; the description "the minimum section level" does. The French name "niveau de début" is clearer. |
Impact found on macro fluidity These 14 KOs come from the WYSIWYG usability audit of the macros, under the criteria C1 clarity, D1 wording, D2 summary, D3 category 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. |
|
