Naming common pkgsrc mk includes (was ssl.buildlink3.mk)

[David Brownlee <abs%absd.org@localhost>]

We have some... different patterns in naming mk files that can pull in
different dependencies

I'm not looking to necessarily change any existing files here, more to
see if there is consensus on which of the patterns are encouraged, and
hopefully document that.

Pattern 1 - dependency selection - in package dir with various .mk files
- All files live in package dir
- Good example is lang/python with application.mk, egg.mk etc, all
calling pyversion.mk and checking PYTHON_VERSIONS_* and friends,

Pattern 2 - dependency selection - various .mk files in pkgsrc/mk
- pretty much the same as pattern 1, except the files live in pkgsrc/mk
- java is a good multi file example with java-env.mk and java-vm.mk
with PKG_JVM_DEFAULT, USE_JAVA2 (sic) and friends, or apache with
apache.mk, apache.module.mk and PKG_APACHE_ACCEPTED etc

Pattern 3 - dependency selection - various buildlink3.mk files in pkgsrc/mk
- pretty much the same as pattern2, but with a 'buildlink3.' in the filename
- good example would be bdb, with bdb.buildlink3.mk and BDB_ACCEPTED etc

Pattern 4 - factored out build config in pkgsrc/mk
- "one of these things is not like the others..." named the same as
pattern2, but just holds build config as opposed to dependency
selection (with associated build config)
- example would be djbware.mk

Pattern 5 - builtin handling - always(?) named *.buildin.mk in pkgsrc/mk
- determines whether to use builtin or pkgsrc dependencies
- usually not used directly, but called by a buildlink3.mk file
- example - mk/readline.builtin.mk, called by readline.buildlink3.mk

There is also the minor issue that these are all mixed in with the top
level mk files in pkgsrc/mk - which adds to the level of confusion to
anyone coming new to the pkgsrc setup

So

a) I think the biggest inconsistency seems to be between pattern 2 & 3
- which seem to pretty much be the same thing. At the very least
should the dependency selection mk files have buildlink3. in their
names, and can we document a recommendation going forward

b) If we are happy keeping both 1 and 2/3 for new files going forward,
can we document a preference for how to name them. eg: If it applies
to a single named package, put it in the package dir, else if it's
more general put it in pkgsrc/mk. I'm half inclined to say 'prefer
putting everything new in pkgsrc/mk', but I can see arguments against

c) subdirectories? if we're going to keep adding files to pkgsrc/mk
can we get these types of files into one or more subdirectories (OK,
maybe I _am_ looking to change existing file layout here)

David