In the xdoc parser, Doxia uses <macro id="foo" /> to reference the 'foo' macro. This is an unfortunate choice because it allows each macro on each xdoc page only once (id must be unique). I'd suggest that this gets changed to e.g. macroName. Also, some macros (most prominently the snippet macro) might require an 'id' parameter, which not only clashes with the notation above but also leaves the problem that this id might clash with another id and can not be used twice on a page. I'd suggest that in a possible Doxia manual, the usage of an 'id' parameter is strongly discouraged. For the snippet macro, I'd suggest changing 'id' to 'snippetId'.