Thanks for starting this.
We tried applying it to our macros (roughly 75), and it works quite well. I would only broaden the Generator definition a bit: generated output may depend not only on parameters, but also on the current document/context, referenced content, queries, permissions, or external data. As a result, it can be perfectly normal for the same macro invocation to produce different output for different users. This is worth keeping in mind when auditing such macros. Example: the same Live Data macro invocation may expose 10 matching entries to one user and 5,000 to another, depending on the data the respective user is allowed to access.)
A few additional criteria came to mind, and I would slightly refine E1:
| ID | Name | Criterion | Applies to |
|---|---|---|---|
| D5 | search-id |
Macro search matches the stable macro ID as well as the localized macro name, so that a macro can be found regardless of the current UI language using the identifier shown in wiki syntax, documentation or error messages. Example: In a German UI, searching for display does not find the Display macro; it can only be found by searching for its localized name, Inhalte. |
All |
| E1 | wysiwyg |
The editor representation preserves the semantic meaning of the macro. It does not need to reproduce the exact visual or interactive behavior of View when a dedicated edit representation improves usability. Examples: XWiki’s Dashboard macro intentionally uses a dedicated edit-mode representation instead of reproducing the exact View behavior. Conversely, Live Data in the standalone WYSIWYG editor remains stuck in its loading state in 17.10 (XWIKI-24854). A meaningful semantic edit representation would be more useful than trying to reproduce the original View behavior in the editor. | All |
| E6 | unknown-macro |
An unresolved macro remains understandable and repairable in the editor: the error is at least as informative as in View, and the existing macro ID, parameters and body remain inspectable without data loss. Example: For an unavailable jira macro, View explains that the macro is not registered, suggests checking the spelling, and even lists a compatible extension. In the WYSIWYG editor, the same macro is reduced to a generic “failed to retrieve macro descriptor” error, while the existing macro ID, parameters and body are no longer accessible for repair. |
All |
I personally use Wiki edit mode quite often because a 1:1-like WYSIWYG representation can make authoring harder on macro-heavy pages. If most of the page is generated or included content and only a small part is actually editable, the editable sentence can be difficult to locate. This is another reason why I would prefer semantic fidelity over visual fidelity in E1.
If I can help with the analysis, let me know.