| Source | What it gives | Used for | Where |
|---|
| Documentation | Parameters, default values and examples, including the most common example | L2, L3, and the criteria measured with the most common example | Not recorded yet: search extensions.xwiki.org |
| Source code | How the macro declares its parameters and content: types, groups, features, advanced and hidden flags, constraints, content type, inline support | C4, C5, C7, C8, C9, C13, E4, E6 | https://github.com/xwiki/xwiki-platform/blob/xwiki-platform-18.8.0/xwiki-platform-core/xwiki-platform-help/xwiki-platform-help-ui/src/main/resources/Help/Code/ExampleMacro.xml |
| Macro descriptor | What the Edit Macro dialog is built from, on design.xwiki.org | D1, D2, C1 to C9, E4 | Descriptor, list of macros with their categories |
| Translations | The name, description and parameter names in each language | D1, D2, D4, C1 | l10n.xwiki.org |
| Uses in XWiki pages | How XWiki itself uses the macro, a realistic example when the documentation has none | L3, C2, C3, C6, C8, C9 | Search the xwiki organization on GitHub |
| Compared macros | The audits of the macros of the same type | L1, D3 | box, menu |
| Criterion | Result | Notes |
|---|
| D1 wording | OK |
|
| D2 summary | OK |
|
| D3 category | KO | minor: the macro is only in Formatting, like box and code, while a user looking for a way to show a code sample, a snippet or the source of some wiki syntax would also look under Development, where html is. A macro can have several categories since XWiki 14.6, so example could also be in Development. |
| D4 quick-action | KO | Quick Actions finds the macro first for "example", for the ID, and for the French name "Exemple". Of the synonyms, "sample" finds it first, but "code sample", "demo", "source code", "show code" and "snippet" give no result; "snippet" lists Code Snippet and "demo" lists Emoji and Container. The German name "Beispiel" was not searched. |
| L1 consistency | OK | compared with box and menu. Like menu, the content is mandatory and has no default, so the Quick Action opens the Edit Macro dialog, see I1 and I3; box has an optional content. An empty example would show nothing, so the mandatory content is by design. The macro has no parameter other than its content, which box and menu both have. |
| L2 doc-parameters | KO | the macro has no documentation page: the Documentation status page lists it as Undocumented, and no page of the Help Application, of the documentation tree or of extensions.xwiki.org describes it, its content, nor that the content is mandatory. |
| L3 doc-example | KO | with no documentation there is no example at all. The macro is only used by the Help macro pages, always as one macro call wrapped in it, like {{example}}{{info}}Information message.{{/info}}{{/example}} ; the audit used that info message call, from the Box macro help page, as the most common example. |
| I1 pattern | KO | the reference wrapper, warning, is inserted by its Quick Action without a dialog; the example Quick Action, the only entry that inserts the macro, opens the Edit Macro dialog, see I3. It follows the generic behavior of macros with a mandatory content and no dedicated Quick Action, like menu, html and comment. |
| I2 zero-config | OK | the Edit Macro dialog cannot be submitted with the default values, since the content is mandatory and empty: it stays open, with no message, the generic behavior of the dialog. An empty example would not be a sensible result, so the mandatory content is OK. Written by hand, {{example/}} fails in view mode with "Missing macro content: this macro requires content (a body)". |
| I3 instant | KO | inserting from the Quick Actions menu with "/example" and Enter opens the Edit Macro dialog with an empty Content text area; the macro is only inserted after typing the example in wiki syntax, like {{info}}Information message.{{/info}} , and submitting. |
| I4 cursor | OK | after submitting the dialog with a content, typed text goes inside the macro content: the example is edited in place. |
| I5 focus | N/A |
|
| E1 wysiwyg | OK |
|
| E2 errors | N/A | the macro has no parameter, and its content is free wiki syntax, so there is no invalid value to test. An unknown parameter is accepted, which is generic and not recorded. |
| E3 nesting | KO | in a list item and in a table cell the macro fails in view mode with "The [example] macro is a standalone macro and it cannot be used inline", and its content cannot be edited. In a box it renders and its content stays editable, and so does a list, a table or a box inside its content. |
| E4 inline-support | OK | the macro does not declare inline support, and its output, a block with an Example and a Source tab, cannot be inside a sentence: the missing declaration has a technical reason. In a sentence it shows the standalone error of E3. |
| E5 empty | OK | the content emptied in the editor stays a visible area, 952 by 76 pixels after a triple click and Delete, or 952 by 20 pixels after selecting everything, that one click puts the cursor in. Saved empty, the page holds {{example}} and an empty line, and view mode shows no error, unlike {{example/}} , which fails. |
| E6 inplace | KO | the content is edited in place, rendered, in the Example tab, but the Edit Macro dialog still shows it as a wiki syntax text area, also when editing an existing example, so a nested macro like the info message appears as {{info}}Information message.{{/info}} . |
Lucas Charpentier
