docs(mpconfig): Match directory config source docs to current functio…

…nality.

This doc change aligns the docs with the new implementation of the directory
config source for MicroProfile Config API.

- See PR payara/Payara#5007
- Internal ticket FISH-788

docs/modules/ROOT/pages/documentation/microprofile/config/directory.adoc

@@ -1,3 +1,5 @@
+:source-highlighter: rouge
+
 = Directory Config Source
 
 == Configuration
@@ -24,7 +26,10 @@ include::partial$tech-preview.adoc[]
 `asadmin> set-config-dir --directory=<full.path.to.dir> --target=<target[default:server]>`
 *Aim*::
 Sets the directory to be used for the directory config source.
-
+- *Leaf directory may not start with a dot*, rendering `/home/payara/.secret`
+  an invalid path ("." means hidden on a POSIX filesystem).
+- If relative, will lookup beneath server instance location
+  (usually to be found at `<PAYARA-HOME>/glassfish/domains/<DOMAIN>/`)
 
 ===== Command Options
 
@@ -36,7 +41,8 @@ Sets the directory to be used for the directory config source.
 |Mandatory
 
 |`directory`
-|Full path to the directory containing configuration files
+|Full path to the directory containing configuration files.
+ Leaf directory name may not start with a dot.
 |-
 |yes
 
@@ -50,10 +56,10 @@ Sets the directory to be used for the directory config source.
 
 ===== Example
 
-[source,Shell]
+[source]
 ----
 asadmin> set-config-dir
-    --directory=/home/payara/.secrets
+    --directory=/home/payara/secrets
     --target=myAppCluster
 ----
 
@@ -87,7 +93,7 @@ Gets the value of the directory to be used for the directory config source.
 
 ===== Example
 
-[source,Shell]
+[source]
 ----
 asadmin> get-config-dir
     --target=myAppCluster
@@ -101,34 +107,62 @@ Usually this config source is used to map secrets mounted by Kubernetes or
 Docker to a directory inside a running container.
 
 Once you configured a directory to read a config (secrets) from, you need to
-make sure properties in your codebase map to files.
+make sure file names correspond to properties in your codebase.
 
 === Map property names to flat file hierarchy
 
 _Since *5.183*&nbsp;_
 
 1. Say you have two properties `property1` and `foo.bar.property2`.
-2. Payara is configured with secret directory `/home/payara/.secrets`
-3. Secrets mounted as files to `/home/payara/.secrets/property1` and
-   `/home/payara/.secrets/foo.bar.property2` will be read.
+2. Payara is configured with secret directory `/home/payara/secrets`
+3. Secrets mounted as files to `/home/payara/secrets/property1` and
+   `/home/payara/secrets/foo.bar.property2` will be read.
 
-Remember that the files may only contain the secret, no newline, metadata, etc.
+Remember that the files may only contain the secret or other configuration
+value - no newlines, metadata, etc! Plaintext files only, no file extensions
+allowed.
 
 === Map property names to a sub-directory structure
 
-_Since *5.2020.7*&nbsp;_
+_Since *5.2021.1*&nbsp;_
 
 1. Say you have two properties `property1` and `foo.bar.property2`.
-2. Payara is configured with secret directory `/home/payara/.secrets`
-3. Secrets mounted as files to `/home/payara/.secrets/property1` and
-   `/home/payara/.secrets/foo/bar/property2` will be read.
-
-Usually property scopes are done via "." in their names, reflecting to
-subdirectories here.
+2. Payara is configured with secret directory `/home/payara/secrets`
+3. Secrets mounted as files to `/home/payara/secrets/property1` and
+   `/home/payara/secrets/foo/bar/property2` will be read.
 
-Remember not to include "." in your file names or they won't be found reliably.
 Restrictions on the files content are the same as with the flat hierarchy.
 
+Updates to files and subdirectories are picked up at runtime. Re-retrieving
+the config property will use the updated values. This allows for clearing
+a value by removing the file, too.
+
+==== Dots usage and depicting directories and file name
+
+Dots in property names are used to reflect scopes, for example to distinguish
+different applications, modules, etc.
+
+1. Any dots in the property name may correspond to changing from one directory
+   to a subdirectory.
+   Example: `foo.bar.test` could be a file `test` in `foo/bar/` path.
+2. You may combine any number of dot-separated "components" into directories
+   and file name.
+   Example: `foo.bar.test.example` may be a file `test.example` in
+   `foo/bar/` path or a file `example` in path `foo/bar.test/` and so on.
+3. Do not use a file extension, as it would be taken as part of the
+   property name.
+4. The longest, most specific match "wins" for reading the value into the
+   property. This allows to create scoped directory structures as you see fit.
+   Example: `foo.bar/test.example` is less specific than `foo/bar/test.example`
+   and so on.
+
+You cannot use directories or files whose names start with a dot. They will
+be ignored, following the POSIX philosophy of hidden files and folders.
+
+Symlinks will be followed, so you can expose files from such hidden areas,
+allowing for all types of mangling with names etc. (This allows the Kubernetes
+Secret mounting magic to happen...) Don't symlink to directories, as the
+file monitors rely on real directories.
 
 ==== Kubernetes Example
 
@@ -152,23 +186,23 @@ stringData:
   property1: my-super-secret-value
 ----
 
-And your pod mounts it at `/home/payara/.secrets/foo/bar`
+And your pod mounts it at `/home/payara/secrets/foo/bar`
 (only showing the relevant parts from the `Deployment` K8s YAML):
 
 [source,Yaml]
 ----
 volumeMounts:
   - name: test-secrets
-    mountPath: /home/payara/.secrets/foo/bar
+    mountPath: /home/payara/secrets/foo/bar
 volumes:
   - name: test-secret
     secret:
       secretName: foobar
 ----
 
-[source,Shell]
+[source]
 ----
-/ # ls -la /home/payara/.secrets/foo/bar
+/ # ls -la /home/payara/secrets/foo/bar
 total 3
 drwxrwxrwt 3 root root  120 Nov 25 10:51 .
 drwxr-xr-x 3 root root 4096 Nov 25 10:51 ..