search

xwikisas / xwiki-pro-macros

XWiki rendering macros useful when migrating content from Confluence
GNU Lesser General Public License v2.1
3 stars 12 forks source link

Separate Confluence bridges from XWiki SAS's own Pro macros #277

Closed snazare closed 3 months ago

snazare commented 3 months ago

Currently in the pro macros package we have 19 macros that are supposed to be bridges, used only in the context of the migration. 4 of these are prefixed by "confluence_" and 15 are not. This is an issue due to the following reasons:

Proposal: we could split the pro macros into two sub modules, one "confluence bridges" and one "generic editing macros".

Generic macros that can be used in any context:

  1. column
  2. content report table
  3. contributors
  4. excerpt
  5. excerpt include
  6. expand
  7. microsoftstream
  8. profile-picture
  9. recently-updated
  10. section
  11. userlister
  12. view-file

Confluence bridge macros that should be prefixed with 'confluence_' and not used as standalone macros after the migration:

  1. anchor - existing xwiki native "id" macro, we already convert it to id during conversions but we also have an unprefixed bridge
  2. [already prefixed] attachments - same content available in default attachments tab
  3. balsamiq - old xwiki integration existed. We should improve that one if requested.
  4. [already prefixed] children - existing xwiki native macro
  5. [already prefixed] gallery - existing xwiki native macro
  6. drawio - existing xwiki native diagram app
  7. gliffy - existing xwiki native diagram app
  8. layout
  9. mathblock - existing mathjax macro
  10. mathblock reference - existing mathjax macro
  11. mathinline - existing mathjax macro
  12. mockup - existing xwiki native diagram app
  13. multimedia - existing xwiki native functionality
  14. note - existing xwiki native functionality
  15. pagetree - existing xwiki native documenttree macro
  16. paste code - existing xwiki native code macros
  17. time - existing xwiki native date macro
  18. tip - existing xwiki native success macro
michitux commented 3 months ago

The "layout" and "section"/"column" macros are very similar in functionality and both hard to use (see existing issues). It would be beneficial I think to decide for one of them and improve that one instead of offering two half-working solutions. The layout-section's parameter ac:type="two_equal" does not seem very native, and the supported parameter values are basically undocumented (there are some examples in the documentation, the macro dialog just says "The layout type" with a text input and no further help). To me, it therefore seems the layout macro is more a Confluence bridge macro than anything else.

The "mathblock", "mathinline" and "mathblock reference" macros are very thin wrappers around the more generic MathJax Macro. To me they, should also be classified as Confluence bridge macros.

The "anchor" macro seems to be the exactly same as the native "id" macro in XWiki.

snazare commented 3 months ago

thank you very much for your input, @michitux ! I am modifying the description accordingly.