Forum OpenACS Development: is there any decent documentation on permissions?

I've run into a problem with permissions, and before I call it a
bug I'd like to understand better how this is *supposed* to work.
Unfortuntely, I can't find any docs on this stuff.  I'm working with
ACS Classic, but I thought that since most of the porters seem to
hang out in this bboard someone might have found something
that could help clear this up.

The situation is this:

The code does a permission check like this:

ad_require_permission $user_id permission_needed

I go to /permissions, find the link for the module, and grant the
proper permission to the proper user (suffering with all the
drop-down nonsense alraedy discussed).

User still doesn't have permission.

I go back to /permissions, find the link for the user, and do the
same grant again.

Now the user has permission.  And I am terminally confused as
to why this should be.

A grep for ad_require_permission shows that it's usually called
on the object_id, which I believe would have worked after my first
grant, but sometimes it's called with user_id, group_id,
category_id, etc, each of which (I believe) is going to require a
grant to the particular id being checked, *from* that id's
permission page.

I thnk that this inconsistency is going to drive people bonkers...
unless I'm missing something?

ad_require_permission $user_id permission_needed

The way you've written it checks wether the user who's viewing the page has permission_needed on user_id, which is probably not what you want. The first argument should be your 'module'.

Otherwise, ad_permission_p allows the flexibility to check permissions for arbitrary users.

Thanks, Stephen.  That's more or less what I thought.  I actually
didn't write this code, it's from the unfinished calendar module.
And there are other examples of this usage sprinkled about.  I'm
sure there are times when one wants to use
ad_require_permission this way, but I have a feeling that most of
the time it's done in error.  Guess it's time for a bug report.
I posted a similar question a few weeks ago and Vadim, an aD developer, sent me this document, called "ACS 4 Permissions Tediously Explained" which cleared up _a lot_ of my questions.

With his permissions, I uploaded it to new-file-storage. You can read it at https://openacs.org/new-file-storage/download/permissions-notes-vadim.html?version_id=229. It's a great read for (Open)ACS 4 developers.