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

[Maciej Katafiasz]

Adding some more constructive criticism you asked for.

Dnia 09-02-2005, śro o godzinie 23:26 -0600, Jeff Mitchell napisał:
> > 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.
> 
> Any particular system may not have all plugins installed, which would
> lead to incomplete tables if the script used to build the web site is
> run on such a system.

What is the problem with applying union operator here? There's more than
one system gst builds on...

> >  2) Put that XML file into gst-plugins CVS and make it build into a
> >     nice document.
> 
> Cue big monolithic XML document number 1.

Which you would create anyway in your proposal, just with more manual
content. Unless you meant something else, but then I'm afraid you
totally failed to explain it.

> >  3) Add any information you wish to this document, possibly modifying
> >     the DTD because you want to add additional fields.
> 
> Arbitrarily modify big monolithic XML document number 1.  Already this
> is becoming clunky...

Uh, y'know, XML was specifically designed to be easy to parse and
manipulate in automated way.

> >  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.
> 
> So now you propose to gather information from both the (possibly
> incomplete) binaries and some XML file, somehow keeping track of what
> has changed or is new, and merging the data.  Cue big monolithic XML
> document number 2.  Even more clunky.

Again, poking XML is not hard. And keeping track is trivial, like:

desc_table = read_big_xml()
for plugin in plugins:
    desc = read_plugin_desc(plugin)
    if (plugin not in desc_table) or (desc_table[plugin] != desc):
        desc_table[plugin] = desc
write_big_xml(desc_table)

> >  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.
> 
> So now, after merging as-yet-undefined data pulled from random
> sources, identify what's missing.  This could be done much earlier
> with a DTD/schema.

Eh? I don't really understand your objection, nor solution.

> >  6) Put it into the web build system so that we have a nice status
> >     page on the web.
> 
> As described, this is messy.  It's an ugly hack.  There's no reason
> this can't be done elegantly and extensibly, and with far less work
> and with better output.

Like, what exactly is hacky about that? You get the info from where it
resides, you reformat it and augment with some external bits you have
from other sources, then put it where you want it to be. Simple and
elegant.

> >  - Any plan that requires modifying the source code of plugins is
> >    probably wrong.
> 
> I'm trying to get *away* from modifying the source code of plugins --
> which is the system you have *now*.

I think there might be misunderstanding here. "Modifying source" as in
source of many or all plugins to make it more parsable / accommodate for
extended info in your scheme / something else == bad. Modyfing inline
description in individual plugins' sources as they change == good.
(Correct me if I got any part of this wrong)

> >  - API changes _will_ _not_ _occur_ in the 0.8 series, so there's no
> >    point in discussing it.
> 
> Excellent, I'm fully in favor.  So we better make sure we have a way
> for any extra information we may want to be gained from the plugins
> without changing the API as it currently is.  Wait, I have an
> idea...wouldn't this be a *perfect* use for an alternate data
> source...say...XML?

Uh, and care to explain *why* you were arguing against "big monolithic
XML document number 1" above?

> >  - 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.
> 
> I've been told that a lot of Gstreamer developers very strongly
> dislike redundant information...

That's true. Also, they dislike things that break easily. And, guess
what, redundant things tend to break easily :)

> I should note that throughout this whole reply of yours, you did not
> contribute any information relating to what is most important right
> now and what I specifically asked for input on several times in my
> previous posting -- namely, what information we wish to have in the
> status tables.

I'd say he did. Look at points 1) and 3). Right now you're before stage
1), make it past 2) and we will have nice starting point for discussion
about what's missing there.

Cheers,
Maciej

-- 
Maciej Katafiasz <ml at mathrick.org>