Re: Discrimination

[Filippo Giunchedi]

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
same style)

> 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
-- 
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