Support macro documantation [was: Sample Passenger/Rails policy for review]

[Moray Henderson]

Jason Axelson wrote:
>On Tue, Aug 17, 2010 at 5:34 AM, Moray Henderson
><Moray.Henderson at ict-software.org> wrote:
>> Are any of the macros in /usr/share/selinux/devel/include/support/
>> documented anywhere?  I couldn't find them in the Tresys Refpolicy
API
>> documentation or the selinuxproject.org wiki.
>
>Have you tried doing a "make html" in the refpolicy source? That will
>generate a nice html interface to the macros, although there are many
>so it can still be hard to tell which one would be best to use. Not
>sure if you'll have it with your distribution but if you download from
>tresys directly [1] you will be fine.
>
>1. http://oss.tresys.com/projects/refpolicy
>
>Jason

In the CentOS 5 policy source (selinux-policy-2.4.6-279.el5.src.rpm)
"make html" produces html for the files in admin, apps, kernel, services
and system directories of policy/modules/ which have embedded xml usage
notes.  

The basic support macros, however, are defined in policy/support/*.spt,
which do not even contain the xml comments necessary to produce the
html.

Then too I'm looking for documentation that actually explains what these
commands are for and how to put them together into something useful:
when should you use domain_auto_transition_pattern and when
domain_transition_pattern?  Why is there a macro called "domain_trans"
when it doesn't do a domain transition?  The often-cryptic one-liners in
the html reference seem to assume that level of knowledge.


Moray.
"To err is human.  To purr, feline"