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

[Richard Boulton]

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