[gst-devel] Proposal for XML Description File for Plugins

[David Schleef]

On Wed, Feb 09, 2005 at 08:22:00PM -0600, Jeff Mitchell wrote:
> > 1) create the status table without needing manual updates. (This is how
> > gst-inspect works.)
> > 2) find missing updates automatically and make them break the build. (This
> > is how our documentation building works.)
> > 
> > Binary extraction would be step 1). A manually updated XML file (or
> > multiple manually updated XML files) would be the exact same problem as
> > before.
> 
> I guess a big part of the issue here is what exactly we want in the
> status tables.
> 
> The information has to be provided somewhere, which means that manual
> updating has to occur at some point.  gst-inspect provides the details
> in GstElementDetails, for instance, but if we want to add field foobar
> in there with another piece of relevant information, that info still
> has to be added somewhere into the code for gst-inspect to gather it. 
> At which point other code may need to be changed because the structure
> of the GstElementDetails struct as changed.

Good grief, you are _so_ not getting it.

This is what you need to do:

 1) Create a program that pulls out information that would be relevant
    to documentation from all plugins installed on your system.
    Select only the plugins that are from the product 'gst-plugins'.
    Write out the information for each plugin into an XML file using
    the DTD of your choosing.

 2) Put that XML file into gst-plugins CVS and make it build into a
    nice document.

 3) Add any information you wish to this document, possibly modifying
    the DTD because you want to add additional fields.

 4) Change the program in 1) so that will do everything in 1) above,
    *but* *also* read in an XML file, modify information for plugins
    that have changed and/or add information for plugins that are new,
    and write out the new XML file.

 5) Write a script that complains about missing or bogus information
    in the updated XML file, so that we can include it in the build
    process and complain loudly on the buildbots if anything is wrong.

 6) Put it into the web build system so that we have a nice status
    page on the web.

Other stuff:

 - Any plan that requires modifying the source code of plugins is
   probably wrong.

 - API changes _will_ _not_ _occur_ in the 0.8 series, so there's no
   point in discussing it.

 - If we have a plugin documentation system working before the 0.9
   API freeze, we'll probably just drop any redundant information
   in the plugins, especially if it needs to be translated.



dave...