[development] Documenting contribs
inkfree at gmail.com
Wed Oct 25 20:40:04 UTC 2006
"Moshe Weitzman" wrote:
> I like reuse of .info files because it centralizes project metadata. We
> probably need some more metadata fields.
An excellent point. (One file to rule them all. One file to bind them.)[*]
The problem is: Out of 354 modules just checked, only _3_ use this file at
So, there's that.
The general guideline of including an "INSTALL.txt", "README.txt" and
"LICENSE.txt" is a very wobbly guideline also. Some have only the last,
some have a README.txt which has only one sentence, saying "See some other
document named blah" or similar. And some have files named without any
extension at all [README].
A common, required and re-usable system should be able to avoid some of the
call for a "Golden Seal" stamped onto some modules, indicating their level
of quality. (I _still_ think that's a worthy system, but that debate was
long and generally a non-starter.)
[*] Plain text format with metadata labels (as it is) is excellent and
re-usable in lots of ways. This should be taken advantage of, of course. I
agree that there need to be more "label =" metadata data fields. Everthing
should be here, and then it can be used to auto-generate the module
description pages. Even whole "Module Library" descriptions could be
downloaded in XML, for browsing descriptions. Yes, one well-formed file
should be the basis of everything else -- maintainers only need to keep one
".info" source and that's it.
More information about the development