[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Sat, 1 Aug 2009 14:50:32 +0100
On Sat, Aug 01, 2009 at 03:03:25PM +0200, Reuben Thomas wrote:
> My renaming drive (to change them all to the same prefix) will help
> inspection of the list. Peter is working on documentation, which will
> also help, though I'm actually sceptical about the value of doing it:
> how will the documentation be kept consistent with the code? Will it
> be automatically generated from the code? If so, fine. Otherwise, I'm
> skeptical about both the value of the documentation and of the wisdom
> of spending time on it. If it's a one-off effort to provide texinfo
> documentation generated from the comments in the .m4 files, then fine.
I guess it is the latter, yes.
> I have suggestions:
> 1. Separate the macros into two groups, those which are single-purpose
> (broadly speaking, those which don't take arguments), and those which
> are general purpose. This makes the search problem easier.
can you make some examples of both categories with existing macros? Just to help
understanding where to draw the line.
> 2. Be more demanding when new general-purpose macros are submitted:
> are they necessary? can the functionality be added to an existing
> macro? For special-purpose macros: why is a special-purpose macro
> needed? What's the audience?
good point, once the archive is consistent with both macro naming and usage
submissions can be better (IOW simply copying from existing macros and using the
> Essentially, we should be able to achieve good results with
> structuring, and leave little need for documentation beyond what is
> written in each file, even if we allow it to be read in a more
> convenient format.
I would add something like a FAQ as I bet there are recurrent problems which are
solved by "popular" macros in ac-archive.
Filippo Giunchedi - http://esaurito.net - 0x6B79D401
There is nothing either good or bad, but thinking makes it so.
-- William Shakespeare. Hamlet; Act II, scene ii