[jackrabbit-filevault] 01/01: JCRVLT-601 improve documentation on namespace handling

[kw...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

kwin pushed a commit to branch feature/docs-namespace-handling
in repository https://gitbox.apache.org/repos/asf/jackrabbit-filevault.git

commit 1f108c9e4f90670bc8b5404fc44a67784da3d6e9
Author: Konrad Windszus <kw...@apache.org>
AuthorDate: Mon Jan 31 16:55:58 2022 +0100

    JCRVLT-601 improve documentation on namespace handling
---
 src/site/markdown/nodetypes.md  | 12 +++++++++++-
 src/site/markdown/privileges.md |  8 +++++++-
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/src/site/markdown/nodetypes.md b/src/site/markdown/nodetypes.md
index c7b6634..70e6e71 100644
--- a/src/site/markdown/nodetypes.md
+++ b/src/site/markdown/nodetypes.md
@@ -19,4 +19,14 @@ Node Types and Namespaces
 ===========
 
 Packages can register custom [JCR node types](https://s.apache.org/jcr-2.0-spec/8_Node_Type_Discovery.html) and [Namespaces](https://s.apache.org/jcr-2.0-spec/3_Repository_Model.html#3.2.1%20Namespaces) during import by carrying arbitrarily many `.cnd` files. All files names matching the regular expression pattern set in [package property](properties.html) `cndPattern` as well as all `*.cnd` files below `META-INF/vault` are considered. Details around the CND file format can be found at < [...]
-Node types and namespaces whose qualified name/uri are already registered are not touched. This also means that existing namespaces and node types are never modified but only once initially installed in case they are not yet there.
+Node types and namespaces whose qualified name/prefix/uri is already registered are not touched. This also means that existing namespaces and node types are never modified but only once initially installed in case they are not yet there.x
+
+Namespace Prefixes
+-------
+
+As the [Standard Form of JCR Paths](https://s.apache.org/jcr-2.0-spec/3_Repository_Model.html#3.4.3.1%20Standard%20Form) only uses qualified names (i.e. leveraging prefixes instead of full URLs) it is important that the destination repository uses the same prefixes as are being used in the package.
+
+Although you can redefine a namespace URL to be mapped from another prefix in the [FileVault Document View (DocView) Format](./docview.html) this will only be used during parsing that file (i.e. once during import) but is not persisted in the destination repository. Particularly it won't affect:
+
+1. property values containing the JCR standard form
+2. the standard form of JCR paths containing namespaced items
diff --git a/src/site/markdown/privileges.md b/src/site/markdown/privileges.md
index c31f979..86893f2 100644
--- a/src/site/markdown/privileges.md
+++ b/src/site/markdown/privileges.md
@@ -18,7 +18,9 @@
 Privileges
 ===========
 
-Packages can register custom [JCR privileges](https://s.apache.org/jcr-2.0-spec/16_Access_Control_Management.html#16.2%20Privilege%20Discovery) during import by carrying a `META-INF/vault/privileges.xml` file. 
+Packages can register custom [JCR privileges](https://s.apache.org/jcr-2.0-spec/16_Access_Control_Management.html#16.2%20Privilege%20Discovery) during import by carrying a `META-INF/vault/privileges.xml` file.  
+
+Its DTD is defined as
 
 ```xml
 <!DOCTYPE privileges [
@@ -31,4 +33,8 @@ Packages can register custom [JCR privileges](https://s.apache.org/jcr-2.0-spec/
 ]>
 ```
 
+The implementation is leveraging the [Jackrabbit API PrivilegeManager](
+
+The privilege **name** must be given in [qualified form](https://s.apache.org/jcr-2.0-spec/3_Repository_Model.html#3.2.5.2%20Qualified%20Form). Every element may carry [XML namespace declarations](https://www.w3.org/TR/2006/REC-xml-names11-20060816/#ns-decl) which are automatically registered in the destination repository during import as well. This should be used when the privilege is using a custom namespace URL.
+
 Aggregate privileges can be registered with the additional element `contains` which should reference an existing privilege name.