New help files for Roles MDL-6923

lang/en_utf8/help/assignroles.html

@@ -0,0 +1,34 @@
+<p align="center"><b>Assigning Roles</b></p>
+
+<p>
+By assigning a role to a user in a context, you 
+are granting them the permissions contained
+in that role, for the current context and all 
+"lower" contexts.
+</p>
+
+<p>
+Contexts:
+<ol>
+<li>Site/System</li>
+<li>Course Categories</li>
+<li>Courses</li>
+<li>Blocks and Activities</li>
+</ol>
+</p>
+
+<p>
+So for example, if you grant a Student role to a 
+user in a Course, they will have that role for 
+the course, but also all Blocks and Activities inside
+that course.  Their actual permissions may depend on 
+other roles and overrides that have been defined.
+</p>
+
+<p>
+See also 
+<a href="help.php?file=roles.html">Roles</a>,
+<a href="help.php?file=contexts.html">Contexts</a>,
+<a href="help.php?file=permissions.html">Permissions</a> and
+<a href="help.php?file=overrides.html">Overrides</a>.
+</p>

lang/en_utf8/help/contexts.html

@@ -0,0 +1,24 @@
+<p align="center"><b>Contexts</b></p>
+
+<p>Contexts are the "areas" in Moodle where roles
+   can be assigned to people</p>
+
+<p>They are arranged in a hierarchical fashion, with permissions
+   inherited from "higher" to "lower" contexts.</p>
+
+<ol>
+<li>Site (System)</li>
+<li>Course Categories</li>
+<li>Course Sub-categories</li>
+<li>Courses</li>
+<li>Blocks and Activities</li>
+</ol>
+</p>
+
+<p>
+See also 
+<a href="help.php?file=roles.html">Roles</a>,
+<a href="help.php?file=permissions.html">Permissions</a>,
+<a href="help.php?file=assignroles.html">Assign Roles</a> and
+<a href="help.php?file=overrides.html">Overrides</a>.
+</p>

lang/en_utf8/help/index.html

@@ -9,6 +9,15 @@
   <li><a href="help.php?file=search.html">How to search</a></li>
 </ul>
 
+<p>Roles</p>
+<ul>
+  <li><a href="help.php?file=roles.html">Roles</a></li>
+  <li><a href="help.php?file=contexts.html">Contexts</a></li>
+  <li><a href="help.php?file=permissions.html">Permissions</a></li>
+  <li><a href="help.php?file=assignroles.html">Assign Roles</a></li>
+  <li><a href="help.php?file=overrides.html">Overrides</a></li>
+</ul>
+
 <p>Administration</p>
 <ul>
   <li><a href="help.php?file=advancedsettings.html">Advanced settings</a></li>
@@ -19,7 +28,6 @@
   <li><a href="help.php?file=langedit.html">Language editing</a></li>
   <li><a href="help.php?file=uploadgroups.html">Upload groups</a></li>
   <li><a href="help.php?file=uploadusers.html">Upload users</a></li>
-
 </ul>
 
 <p>Setting up courses</p>

lang/en_utf8/help/overrides.html

@@ -0,0 +1,40 @@
+<p align="center"><b>Overrides</b></p>
+
+<p>
+Overrides are specific permissions designed to override a 
+role in a specific context, allowing you to "tweak" your 
+permissions as required.
+</p>
+
+<p>
+For example, if users with the role Student in your course 
+can usually start new discussions in forums, but there is 
+one particular forum for which you want to restrict that 
+capability, then you can set an override that PREVENTS 
+the capability for Students to "Start new discussions".
+</p>
+
+<p>
+Overrides can also be used to "open up" areas of your 
+site and courses to give users extra permissions where 
+it makes sense.  For example, you may want to experiment 
+giving Students the ability to grade some assignments.
+</p>
+
+<p>
+The interface is similar to the one for defining roles,
+except sometimes only relevant capabilities are shown, 
+and you will also see some capabilities highlighted to 
+show you what the permission for that role would be 
+WITHOUT any override active (ie when your override is 
+set to INHERIT).
+</p>
+
+
+<p>
+See also 
+<a href="help.php?file=roles.html">Roles</a>,
+<a href="help.php?file=contexts.html">Contexts</a>,
+<a href="help.php?file=assignroles.html">Assign Roles</a> and
+<a href="help.php?file=permissions.html">Permissions</a>.
+</p>

