[gst-devel] README-files in plugins/*

[Christian Schaller]

hi,
A late reply is better than no reply they say. I would suggest that when
we create documentation we do so with the standard defined Open Source
Metadata Framework(OMF). This format has been selected as a common
standard between GNOME, KDE, FreeBSD and LDP. More information can be
found on the Scrollkeeper homepage.
http://scrollkeeper.sourceforge.net/

Christian

On 07 Jun 2001 10:13:33 +0100, Richard Boulton wrote:
> On Thu, Jun 07, 2001 at 10:51:33AM +0200, Thomas Nyberg wrote:
> > Noone likes to write documentation, but it is always nice to
> > read it. Some informal information would probably do for now,
> > but in the end something looking like a man-page should
> > probably be favorable.
> 
> Absolutely agree that documentation of each plugin is required, and
> that in the short term, to encourage easy creation, is should probably be
> in the form of READMEs in each plugin directory.
> 
> But, I don't think man pages, or similar, are desirable for this kind of
> documentation.  A structured form would be greatly preferable.
> 
> In fact, I would favour documentation _in_ the plugins themselves.  (With
> an optional compile switch to prevent including it for situations where
> space is dear.)
> 
> The reason for this is that tools, such as the editor, can then access and
> display the documentation, it is more likely to be kept up to date, and
> less likely to get dissassociated from the plugin it refers to.
> 
> A gstreamer-inspect like tool could then extract this documentation and
> convert it into a standard form (eg, docbook) for generation of other forms
> of documentation.
> 
> An alternative approach is to have a standard format for a documentation
> file, with defined fields to encourage documenters to document standard
> things (as well as some general purpose "description" fields, ofc), and
> then have a tool to generate accessible documentation from that (again, eg,
> docbook).
> 
> Probably, for now, we should specify a list of "standard things to
> document" and see how that develops, and then do a proper specification of
> a format.
> 
> -- 
> Richard
> 
> _______________________________________________
> gstreamer-devel mailing list
> gstreamer-devel at lists.sourceforge.net
> http://lists.sourceforge.net/lists/listinfo/gstreamer-devel
>