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

[Simon Per Soren Kagedal]

On Sun, Jun 10, 2001 at 09:03:41PM +0200, Christian Schaller wrote:
> 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/

OMF is not about how to create documentation, it is about meta data
for cataloguing documents for help systems...  And looking at the
standard, it doesn't seem to me that it is aimed at programming
reference documentation...  :/ (like, indexing function names and such
- I want to have a standard framework for things like getting help
about a function name, type etc. in any source code editor)

Best format for the actual docs is probably XML DocBook.

Simon.


> 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
> > 
> 
> 
> _______________________________________________
> gstreamer-devel mailing list
> gstreamer-devel at lists.sourceforge.net
> http://lists.sourceforge.net/lists/listinfo/gstreamer-devel