lang/en_utf8/help/permissions.html

@@ -12,7 +12,7 @@
 In each role, you can choose to set the permission for such a capability 
 to one of four values:
 <dl>
-<dt>Inherit</dt>
+<dt>INHERIT</dt>
 <dd>This is the default setting, generally.  It's a neutral setting that
     means "use whatever setting the user already had".   If a role 
     gets assigned to someone (eg in a course) that has this permission for 
@@ -22,7 +22,7 @@
     level, then the user will have no permission for that capability.
     </dd>
 
-<dt>Allow</dt>
+<dt>ALLOW</dt>
 <dd>By choosing this you are granting permission for this capability
     to people who are assigned this role.  This permission applies
     for the context that this role gets assigned plus all "lower"
@@ -32,12 +32,12 @@
     override or a new assignment with a Prevent or Prohibit value
     for this capability.</dd>
 
-<dt>Prevent</dt>
+<dt>PREVENT</dt>
 <dd>By choosing this you are removing permission for this capability,
     even if the users with this role were allowed that permission in 
     a higher context.</dd>
 
-<dt>Prohibit</dt>
+<dt>PROHIBIT</dt>
 <dd>This is rarely needed, but occasionally you might want to completely
     deny permissions to a role in a way that can NOT be overridden at 
     any lower context.  A good example of when you might need this is 
@@ -52,13 +52,29 @@
 
 <p align="center"><b>Conflict resolution of permissions</b></p>
 
+<p> Permissions at a "lower" context will generally override 
+    anything at a higher "context" (this applies to overrides
+    and assigned roles).  The exception is PROHIBIT which can not 
+    be overridden at lower levels.
+</p>
+
 <p> If two roles are assigned to a person in the same context, one with 
-    Allow and one with Prevent, which one wins?  In this case, Moodle will 
+    ALLOW and one with PREVENT, which one wins?  In this case, Moodle will 
     look up the context tree for a "decider".   </p>
 
 <p> For example, a student has two roles in a course, one that allows 
     them to start new discussions, one that prevents them.  In this case, 
     we check the categories and the site contexts, looking for another 
     defined permission to help us decide.  If we don't find one, then 
-    permission is prevented by default (the two settings cancelled each other out).
+    permission is PREVENT by default (because the two settings cancelled 
+    each other out, and thus you have no permission).
+</p>
+
+
+<p>
+See also 
+<a href="help.php?file=roles.html">Roles</a>,
+<a href="help.php?file=contexts.html">Contexts</a>,
+<a href="help.php?file=assignroles.html">Assign Roles</a> and
+<a href="help.php?file=overrides.html">Overrides</a>.
 </p>

lang/en_utf8/help/roles.html

@@ -0,0 +1,43 @@
+<p align="center"><b>Roles</b></p>
+
+<p> 
+A role is a collection of permissions defined for the whole site 
+that you can assign to specific users in specific contexts.
+</p>
+
+<p>
+For example, you may have a Role called "Teacher" that is set up to 
+allow teachers to do certain things (and not others).   Once this role
+exists, you can assign it to someone in a course to make them a "Teacher"
+for that course.  You could also assign the role to a user in the 
+course category to make them a "Teacher" for all the courses under that
+category, or assign the role to a user just in a single forum, giving 
+that user those capabilities just in that forum.
+<p>
+
+<p>
+A role must have a <strong>name</strong>.  If you need to name the role for multiple 
+languages you can use multilang syntax if you wish, such as <pre>
+  &lt;span lang="en">Teacher&lt;/span> 
+  &lt;span lang="es_es">Profesor&lt;/span> 
+  </pre>If you do this make sure the setting to "filter strings" is on for your installation.
+</p>
+
+<p>
+The <strong>shortname</strong> is necessary for other plugins in Moodle that may need
+to refer to your Roles (eg when uploading users from a file or setting 
+enrolments via an enrolment plugin).
+<p>
+
+<p>
+The <strong>description</strong> is simply to describe the role in your own words, so 
+that everyone has a common understanding about the role.
+<p>
+
+<p>
+See also 
+<a href="help.php?file=contexts.html">Contexts</a>,
+<a href="help.php?file=permissions.html">Permissions</a>,
+<a href="help.php?file=assignroles.html">Assign Roles</a> and
+<a href="help.php?file=overrides.html">Overrides</a>.
+</p>