packages (was: Archive unification progress)

[Peter Simons]

Stepan Kasal writes:

 > I'd intuitively treat individual files as ``packages,''
 > expectind the dependencies to work on this level.

I agree, that's the simplest solution I'd know. That
approach didn't work out too well in the past because there
was only one @synopsis line, so you couldn't specify the
synopsis for more than one macro without breaking the
formatting. Lifting that restriction is pretty much a made
decision, so all is well. ;-)

A different (albeit related) problem is that it's not always
non-trivial to decide which macros should reside in the same
file and which ones shouldn't. For example: Let's assume
there was a cool macro that tested for package "foobar", and
that macro would use an internal helper to achieve whatever
functionality. Now, if the helper macro is available in the
same file only, then other macro authors can't use it
without depending on the "foobar"-test macro. So shipping
that macro in the same file restricts its usefulness.

On the other hand, once a file uses a macro from another
file, you can't use it individually anymore; you'll need
both files to use it. And then we're back at having to
express dependencies of files again.

That's why I tend towards having _one_ macro per file
(except really, really trivial helpers) and having
dependencies between files.

Right now, categories sort of stand in for packages. Instead
of having a "Java" package, we have a "Java Language"
category which has lots of macros that all depend on each
other. Thanks to the wonders of aclocal(1) that isn't really
a problem, but it's not exactly nice either.

Peter