flexible, extensible and parametric macros in doc comments

[Stefan Kost <ensonic hora-obscura de>]

hi,

There is one feature I'd like to do for 1.14 - custom macros. Right now we have
e.g. |[ ... ]| as a shortcut for programmlisting.

I'd like to have something more flexible, extensible and parametric. E.g.:
|macro(arg1,arg2,...)[ ... ]|
  - call macro
  - pass args as parameters (on the commandline)
  - content of [] on stdin or as a file
  - get output on stdout or file
  - and replace the macro with it

some examples:
|highlight(c)[...]| - highlight source code for a specific language
|dot(abc.svg)[...]| - format dot graph and include result as mediaobject
|ditta(abc.svg)[...]| - parse ascii art and include result as mediaobject

Any other idea?

I need to figure a lot of practical details still:
- where to define those macros
  - we could include popular ones with gtk-doc
   (installed to <prefix>/share/gtk-doc/macros)
  - the package that uses gtk-doc could have their own ($srcdir)
  - we always look in $srcdir first, so that the app could e.g.
    inlcude a brand-new one (a version check to load the newer would be better)
- we could require stdin for input and stdout for output, the wrapper for the
  actual tool can ensure the convention
- the mailing-list bugzilla can be used to submit macros for inclusion
  in future versions

Anything I miss?

Stefan