Add folder_include_patterns and file_include_patterns

source/file_management/file_management.rst

@@ -223,11 +223,52 @@ and ``build_systems``, for project-specific build systems.
 
 
 **Folders**
-    Each folder must have a ``path``,
-    and may optionally have a ``folder_exclude_patterns``
-and ``file_exclude_patterns`` setting.
-    The path may be relative to the project directory,
-    or an absolute path.
+    Each folder must have a ``path``, that may be absolute or
+    relative. In the latter case it will be relative to the
+    project directory.
+
+    There are also the optional properties ``folder_include_patterns``,
+    ``file_include_patterns``, ``folder_exclude_patterns``
+    and ``file_exclude_patterns``. They all admit an array of strings
+    as values, and understand basic globbing syntax, such as "*.html".
+
+    The ones that include files and folders, work by excluding
+    everything first, so that in the end only what they specify
+    gets shown. After those, the ones that exclude folders apply,
+    though with lesser precedence.
+
+    Note that a pattern that includes any folder in the project
+    directory will not automatically include every of it's sub-folders,
+    but including theese will include any other descendants.
+
+    For example, consider adding the following to a folder:
+
+    .. sourcecode:: javascript
+        {
+            "folders":
+            [
+                {
+                    "path": ".",
+                    "folder_include_patterns": ["foo"]
+                }
+        }
+
+    If the folder "foo" is included, that will by itself include
+    any  other folder whose name starts with foo, whether it is in
+    the project folder, or inside some other folder. But, the folder
+    "bar" inside the "folder "foo" that resides in the project folder
+    will not be included automatically, whereas another folder called
+    "bar" or any other name in some other "foo" folder nested deeper
+    **wll** be included by this definition. If you want to include
+    every sub-folder form a folder residing in the project folder,
+    you can use something like "["foo", foo/*]".
+
+    Note also that a rule like the one in the prevous example would
+    not let us exclude an already included "foo" sub-folder through
+    the use of "folder_exclude_patterns", no matter the specificity
+    of the rule (for example "baz/bar/foo"). Consider that includes
+    have precedence over includes.
+
     Folders may also be given a ``name``
     that will appear in the side bar.