You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sis.apache.org by de...@apache.org on 2023/09/28 16:20:27 UTC
[sis] 04/04: Convert text files and HTML files to Markdown format when those files were not used for tests. The intend is to have a less formats for documentation (Javadoc, Markdown, MathML), so all `*.txt` files can be considered as used in tests.
This is an automated email from the ASF dual-hosted git repository.
desruisseaux pushed a commit to branch geoapi-4.0
in repository https://gitbox.apache.org/repos/asf/sis.git
commit 2f6a07007c31e417d5f78bdbf419126c20a743ff
Author: Martin Desruisseaux <ma...@geomatys.com>
AuthorDate: Thu Sep 28 18:18:33 2023 +0200
Convert text files and HTML files to Markdown format when those files were not used for tests.
The intend is to have a less formats for documentation (Javadoc, Markdown, MathML),
so all `*.txt` files can be considered as used in tests.
---
.../sis/buildtools/gradle/ModularCompilation.java | 24 +--
.../main/org/apache/sis/feature/README.md | 77 ++++++++++
.../main/org/apache/sis/feature/benchmarks.html | 114 --------------
.../main/org/apache/sis/xml/README.md | 78 ++++++++++
.../sis/xml/bind/gco/ObjectIdentification.html | 59 --------
.../sis/xml/bind/gco/ObjectIdentification.md | 31 ++++
.../main/org/apache/sis/xml/readme.html | 98 ------------
.../sis/metadata/internal/AxisDirectionsTest.md | 3 +
.../sis/metadata/internal/AxisDirectionsTest.txt | 3 -
.../src/org.apache.sis.openoffice/bundle/README.md | 100 ++++++++++++
.../bundle/build-instruction.html | 119 ---------------
.../apache/sis/parameter/AbstractParameterValue.md | 5 +
.../sis/parameter/AbstractParameterValue.txt | 5 -
.../sis/referencing/factory/sql/EPSG_README.md | 7 +
.../sis/referencing/factory/sql/EPSG_README.txt | 7 -
.../sis/referencing/operation/builder/README.md | 33 ++++
.../sis/referencing/operation/builder/readme.html | 50 ------
...c3DtoVertical.txt => Geographic3DtoVertical.md} | 6 +-
.../transform/SpecializableTransform1D.md | 3 +
.../transform/SpecializableTransform1D.txt | 3 -
.../sis/xml/bind/referencing/SC_GeographicCRS.md | 4 +
.../sis/xml/bind/referencing/SC_GeographicCRS.txt | 4 -
.../sis/referencing/factory/sql/epsg/README.md | 133 ++++++++++++++++
.../sis/referencing/factory/sql/epsg/package.html | 168 ---------------------
.../shapefile/jdbc/{readme.txt => README.md} | 2 +
25 files changed, 487 insertions(+), 649 deletions(-)
diff --git a/buildSrc/src/org.apache.sis.buildtools/main/org/apache/sis/buildtools/gradle/ModularCompilation.java b/buildSrc/src/org.apache.sis.buildtools/main/org/apache/sis/buildtools/gradle/ModularCompilation.java
index 5979bc45b5..ea85e0bbef 100644
--- a/buildSrc/src/org.apache.sis.buildtools/main/org/apache/sis/buildtools/gradle/ModularCompilation.java
+++ b/buildSrc/src/org.apache.sis.buildtools/main/org/apache/sis/buildtools/gradle/ModularCompilation.java
@@ -170,6 +170,7 @@ final class ModularCompilation extends Conventions {
/**
* File extensions of resources to not copy.
+ * In addition, everything in {@code doc-files} sub-directories will be excluded.
*
* @todo Reduce this list to IDL and Markdown by converting HTML and text files.
*/
@@ -177,8 +178,7 @@ final class ModularCompilation extends Conventions {
"tmp", "bak", "log", // Same extensions than in `.gitignore`.
"idl", // Source code for OpenOffice add-in.
"md", // Notes in Markdown format.
- "html", // Richer alternative to Markdown.
- "txt"); // Simpler alternative to Markdown.
+ "html"); // Richer alternative to Markdown.
/**
* Compiles the international resources that are found in all modules.
@@ -262,22 +262,12 @@ final class ModularCompilation extends Conventions {
* @return {@code true} for copying or {@code false} for ignoring.
*/
private static boolean include(File resource) {
- String ext = resource.getName();
- ext = ext.substring(ext.lastIndexOf('.') + 1);
- if (EXCLUDE_RESOURCES.contains(ext)) {
- if (ext.equals("txt")) {
- /*
- * Special case: include text file for tests.
- * TODO: remove that special case. See EXCLUDE_RESOURCES comment.
- */
- while ((resource = resource.getParentFile()) != null) {
- if (resource.getName().equals(TEST_DIRECTORY)) {
- return true;
- }
- }
- }
+ final File parent = resource.getParentFile();
+ if (parent != null && parent.getName().equals("doc-files")) {
return false;
}
- return true;
+ String ext = resource.getName();
+ ext = ext.substring(ext.lastIndexOf('.') + 1);
+ return !EXCLUDE_RESOURCES.contains(ext);
}
}
diff --git a/endorsed/src/org.apache.sis.feature/main/org/apache/sis/feature/README.md b/endorsed/src/org.apache.sis.feature/main/org/apache/sis/feature/README.md
new file mode 100644
index 0000000000..1a47bd6abf
--- /dev/null
+++ b/endorsed/src/org.apache.sis.feature/main/org/apache/sis/feature/README.md
@@ -0,0 +1,77 @@
+# Design goals and benchmarks
+
+A major design goal of `org.apache.sis.feature` is to reduce memory usage.
+Consider a ShapeFile or a database table with millions of records.
+Each record is represented by one `Feature` instance.
+Sophisticated `DataStore` implementations will create and discard `Feature`
+instances on the fly, but not all `DataStore` do that.
+As a safety, Apache SIS tries to implement `Feature` in a way that allow applications
+to scale higher before to die with an `OutOfMemoryError`.
+
+A simple `Feature` implementation would use a `java.util.HashMap` as below:
+
+```
+class SimpleFeature {
+ final Map<String,Object> attributes = new HashMap<>(8);
+}
+```
+
+The above `SimpleFeature` does not supports explicitly multi-valued properties and metadata
+about the properties (admittedly multi-values could be stored as `java.util.Collection`,
+but this approach has implications on the way we ensure type safety).
+A more complete but still straightforward implementation could be:
+
+```
+class ComplexFeature {
+ final Map<String,Property> properties = new HashMap<>(8);
+}
+class Property {
+ final List<String> values = new ArrayList<>(4);
+}
+```
+
+A more sophisticated implementation would take advantage of our knowledge that all records in
+a table have the same attribute names, and that the vast majority of attributes are singleton.
+Apache SIS uses this knowledge, together with lazy instantiations of `Property`.
+The above simple implementation has been compared with the Apache SIS one in a micro-benchmark
+consisting of the following steps:
+
+* Defines the following feature type:
+ * `city` : `String` (8 characters)
+ * `latitude` : `Float`
+ * `longitude` : `Float`
+* Launch the micro-benchmarks in Java with a fixed amount of memory.
+ This micro-benchmarks used the following command line with Java 1.8.0_05 on MacOS X 10.7.5:
+ `java -Xms100M -Xmx100M ` _command_
+* Creates `Feature` instances of the above type and store them in a list of fixed size
+ until we get `OutOfMemoryError`.
+
+
+## Results and discussion
+The benchmarks have been executed about 8 times for each implementation (_simple_ and _complex_ versus _SIS_).
+Results of the simple feature implementation were very stable.
+But results of the SIS implementation randomly fall in two modes, one twice faster than the other
+(maybe depending on which optimizations have been chosen by the HotSpot compiler):
+
+```
+ Count Time (seconds)
+Run mean σ mean σ
+ComplexFeature: 194262 ± 2 21.8 ± 0.9
+SimpleFeature: 319426 ± 4 22.5 ± 0.6
+SIS (mode 1): 639156 ± 40 25.6 ± 0.4
+SIS (mode 2): 642437 ± 7 12.1 ± 0.8
+```
+
+For the trivial `FeatureType` used in this benchmark, the Apache SIS implementation
+can load twice more `Feature` instances than the `HashMap<String,Object>`-based
+implementation before the application get an `OutOfMemoryError`.
+We presume that this is caused by the `Map.Entry` instances
+that `HashMap` must create internally for each attribute.
+Compared to `ComplexFeature`, SIS allows 3.3 times more instances
+while being functionally equivalent.
+
+The speed comparisons are subject to more cautions,
+in part because each run has created a different amount of instances before the test stopped.
+So even the slowest SIS case would be almost twice faster than `SimpleFeature`
+because it created two times more instances in an equivalent amount of time.
+However, this may be highly dependent on garbage collector activities (it has not been verified).
diff --git a/endorsed/src/org.apache.sis.feature/main/org/apache/sis/feature/benchmarks.html b/endorsed/src/org.apache.sis.feature/main/org/apache/sis/feature/benchmarks.html
deleted file mode 100644
index 83fca069c0..0000000000
--- a/endorsed/src/org.apache.sis.feature/main/org/apache/sis/feature/benchmarks.html
+++ /dev/null
@@ -1,114 +0,0 @@
-<!DOCTYPE html>
-<html>
- <head>
- <title>Design goals and benchmarks</title>
- <meta charset="UTF-8">
- <meta name="viewport" content="width=device-width, initial-scale=1.0">
- </head>
- <body>
- <h1>Design goals and benchmarks</h1>
- <p>A major design goal of <code>org.apache.sis.feature</code> is to reduce memory usage.
- Consider a ShapeFile or a database table with millions of records.
- Each record is represented by one <code>Feature</code> instance.
- Sophisticated <code>DataStore</code> implementations will create and discard <code>Feature</code>
- instances on the fly, but not all <code>DataStore</code> do that.
- As a safety, Apache SIS tries to implement <code>Feature</code> in a way that allow applications
- to scale higher before to die with an <code>OutOfMemoryError</code>.</p>
-
- <p>A simple <code>Feature</code> implementation would use a <code>java.util.HashMap</code> as below:</p>
- <blockquote><pre>class SimpleFeature {
- final Map<String,Object> attributes = new HashMap<>(8);
-}</pre></blockquote>
-
- <p>The above <code>SimpleFeature</code> does not supports explicitly multi-valued properties and metadata
- about the properties (admittedly multi-values could be stored as <code>java.util.Collection</code>,
- but this approach has implications on the way we ensure type safety).
- A more complete but still straightforward implementation could be:</p>
- <blockquote><pre>class ComplexFeature {
- final Map<String,Property> properties = new HashMap<>(8);
-}
-class Property {
- final List<String> values = new ArrayList<>(4);
-}</pre></blockquote>
-
-
- <p>A more sophisticated implementation would take advantage of our knowledge that all records in a table have the
- same attribute names, and that the vast majority of attributes are singleton.
- Apache SIS uses this knowledge, together with lazy instantiations of <code>Property</code>.
- The above simple implementation has been compared with the Apache SIS one in a micro-benchmark consisting of the
- following steps:</p>
-
- <ol>
- <li>
- <p>Defines the following feature type:</p>
- <table style="border: 1px solid">
- <tr><th>Attribute</th> <th> </th> <th>Value class</th></tr>
- <tr><td><code>city</code></td> <td>:</td> <td><code>String</code> (8 characters)</td></tr>
- <tr><td><code>latitude</code></td> <td>:</td> <td><code>Float</code></td></tr>
- <tr><td><code>longitude</code></td> <td>:</td> <td><code>Float</code></td></tr>
- </table>
- </li>
- <li>
- <p>Launch the micro-benchmarks in Java with a fixed amount of memory.
- This micro-benchmarks used the following command line with Java 1.8.0_05 on MacOS X 10.7.5:</p>
- <code>java -Xms100M -Xmx100M </code> <i>command</i>
- </li>
- <li>
- <p>Creates <code>Feature</code> instances of the above type and store them in a list of fixed size
- until we get <code>OutOfMemoryError</code>.</p>
- </li>
- </ol>
-
- <h2>Results and discussion</h2>
- The benchmarks have been executed about 8 times for each implementation
- (<cite>simple</cite> and <cite>complex</cite> versus <cite>SIS</cite>).
- Results of the simple feature implementation were very stable.
- But results of the SIS implementation randomly fall in two modes, one twice faster than the other
- (maybe depending on which optimizations have been chosen by the HotSpot compiler):
-
- <blockquote><table style="border: 1px solid">
- <tr>
- <th></th>
- <th colspan="2">Count</th>
- <th colspan="2">Time (seconds)</th>
- </tr>
- <tr>
- <th>Run</th>
- <th>mean</th> <th>σ</th>
- <th>mean</th> <th>σ</th>
- </tr>
- <tr>
- <td><code>ComplexFeature</code>:</td>
- <td style="text-align: right">194262</td> <td style="text-align: right">± 2</td>
- <td style="text-align: right">21.8</td> <td style="text-align: right">± 0.9</td>
- </tr>
- <tr>
- <td><code>SimpleFeature</code>:</td>
- <td style="text-align: right">319426</td> <td style="text-align: right">± 4</td>
- <td style="text-align: right">22.5</td> <td style="text-align: right">± 0.6</td>
- </tr>
- <tr>
- <td>SIS (mode 1):</td>
- <td style="text-align: right">639156</td> <td style="text-align: right">± 40</td>
- <td style="text-align: right">25.6</td> <td style="text-align: right">± 0.4</td>
- </tr>
- <tr>
- <td>SIS (mode 2):</td>
- <td style="text-align: right">642437</td> <td style="text-align: right">± 7</td>
- <td style="text-align: right">12.1</td> <td style="text-align: right">± 0.8</td>
- </tr>
- </table></blockquote>
-
- <p>For the trivial <code>FeatureType</code> used in this benchmark, the Apache SIS implementation can load
- twice more <code>Feature</code> instances than the <code>HashMap<String,Object></code>-based
- implementation before the application get an <code>OutOfMemoryError</code>.
- We presume that this is caused by the <code>Map.Entry</code> instances that <code>HashMap</code> must
- create internally for each attribute.
- Compared to <code>ComplexFeature</code>, SIS allows 3.3 times more instances while being functionally equivalent.</p>
-
- <p>The speed comparisons are subject to more cautions, in part because each run has created a different amount
- of instances before the test stopped. So even the slowest SIS case would be almost twice faster than
- <code>SimpleFeature</code> because it created two times more instances in an equivalent amount of time.
- However, this may be highly dependent on garbage collector activities (it has not been verified).</p>
- </body>
-</html>
diff --git a/endorsed/src/org.apache.sis.metadata/main/org/apache/sis/xml/README.md b/endorsed/src/org.apache.sis.metadata/main/org/apache/sis/xml/README.md
new file mode 100644
index 0000000000..57b572124b
--- /dev/null
+++ b/endorsed/src/org.apache.sis.metadata/main/org/apache/sis/xml/README.md
@@ -0,0 +1,78 @@
+# Syntax of RenameOnImport/Export files
+
+**WARNING: the syntax documented in this page is not committed API and may change in any future SIS version.**
+
+This package provides two files in the `resources/org/apache/sis/xml/` folder:
+`RenameOnImport.lst` and `RenameOnExport.lst`.
+Those files are used by `TransformingReader.java` and `TransformingWriter.java` respectively
+for converting XML namespaces between new specifications (ISO 19115-3:2016 and ISO 19115-4) and old specifications
+(ISO 19139:2007 and ISO 19115-2:2009).
+The JAXB annotations in Apache SIS use the newer specifications.
+The `Rename*.lst` files are needed only when reading or writing to older specifications.
+Those files are used for performing the work of a lightweight XSLT engine.
+Both share the same syntax:
+
+* Lines starting with "*" character specify the legacy namespaces containing elements to rename.
+* Lines with zero-space indentation are namespace URIs.
+* Lines with one-space indentation are XML type names.
+* Lines with two-spaces indentation are property names.
+* The "/" character in "_before_/_after_" means that a property name needs to be changed.
+ _Before_ is the name before the renaming process and _after_ is the name after the renaming process.
+* The ":" character in "_Child_ : _Parent_" means that a subclass inherits all properties from a parent class.
+ The _parent_ must be defined before the _child_ (no forward references).
+ This is used for avoiding to repeat all super-class properties in sub-classes.
+ It has no other meaning, i.e. the class hierarchy is not retained at runtime.
+* The "!" character in "_Class_ !_reason_" skips the association of current namespace to that class
+ (but namespace will still be associated to the properties). _Reason_ is a free text.
+ This is used with deprecated classes that do not exist anymore in the new namespace
+ (often because the class has been renamed).
+
+For example, the following snippet from `RenameOnImport.lst` declares that the `Citation.title`,
+`Citation.edition` and `Address.country` properties are defined in the **`cit`** namespace,
+while the `Extent.description` property is defined in the **`gex`** namespace.
+Those information are required when reading a file encoded by the old standards
+because almost all properties where in the single `gmd` namespace.
+Properties not listed will have their namespace unchanged (e.g. still in the old `gmd` namespace).
+Classes that did not existed in old standard should not be listed.
+
+```
+# Legacy namespace containing elements to rename:
+* http://www.isotc211.org/2005/gmd
+
+# New namespaces:
+http://standards.iso.org/iso/19115/-3/**cit**/1.0
+ CI_Citation
+ title
+ edition
+ CI_Address
+ country
+http://standards.iso.org/iso/19115/-3/**gex**/1.0
+ EX_Extent
+ description
+```
+
+In general those information are used for converting only the *namespaces*, the class and property names are unchanged.
+But in the special case where the "_before_/_after_" syntax is used, then class and/or property names are also changed.
+In the following example, the `DQ_Scope` type is renamed `MD_Scope` but with attributes of the same name.
+Then the `Georectified.centerPoint` attribute (from the old standard)
+is renamed as `Georectified.centrePoint` (new standard).
+
+```
+http://standards.iso.org/iso/19115/-3/**mcc**/1.0
+ DQ_Scope/MD_Scope
+ extent
+ level
+ levelDescription
+http://standards.iso.org/iso/19115/-3/**msr**/1.0
+ MI_Georectified
+ centerPoint/centrePoint
+```
+
+Conversely, when writing a file, some additional renaming can be applied *after* the namespaces have been renamed to `gmd`.
+The following snippet from `RenameOnExport.lst` performs the converse of the property renaming shown in previous example:
+
+```
+http://www.isotc211.org/2005/gmd
+ MD_Georectified
+ centrePoint/centerPoint
+```
diff --git a/endorsed/src/org.apache.sis.metadata/main/org/apache/sis/xml/bind/gco/ObjectIdentification.html b/endorsed/src/org.apache.sis.metadata/main/org/apache/sis/xml/bind/gco/ObjectIdentification.html
deleted file mode 100644
index 5a21c11630..0000000000
--- a/endorsed/src/org.apache.sis.metadata/main/org/apache/sis/xml/bind/gco/ObjectIdentification.html
+++ /dev/null
@@ -1,59 +0,0 @@
-<!DOCTYPE html>
-
-<!--
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
--->
-
-<html>
- <head>
- <title>ObjectIdentification</title>
- <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
- </head>
- <body>
- <h1>Class ObjectIdentification</h1>
- <p>The <code>org.apache.sis.xml.bind.gco</code> package conceptually defines two complementary objects:
- <code>ObjectIdentification</code> and <code>ObjectReference</code>. However, only the latter is defined by
- a Java class, because the former is implicitly defined by the classes in the public API of SIS.
- This page contains the information that we would have put in <code>ObjectIdentification</code> Javadoc
- is such class existed.</p>
-
- <h2>Overview</h2>
- <p>The <code>gco:ObjectIdentification</code> XML attribute group is implicitly included
- by all metadata types defined in the <code>org.apache.sis.metadata.iso</code> packages.
- The attributes of interest defined in this group are <code>id</code> and <code>uuid</code>.</p>
-
- <p>This <code>gco:ObjectIdentification</code> group is complementary to <code>gco:ObjectReference</code>,
- which defines the <code>xlink</code> and <code>uuidref</code> attributes to be supported by all metadata
- wrappers in the private <code>org.apache.sis.xml.bind.metadata</code> package and sub-packages.</p>
-
- <h2>Difference between <code>gml:id</code> and <code>gco:uuid</code></h2>
- <p>The <a href="https://www.seegrid.csiro.au/wiki/bin/view/AppSchemas/GmlIdentifiers">GML identifiers</a> page said:</p>
- <ul>
- <li><code>id</code> is a standard <strong>GML</strong> attribute available on every object-with-identity.
- It has type=<code>"xs:ID"</code> - i.e. it is a fragment identifier, unique within document scope only,
- for internal cross-references. It is not useful by itself as a persistent unique identifier.</li>
-
- <li><code>uuid</code> is an optional attribute available on every object-with-identity, provided in
- the <strong>GCO</strong> schemas that implement ISO 19115 in XML. May be used as a persistent
- unique identifier, but only available within GCO context.</li>
- </ul>
-
- <p>However, according the <a href="https://www.isotc211.org/2005/gco/gcoBase.xsd">OGC/ISO schema</a>,
- those identifiers seem to be defined in the GCO schema.</p>
- </body>
-</html>
diff --git a/endorsed/src/org.apache.sis.metadata/main/org/apache/sis/xml/bind/gco/ObjectIdentification.md b/endorsed/src/org.apache.sis.metadata/main/org/apache/sis/xml/bind/gco/ObjectIdentification.md
new file mode 100644
index 0000000000..ecac6c8788
--- /dev/null
+++ b/endorsed/src/org.apache.sis.metadata/main/org/apache/sis/xml/bind/gco/ObjectIdentification.md
@@ -0,0 +1,31 @@
+# Class ObjectIdentification
+
+The `org.apache.sis.xml.bind.gco` package conceptually defines two complementary objects:
+`ObjectIdentification` and `ObjectReference`. However, only the latter is defined by a Java class,
+because the former is implicitly defined by the classes in the public API of SIS.
+This page contains the information that we would have put in `ObjectIdentification` Javadoc
+if such class existed.
+
+## Overview
+
+The `gco:ObjectIdentification` XML attribute group is implicitly included
+by all metadata types defined in the `org.apache.sis.metadata.iso` packages.
+The attributes of interest defined in this group are `id` and `uuid`.
+
+This `gco:ObjectIdentification` group is complementary to `gco:ObjectReference`,
+which defines the `xlink` and `uuidref` attributes to be supported by all metadata
+wrappers in the private `org.apache.sis.xml.bind.metadata` package and sub-packages.
+
+## Difference between `gml:id` and `gco:uuid`
+
+GML identifiers have the following properties:
+
+* `id` is a standard **GML** attribute available on every object-with-identity.
+ It has type=`"xs:ID"` - i.e. it is a fragment identifier, unique within document scope only,
+ for internal cross-references. It is not useful by itself as a persistent unique identifier.
+* `uuid` is an optional attribute available on every object-with-identity, provided in the
+ **GCO** schemas that implement ISO 19115 in XML. May be used as a persistent unique identifier,
+ but only available within GCO context.
+
+However, according the [OGC/ISO schema](https://www.isotc211.org/2005/gco/gcoBase.xsd),
+those identifiers seem to be defined in the GCO schema.
diff --git a/endorsed/src/org.apache.sis.metadata/main/org/apache/sis/xml/readme.html b/endorsed/src/org.apache.sis.metadata/main/org/apache/sis/xml/readme.html
deleted file mode 100644
index 4b764ce790..0000000000
--- a/endorsed/src/org.apache.sis.metadata/main/org/apache/sis/xml/readme.html
+++ /dev/null
@@ -1,98 +0,0 @@
-<!DOCTYPE html>
-<html>
- <head>
- <title>Syntax of Rename files</title>
- <meta charset="UTF-8">
- <style>
- p, code, pre {
- font-size: 18px;
- }
- p {
- text-align: justify;
- }
- pre {
- border-left-style: solid;
- border-left-color: darkgray;
- }
- </style>
- </head>
- <body>
- <h1>Syntax of RenameOnImport/Export files</h1>
- <p>
- <b>WARNING: the syntax documented in this page is not committed API and may change in any future SIS version.</b>
- </p>
- <p>
- This package provides two files in the <code>resources/org/apache/sis/xml/</code> folder:
- <code>RenameOnImport.lst</code> and <code>RenameOnExport.lst</code>.
- Those files are used by <code>TransformingReader.java</code> and <code>TransformingWriter.java</code> respectively
- for converting XML namespaces between new specifications (ISO 19115-3:2016 and ISO 19115-4) and old specifications
- (ISO 19139:2007 and ISO 19115-2:2009). The JAXB annotations in Apache SIS use the newer specifications.
- The <code>Rename*.lst</code> files are needed only when reading or writing to older specifications.
- Those files are used for performing the work of a lightweight XSLT engine.
- Both share the same syntax:
- </p>
- <ul>
- <li>Lines starting with "*" character specify the legacy namespaces containing elements to rename.</li>
- <li>Lines with zero-space indentation are namespace URIs.</li>
- <li>Lines with one-space indentation are XML type names.</li>
- <li>Lines with two-spaces indentation are property names.</li>
- <li>The "/" character in "<var>before</var>/<var>after</var>" means that a property name needs to be changed.
- <var>Before</var> is the name before the renaming process and <var>after</var> is the name after the renaming process.</li>
- <li>The ":" character in "<var>Child</var> : <var>Parent</var>" means that a subclass inherits all properties from a parent class.
- The <var>parent</var> must be defined before the <var>child</var> (no forward references).
- This is used for avoiding to repeat all super-class properties in sub-classes.
- It has no other meaning, i.e. the class hierarchy is not retained at runtime.</li>
- <li>The "!" character in "<var>Class</var> !<var>reason</var>" skips the association of current namespace to that class
- (but namespace will still be associated to the properties). <var>Reason</var> is a free text.
- This is used with deprecated classes that do not exist anymore in the new namespace
- (often because the class has been renamed).</li>
- </ul>
- <p>
- For example, the following snippet from <code>RenameOnImport.lst</code> declares that the <code>Citation.title</code>,
- <code>Citation.edition</code> and <code>Address.country</code> properties are defined in the <b><code>cit</code></b> namespace,
- while the <code>Extent.description</code> property is defined in the <b><code>gex</code></b> namespace.
- Those information are required when reading a file encoded by the old standards
- because almost all properties where in the single <code>gmd</code> namespace.
- Properties not listed will have their namespace unchanged (e.g. still in the old <code>gmd</code> namespace).
- Classes that did not existed in old standard should not be listed.
- </p>
- <blockquote><pre># Legacy namespace containing elements to rename:
-* http://www.isotc211.org/2005/gmd
-
-# New namespaces:
-http://standards.iso.org/iso/19115/-3/<b>cit</b>/1.0
- CI_Citation
- title
- edition
- CI_Address
- country
-http://standards.iso.org/iso/19115/-3/<b>gex</b>/1.0
- EX_Extent
- description</pre></blockquote>
-
- <p>
- In general those information are used for converting only the <em>namespaces</em>; the class and property names are unchanged.
- But in the special case where the "<var>before</var>/<var>after</var>" syntax is used, then class and/or property names are also changed.
- In the following example, the <code>DQ_Scope</code> type is renamed <code>MD_Scope</code> but with attributes of the same name.
- Then the <code>Georectified.centerPoint</code> attribute (from the old standard)
- is renamed as <code>Georectified.centrePoint</code> (new standard).
- </p>
-
- <blockquote><pre>http://standards.iso.org/iso/19115/-3/<b>mcc</b>/1.0
- DQ_Scope/MD_Scope
- extent
- level
- levelDescription
-http://standards.iso.org/iso/19115/-3/<b>msr</b>/1.0
- MI_Georectified
- centerPoint/centrePoint</pre></blockquote>
-
- <p>
- Conversely, when writing a file, some additional renaming can be applied <em>after</em> the namespaces have been renamed to <code>gmd</code>.
- The following snippet from <code>RenameOnExport.lst</code> performs the converse of the property renaming shown in previous example:
- </p>
- <blockquote><pre>http://www.isotc211.org/2005/gmd
- MD_Georectified
- centrePoint/centerPoint</pre></blockquote>
- </body>
-</html>
diff --git a/endorsed/src/org.apache.sis.metadata/test/org/apache/sis/metadata/internal/AxisDirectionsTest.md b/endorsed/src/org.apache.sis.metadata/test/org/apache/sis/metadata/internal/AxisDirectionsTest.md
new file mode 100644
index 0000000000..d9f2f41559
--- /dev/null
+++ b/endorsed/src/org.apache.sis.metadata/test/org/apache/sis/metadata/internal/AxisDirectionsTest.md
@@ -0,0 +1,3 @@
+The `AxisDirections` class is defined in the `org.apache.sis.metadata` module,
+but tested in the `org.apache.sis.referencing` module because the tests use
+constants defined in the referencing module.
diff --git a/endorsed/src/org.apache.sis.metadata/test/org/apache/sis/metadata/internal/AxisDirectionsTest.txt b/endorsed/src/org.apache.sis.metadata/test/org/apache/sis/metadata/internal/AxisDirectionsTest.txt
deleted file mode 100644
index e3ef28a6d6..0000000000
--- a/endorsed/src/org.apache.sis.metadata/test/org/apache/sis/metadata/internal/AxisDirectionsTest.txt
+++ /dev/null
@@ -1,3 +0,0 @@
-The AxisDirections class is defined in the `org.apache.sis.metadata` module,
-but tested in the 'org.apache.sis.referencing' module because the tests use
-constants defined in the referencing module.
diff --git a/endorsed/src/org.apache.sis.openoffice/bundle/README.md b/endorsed/src/org.apache.sis.openoffice/bundle/README.md
new file mode 100644
index 0000000000..39993eeb62
--- /dev/null
+++ b/endorsed/src/org.apache.sis.openoffice/bundle/README.md
@@ -0,0 +1,100 @@
+# OpenOffice add-in build instructions
+
+All `XFoo` Java interfaces are generated from IDL files with the same name.
+As long as `XFoo` Java/IDL interfaces are not modified, there is no need for the OpenOffice SDK.
+But if any `XFoo` interface is modified, then the steps documented below must be done.
+The last step shall be executed on the client machine
+(users can also use the _"Tools / Package manager"_ menu from OpenOffice GUI).
+
+Replace _ooo-path_ by the path to the OpenOffice installation directory.
+That directory should contain the `program` sub-directories.
+The OpenOffice SDK shall be installed as a sub-directory of the OpenOffice root directory.
+If the name of that SDK directory is different than `OpenOffice_SDK`,
+then modify the `OO_SDK_HOME` value below accordingly.
+
+```
+export OFFICE_BASE_HOME=ooo-path
+export OO_SDK_HOME=$OFFICE_BASE_HOME/OpenOffice_SDK
+export PATH=$OFFICE_BASE_HOME/program:$OO_SDK_HOME/bin:$PATH
+```
+
+
+## Compiles the UNO `*.urd` binary file
+
+The following command generates `*.urd` files (to be deleted later).
+The `-C` option is for including additional service information,
+the `-cid` option is for checking if identifiers fulfill the UNO naming requirements, and
+the `-w` option is for displaying warning messages.
+
+```
+cd endorsed/src/org.apache.sis.openoffice/main
+idlc -C -cid -w -I $OO_SDK_HOME/idl org/apache/sis/openoffice/*.idl
+```
+
+
+### MacOS troubleshooting
+
+if the above command fails with a message like “`dyld: Library not loaded: @executable_path/libreg.dylib.3`
+(…) `Reason: image not found`”, try adding the following environment variable:
+
+```
+export DYLD_FALLBACK_LIBRARY_PATH=$OFFICE_BASE_HOME/program
+```
+
+
+## Compiles the UNO `*.rdb` registry file and the `*.class` file
+
+The `*.rdb` and `*.class` files generated by the following commands
+will need to be committed in the source code repository.
+Committing compilation results is usually not recommended, but in this particular case
+most users will not have the necessary installation for producing those files themselves
+(including the `*.class` files, which is not the usual `javac` output).
+
+```
+regmerge ../bundle/sis.rdb /UCR org/apache/sis/openoffice/*.urd
+rm org/apache/sis/openoffice/*.urd
+cd ../bundle
+javamaker -BUCR sis.rdb $OFFICE_BASE_HOME/program/types.rdb -Torg.apache.sis.openoffice.XReferencing
+```
+
+
+## Derives a `*.java` source from the `*.class` file
+
+Following command can be skipped if the API defined by `*.idl` files did not changed.
+If this command is executed, the result will be sent to the console.
+Developer need to bring any changes to the Java interface manually.
+
+```
+javap org.apache.sis.openoffice.XReferencing
+```
+
+
+## Build
+
+```
+cd ../../..
+gradle test
+```
+
+
+## Test in Apache OpenOffice
+
+Launch:
+
+```
+cd target
+unopkg add apache-sis-1.1-SNAPSHOT.oxt --log-file log.txt
+scalc -env:RTL_LOGFILE=log.txt
+```
+
+If not already done, configure Java runtime with
+_Tools_ → _Options…_ → _Advanced_ → _Java options_ → _Parameters_
+and specify the following parameters:
+
+```
+-agentlib:jdwp=transport=dt_socket,server=y,address=8000,suspend=n
+```
+
+It allows to attach the IDE debugger to the Java virtual machine running in LibreOffice.
+For example, with NetBeans, use _Debug_ → _Attach debugger…_,
+select "Socket attach" as the transport and 8000 as the port number.
diff --git a/endorsed/src/org.apache.sis.openoffice/bundle/build-instruction.html b/endorsed/src/org.apache.sis.openoffice/bundle/build-instruction.html
deleted file mode 100644
index ffa8e0c556..0000000000
--- a/endorsed/src/org.apache.sis.openoffice/bundle/build-instruction.html
+++ /dev/null
@@ -1,119 +0,0 @@
-<!DOCTYPE html>
-
-<!--
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
--->
-
-<html>
- <head>
- <title>OpenOffice add-in build instructions</title>
- <meta charset="UTF-8">
- </head>
- <body>
- <h1>OpenOffice add-in build instructions</h1>
- <p>
- All <code>XFoo</code> Java interfaces are generated from IDL files with the same name.
- As long as <code>XFoo</code> Java/IDL interfaces are not modified, there is no need for the OpenOffice SDK.
- But if any <code>XFoo</code> interface is modified, then the steps documented below must be done.
- The last step shall be executed on the client machine
- (users can also use the <i>"Tools / Package manager"</i> menu from OpenOffice GUI).
- </p>
-
- <p>
- Replace <var>ooo-path</var> by the path to the OpenOffice installation directory.
- That directory should contain the <code>program</code> sub-directories
- The OpenOffice SDK shall be installed as a sub-directory of the OpenOffice root directory.
- If the name of that SDK directory is different than <code>OpenOffice_SDK</code>,
- then modify the <code>OO_SDK_HOME</code> value below accordingly.
- </p>
-
-<blockquote><pre>export OFFICE_BASE_HOME=ooo-path
-export OO_SDK_HOME=$OFFICE_BASE_HOME/OpenOffice_SDK
-export PATH=$OFFICE_BASE_HOME/program:$OO_SDK_HOME/bin:$PATH</pre></blockquote>
-
-
- <h2>Compiles the UNO <code>*.urd</code> binary file:</h2>
- <p>
- The following command generates <code>*.urd</code> files (to be deleted later).
- The <code>-C</code> option is for including additional service information,
- the <code>-cid</code> option is for checking if identifiers fulfill the UNO naming requirements, and
- the <code>-w</code> option is for displaying warning messages.
- </p>
-<blockquote><pre>cd endorsed/src/org.apache.sis.openoffice/main
-idlc -C -cid -w -I $OO_SDK_HOME/idl org/apache/sis/openoffice/*.idl</pre></blockquote>
-
- <div style="font-size:smaller"><b>MacOS troubleshooting:</b>
- if the above command fails with a message like:
-
- <blockquote>“<code>dyld: Library not loaded: @executable_path/libreg.dylib.3</code>
- (…) <code>Reason: image not found</code>”</blockquote>
-
- try adding the following environment variable:
-
- <blockquote><pre>export DYLD_FALLBACK_LIBRARY_PATH=$OFFICE_BASE_HOME/program</pre></blockquote>
- </div>
-
-
-<h2>Compiles the UNO <code>*.rdb</code> registry file and the <code>*.class</code> file:</h2>
-<p>
- The <code>*.rdb</code> and <code>*.class</code> files generated by the following commands
- will need to be committed in the source code repository.
- Committing compilation results is usually not recommended, but in this particular case
- most users will not have the necessary installation for producing those files themselves
- (including the <code>*.class</code> files, which is not the usual <code>javac</code> output).
-</p>
-<blockquote><pre>regmerge ../bundle/sis.rdb /UCR org/apache/sis/openoffice/*.urd
-rm org/apache/sis/openoffice/*.urd
-cd ../bundle
-javamaker -BUCR sis.rdb $OFFICE_BASE_HOME/program/types.rdb -Torg.apache.sis.openoffice.XReferencing</pre></blockquote>
-
-
-<h2>Derives a <code>*.java</code> source from the <code>*.class</code> file:</h2>
-<p>
- Following command can be skipped if the API defined by <code>*.idl</code> files did not changed.
- If this command is executed, the result will be sent to the console.
- Developer need to bring any changes to the Java interface manually.
-</p>
-<blockquote><pre>javap org.apache.sis.openoffice.XReferencing</pre></blockquote>
-
-
-<h2>Build:</h2>
-<blockquote><pre>cd ../../..
-mvn install</pre></blockquote>
-
-
-<h2>Test in Apache OpenOffice:</h2>
-<p>Launch:</p>
-<blockquote><pre>cd target
-unopkg add apache-sis-1.1-SNAPSHOT.oxt --log-file log.txt
-scalc -env:RTL_LOGFILE=log.txt</pre></blockquote>
-
-<p>If not already done, configure Java runtime with
- <i>Tools</i> → <i>Options…</i> → <i>Advanced</i> → <i>Java options</i> → <i>Parameters</i>
- and specify the following parameters:
-</p>
-<blockquote><pre>-agentlib:jdwp=transport=dt_socket,server=y,address=8000,suspend=n</pre></blockquote>
-
-<p>
- It allows to attach the IDE debugger to the Java virtual machine running in LibreOffice.
- For example, with NetBeans, use <i>Debug</i> → <i>Attach debugger…</i>,
- select "Socket attach" as the transport and 8000 as the port number.
-</p>
-
- </body>
-</html>
diff --git a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/parameter/AbstractParameterValue.md b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/parameter/AbstractParameterValue.md
new file mode 100644
index 0000000000..cce7e78b5c
--- /dev/null
+++ b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/parameter/AbstractParameterValue.md
@@ -0,0 +1,5 @@
+There is no `AbstractParameterValue` class because we do not need it.
+However if a public `AbstractParameterValue` class is provided in the
+future, then we could simplify a little bit the JAXB annotations on
+`CC_GeneralParameterValue.getElement()`. We don't do that for now
+because this is a too minor convenience for growing the public API.
diff --git a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/parameter/AbstractParameterValue.txt b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/parameter/AbstractParameterValue.txt
deleted file mode 100644
index 337cc8cfd5..0000000000
--- a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/parameter/AbstractParameterValue.txt
+++ /dev/null
@@ -1,5 +0,0 @@
-There is no AbstractParameterValue class because we do not need it.
-However if a public AbstractParameterValue class is provided in the
-future, then we could simplify a little bit the JAXB annotations on
-CC_GeneralParameterValue.getElement(). We don't do that for now
-because this is a too minor convenience for growing the public API.
diff --git a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/factory/sql/EPSG_README.md b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/factory/sql/EPSG_README.md
new file mode 100644
index 0000000000..f75310480f
--- /dev/null
+++ b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/factory/sql/EPSG_README.md
@@ -0,0 +1,7 @@
+Do not create an `epsg` sub-package (except for tests or maintenance tasks only)
+because the `org.apache.sis.referencing.factory.sql.epsg` package name is owned
+by the `org.apache.sis.non-free:sis-epsg` module and we should not put anything
+in a package owned by another module.
+
+We make this separation for licensing reason because the EPSG geodetic dataset
+is subject to different terms of use than Apache 2 license.
diff --git a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/factory/sql/EPSG_README.txt b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/factory/sql/EPSG_README.txt
deleted file mode 100644
index a1b26c3f1c..0000000000
--- a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/factory/sql/EPSG_README.txt
+++ /dev/null
@@ -1,7 +0,0 @@
-Do not create an "epsg" sub-package (except for test or maintainance tasks only)
-because the "org.apache.sis.referencing.factory.sql.epsg" package name is owned
-by the "org.apache.sis.non-free:sis-epsg" module and we should not put anything
-in a package owned by another module.
-
-We make this separation for licensing reason since the EPSG geodetic dataset is
-subject to different terms of use than Apache 2 license.
diff --git a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/builder/README.md b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/builder/README.md
new file mode 100644
index 0000000000..897e7f2898
--- /dev/null
+++ b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/builder/README.md
@@ -0,0 +1,33 @@
+# Implementation notes
+
+## Choice of errors in linear regression method
+Before to compute a localization grid, the `LocalizationGridBuilder` class
+first computes an *affine transform* from grid indices to geospatial coordinates.
+That affine transform is an approximation computed by linear regression using least-squares method.
+In an equation of the form _y_ = _C₀_ + _C₁_ × _x_ where the _C₀_ and _C₁_ coefficients are determined by linear regression,
+typical linear regression method assumes that _x_ values are exact and all errors are in _y_ values.
+Applied to the `LocalizationGridBuilder` context, it means that linear regression method
+assumes that grid indices are exact and all errors are in geospatial coordinates.
+
+The assumption that all errors are in geospatial coordinates is reasonable if the linear regression is used directly.
+But in `LocalizationGridBuilder` context, having the smallest errors on geospatial coordinates may not be so important
+because those errors are corrected by the residual grids during *forward* transformations.
+However, during *inverse* transformations, it may be useful that grid indices estimated by the linear regression
+are as close as possible to the real grid indices in order to allow iterations to converge faster
+(such iterations exist only in inverse operations, not in forward operations).
+For that reason, `LocalizationGridBuilder` may want to minimize errors on grid indices instead of geospatial coordinates.
+We could achieve this result by computing linear regression coefficients for an equation of the form
+_x_ = _C₀_ + _C₁_ × _y_, then inverting that equation.
+
+This approach was attempted in a previous version and gave encouraging results, but we nevertheless reverted that change.
+One reason is that even if inverting the linear regression calculation allowed iterations to converge more often with curved
+localization grids, it was not sufficient anyway: we still had too many cases where inverse transformations did not converge.
+Since a more sophisticated iteration method is needed anyway, we can avoid the additional complexity introduced by application
+of linear regression in reverse way. Some examples of additional complexities were `LinearTransformBuilder.correlation()`
+getting a meaning different than what its Javadoc said (values for each source dimensions instead of target dimensions),
+additional constraints brought by that approach (source coordinates must be a two-dimensional grid,
+source and target dimensions must be equal in order to have a square matrix), _etc._
+A more minor reason is that keeping the original approach (minimize errors on geospatial coordinates)
+help to improve accuracy by resulting in storage of smaller values in `float[]` arrays of `ResidualGrid`.
+
+For experimenting linear regressions in the reverse way, revert commit `c0944afb6e2cd77194ea71504ce6d74b651f72b7`.
diff --git a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/builder/readme.html b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/builder/readme.html
deleted file mode 100644
index b7d3de314c..0000000000
--- a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/builder/readme.html
+++ /dev/null
@@ -1,50 +0,0 @@
-<!DOCTYPE html>
-<html>
- <head>
- <title>Implementation notes</title>
- <meta charset="UTF-8">
- <style>
- p {
- text-align: justify;
- }
- </style>
- </head>
- <body>
- <h1>Implementation notes</h1>
- <h2>Choice of errors in linear regression method</h2>
- <p>
- Before to compute a localization grid, <code>LocalizationGridBuilder</code>
- first computes an <em>affine transform</em> from grid indices to geospatial coordinates.
- That affine transform is an approximation computed by linear regression using least-squares method.
- In an equation of the form <var>y</var> = <var>C₀</var> + <var>C₁</var> × <var>x</var>
- where the <var>C₀</var> and <var>C₁</var> coefficients are determined by linear regression,
- typical linear regression method assumes that <var>x</var> values are exact and all errors are in <var>y</var> values.
- Applied to the <code>LocalizationGridBuilder</code> context, it means that linear regression method
- assumes that grid indices are exact and all errors are in geospatial coordinates.
- </p><p>
- The assumption that all errors are in geospatial coordinates is reasonable if the linear regression is used directly.
- But in <code>LocalizationGridBuilder</code> context, having the smallest errors on geospatial coordinates
- may not be so important because those errors are corrected by the residual grids during <em>forward</em> transformations.
- However, during <em>inverse</em> transformations, it may be useful that grid indices estimated by the linear regression
- are as close as possible to the real grid indices in order to allow iterations to converge faster
- (such iterations exist only in inverse operations, not in forward operations).
- For that reason, <code>LocalizationGridBuilder</code> may want to minimize errors on grid indices instead of geospatial coordinates.
- We could achieve this result by computing linear regression coefficients for an equation of the form
- <var>x</var> = <var>C₀</var> + <var>C₁</var> × <var>y</var>, then inverting that equation.
- </p><p>
- This approach was attempted in a previous version and gave encouraging results, but we nevertheless reverted that change.
- One reason is that even if inverting the linear regression calculation allowed iterations to converge more often with curved
- localization grids, it was not sufficient anyway: we still had too many cases where inverse transformations did not converge.
- Since a more sophisticated iteration method is needed anyway, we can avoid the additional complexity introduced by application
- of linear regression in reverse way. Some examples of additional complexities were <code>LinearTransformBuilder.correlation()</code>
- getting a meaning different than what its Javadoc said (values for each source dimensions instead of target dimensions),
- additional constraints brought by that approach (source coordinates must be a two-dimensional grid,
- source and target dimensions must be equal in order to have a square matrix), <i>etc.</i>
- A more minor reason is that keeping the original approach (minimize errors on geospatial coordinates) help to improve accuracy
- by resulting in storage of smaller values in <code>float[]</code> arrays of <code>ResidualGrid</code>.
- </p>
- <p>
- For experimenting linear regressions in the reverse way, revert commit <code>c0944afb6e2cd77194ea71504ce6d74b651f72b7</code>.
- </p>
- </body>
-</html>
diff --git a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/provider/Geographic3DtoVertical.txt b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/provider/Geographic3DtoVertical.md
similarity index 84%
rename from endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/provider/Geographic3DtoVertical.txt
rename to endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/provider/Geographic3DtoVertical.md
index 38b21a8e89..e44cd9fead 100644
--- a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/provider/Geographic3DtoVertical.txt
+++ b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/provider/Geographic3DtoVertical.md
@@ -5,12 +5,14 @@ but it should be only in contexts where SIS can keep trace of other
dimensions in an "interpolation CRS". This happen in the following
method:
+```
CoordinateOperationFinder.createOperationStep(GeodeticCRS, VerticalCRS)
+```
The above method does inline the work of what would have been a
"Geographic 3D to ellipsoidal height" operation if it existed.
-The algorithm is the same than the one in Geographic3Dto2D.java:
-just drop dimensions with a non-square matrix like below; don't
+The algorithm is the same than the one in `Geographic3Dto2D.java`:
+just drop dimensions with a non-square matrix like below and don't
do unit conversion at this place (unit conversions are the job
of another method):
diff --git a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/transform/SpecializableTransform1D.md b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/transform/SpecializableTransform1D.md
new file mode 100644
index 0000000000..9a742db406
--- /dev/null
+++ b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/transform/SpecializableTransform1D.md
@@ -0,0 +1,3 @@
+There is no `SpecializableTransform1D` implementation yet because
+a more specific implementation is needed for Grid Coverage anyway.
+See the `SampleDimension` class in `org.apache.sis.feature` module.
diff --git a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/transform/SpecializableTransform1D.txt b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/transform/SpecializableTransform1D.txt
deleted file mode 100644
index 4026acc21a..0000000000
--- a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/transform/SpecializableTransform1D.txt
+++ /dev/null
@@ -1,3 +0,0 @@
-There is no SpecializableTransform1D implementation yet because a
-more specific implementation is needed for Grid Coverage anyway.
-See the SampleDimension class in sis-coverage module.
diff --git a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/xml/bind/referencing/SC_GeographicCRS.md b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/xml/bind/referencing/SC_GeographicCRS.md
new file mode 100644
index 0000000000..961fa2048b
--- /dev/null
+++ b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/xml/bind/referencing/SC_GeographicCRS.md
@@ -0,0 +1,4 @@
+The `SC_GeographicCRS` adapter is defined in the `org.apache.sis.referencing.crs`
+package because it needs access to `DefaultGeodeticCRS` package-private methods.
+Note also that `GeographicCRS` does not exist in GML, so this is a special case
+anyway.
diff --git a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/xml/bind/referencing/SC_GeographicCRS.txt b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/xml/bind/referencing/SC_GeographicCRS.txt
deleted file mode 100644
index 5d11dc7511..0000000000
--- a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/xml/bind/referencing/SC_GeographicCRS.txt
+++ /dev/null
@@ -1,4 +0,0 @@
-The SC_GeographicCRS adapter is defined in the org.apache.sis.referencing.crs
-package because it needs access to DefaultGeodeticCRS package-private methods.
-Note also that GeographicCRS does not exist in GML, so this is a special case
-anyway.
diff --git a/endorsed/src/org.apache.sis.referencing/test/org/apache/sis/referencing/factory/sql/epsg/README.md b/endorsed/src/org.apache.sis.referencing/test/org/apache/sis/referencing/factory/sql/epsg/README.md
new file mode 100644
index 0000000000..73d583a49e
--- /dev/null
+++ b/endorsed/src/org.apache.sis.referencing/test/org/apache/sis/referencing/factory/sql/epsg/README.md
@@ -0,0 +1,133 @@
+# EPSG dataset update procedure
+
+The `org.apache.sis.referencing.factory.sql.epsg` package in the `non-free:sis-epsg` module
+provides SQL scripts for installing a local copy of the [EPSG geodetic dataset](https://epsg.org/).
+This dataset provides definitions for thousands of Coordinate Reference Systems (CRS),
+together with parameter values for thousands of Coordinate Operations between various pairs of CRS.
+EPSG is maintained by the [International Association of Oil and Gas Producers](https://www.iogp.org/) (IOGP)
+Surveying & Positioning Committee and is subject to [EPSG terms of use](https://epsg.org/terms-of-use.html).
+Because of incompatibilities between EPSG terms of use and Apache 2 license, the EPSG geodetic dataset is not distributed
+by default with Apache SIS. A copy of the dataset is provided in a separated module in a separated source code repository.
+The Maven identifier of that module is `org.apache.sis.non-free:sis-epsg` and the source repository is located at
+http://svn.apache.org/repos/asf/sis/data/non-free/sis-epsg.
+The EPSG scripts are copied in that module with identical content, but in a more compact format.
+
+This `org.apache.sis.referencing.factory.sql.epsg` package in `endorsed/org.opengis.sis.referencing` module
+contains only tools for maintaining the `non-free/org.apache.sis.referencing.epsg` module.
+This package is provided only in the **test** directory, not in the main directory, because the
+`org.apache.sis.referencing.factory.sql.epsg` package name is reserved by the `non-free/org.apache.sis.referencing.epsg` module.
+The `endorsed/org.apache.sis.referencing` module should not distribute anything in packages owned by other modules.
+However, it is okay to use those package names in directories that are not part of the distribution, like tests.
+We put those tools here for easier maintainance when the core of Apache SIS is modified.
+
+
+## How to apply EPSG geodetic dataset updates
+
+This page explains how to convert the SQL scripts published by EPSG into the more compact form used by Apache SIS.
+The compact form is about half the size of the original files. Compaction is achieved by avoiding redundant statements.
+This conversion applies only to the data types, the integrity constraints and the way the SQL scripts are written.
+No data value should be altered. Steps to follow:
+
+Download the latest SQL scripts for PostgreSQL from https://epsg.org/ (require registration).
+Unzip in the directory of your choice and remember the path to that directory:
+
+```
+unzip EPSG-PSQL-export-_<version>_.zip
+export EPSG_SCRIPTS=$PWD
+```
+
+If a copy of the original SQL scripts (as downloaded from EPSG) for the previous version is still available,
+and if the following commands report no difference, then jump to "execute main" step.
+
+```
+cd _<directory containing EPSG scripts of previous version>_
+diff PostgreSQL_Table_Script.sql $EPSG_SCRIPTS/PostgreSQL_Table_Script.sql
+diff PostgreSQL_FKey_Script.sql $EPSG_SCRIPTS/PostgreSQL_FKey_Script.sql
+```
+
+Otherwise, move to the directory which contains the Apache SIS scripts:
+
+```
+cd <SIS_HOME>/non-free/sis-epsg/src/main/resources/org/apache/sis/referencing/factory/sql/epsg/
+```
+
+Overwrite `Tables.sql` and `FKeys.sql` with the new SQL scripts.
+Do not overwrite `Data.sql` and `Indexes.sql`:
+
+```
+cp $EPSG_SCRIPTS/PostgreSQL_Table_Script.sql Tables.sql
+cp $EPSG_SCRIPTS/PostgreSQL_FKey_Script.sql FKeys.sql
+```
+
+Open the `Tables.sql` file for edition:
+
+* Keep the header comments that existed in the overwritten file.
+* In the statement creating the `coordinateaxis` table,
+ add the `NOT NULL` constraint to the `coord_axis_code` column.
+* In the statement creating the `change` table,
+ remove the `UNIQUE` constraint on the `change_id` column
+ and add a `CONSTRAINT pk_change PRIMARY KEY (change_id)` line instead.
+* In the statement creating the `epsg_datum` table,
+ change the type of the `realization_epoch` column to `DATE`.
+* Change the type of `ellipsoid_shape`, `reverse_op`, `param_sign_reversal`
+ `show_crs`, `show_operation` and all `deprecated` fields from `SMALLINT`
+ (or sometimes `VARCHAR(3)`) to `BOOLEAN`.
+* Change the type of every `table_name` columns from `VARCHAR(80)` to `epsg_table_name`.
+* Change the type of `coord_ref_sys_kind` column from `VARCHAR(24)` to `epsg_crs_kind`.
+* Change the type of `coord_sys_type` column from `VARCHAR(24)` to `epsg_cs_kind`.
+* Change the type of `datum_type` column from `VARCHAR(24)` to `epsg_datum_kind`.
+* Suppress trailing spaces and save.
+
+Usually this results in no change at all compared to the previous script (ignoring white spaces),
+in which case the maintainer can just revert the changes in order to preserve the formatting.
+Then open the `FKeys.sql` file for edition:
+
+* At the end of all `ALTER TABLE` statement, append `ON UPDATE RESTRICT ON DELETE RESTRICT`.
+* Suppress trailing spaces and save.
+
+In most cases this results in unmodified `FKeys.sql` file compared to the previous version.
+
+
+### Main
+Execute the `main` method of the `org.apache.sis.referencing.factory.sql.epsg.DataScriptFormatter` class
+located in the test directory of `sis-referencing` module
+(adjust version numbers as needed; we may provide an easier way after migration to Jigsaw modules):
+
+```
+cd _<path to SIS project directory>_
+mvn clean install
+export CLASSPATH=~/.m2/repository/org/apache/derby/derby/10.14.2.0/derby-10.14.2.0.jar
+export CLASSPATH=$PWD/core/sis-metadata/target/test-classes:$CLASSPATH
+export CLASSPATH=$PWD/target/binaries/sis-referencing-2.0-SNAPSHOT.jar:$CLASSPATH
+export CLASSPATH=$PWD/core/sis-metadata/target/test-classes:$CLASSPATH
+export CLASSPATH=$PWD/core/sis-referencing/target/test-classes:$CLASSPATH
+cd <path to local copy of http://svn.apache.org/repos/asf/sis/data/non-free/>
+java org.apache.sis.referencing.factory.sql.epsg.DataScriptFormatter $EPSG_SCRIPTS/PostgreSQL_Data_Script.sql \
+ sis-epsg/src/main/resources/org/apache/sis/referencing/factory/sql/epsg/Data.sql
+```
+
+Run the tests. It it convenient to run `org.apache.sis.referencing.factory.sql.EPSGInstallerTest`
+in an IDE first, for easier debugging if some changes in database structure or content broke some code.
+Then the whole Apache SIS project should be [tested extensively](https://sis.apache.org/source.html#tests),
+preferably with a PostgreSQL server ready to accept local connections to `SpatialMetadataTest` database:
+
+```
+mvn install -Dorg.apache.sis.test.extensive=true
+```
+
+Regenerate the HTML pages listing available CRS and coordinate operation methods.
+Those pages will be copied into the
+[site/content/tables/](http://svn.apache.org/repos/asf/sis/site/trunk/content/tables/)
+directory during the [release process](https://sis.apache.org/release-management.html#update-crs-list),
+but for now the purpose is only to check if there is errors:
+
+* Upgrade the `FACTORY.VERSION` value defined in the
+ `org.apache.sis.referencing.report.CoordinateReferenceSystems` class, then execute that class.
+ It can be executed from the IDE since the `main` method takes no argument.
+ This class will write a `CoordinateReferenceSystems.html` file in current directory
+ (the full path will be printed in the standard output).
+* Execute the `org.apache.sis.referencing.report.CoordinateOperationMethods` class.
+ It can be executed from the IDE since the `main` method takes no argument.
+ This class will write a `CoordinateOperationMethods.html` file in current directory.
+
+Open those generated HTML files in a web browser and verify the result.
diff --git a/endorsed/src/org.apache.sis.referencing/test/org/apache/sis/referencing/factory/sql/epsg/package.html b/endorsed/src/org.apache.sis.referencing/test/org/apache/sis/referencing/factory/sql/epsg/package.html
deleted file mode 100644
index 0637d4619d..0000000000
--- a/endorsed/src/org.apache.sis.referencing/test/org/apache/sis/referencing/factory/sql/epsg/package.html
+++ /dev/null
@@ -1,168 +0,0 @@
-<!DOCTYPE html>
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to You under the Apache License, Version 2.0
- (the "License"); you may not use this file except in compliance with
- the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
--->
-<html>
- <head>
- <title>EPSG dataset update procedure</title>
- <meta charset="UTF-8">
- <style>
- p {text-align: justify;}
- pre > i {color:red}
- </style>
- </head>
- <body>
- <h1>EPSG dataset update procedure</h1>
- <p>
- The <code>org.apache.sis.referencing.factory.sql.epsg</code> package in the <code>non-free:sis-epsg</code> module
- provides SQL scripts for installing a local copy of the <a href="https://epsg.org/">EPSG geodetic dataset</a>.
- This dataset provides definitions for thousands of Coordinate Reference Systems (CRS),
- together with parameter values for thousands of Coordinate Operations between various pairs of CRS.
- EPSG is maintained by the <a href="https://www.iogp.org/">International Association of Oil and Gas Producers</a> (IOGP)
- Surveying & Positioning Committee and is subject to <a href="https://epsg.org/terms-of-use.html">EPSG terms of use</a>.
- Because of incompatibilities between EPSG terms of use and Apache 2 license, the EPSG geodetic dataset is not distributed
- by default with Apache SIS. A copy of the dataset is provided in a separated module in a separated source code repository.
- The Maven identifier of that module is <code>org.apache.sis.non-free:sis-epsg</code> and the source repository is located at
- <a href="http://svn.apache.org/repos/asf/sis/data/non-free/sis-epsg">http://svn.apache.org/repos/asf/sis/data/non-free/sis-epsg</a>.
- The EPSG scripts are copied in that module with identical content, but in a more compact format.
- </p>
-
- <p>
- This <code>org.apache.sis.referencing.factory.sql.epsg</code> package in <code>core:sis-referencing</code> module
- contains only tools for maintaining the <code>non-free:sis-epsg</code> module.
- This package is provided only in the <strong>test</strong> directory, not in the main directory, because the
- <code>org.apache.sis.referencing.factory.sql.epsg</code> package name is reserved by the <code>non-free:sis-epsg</code> module.
- The <code>core:sis-referencing</code> module should not distribute anything in packages owned by other modules.
- However, it is okay to use those package names in directories that are not part of the distribution, like tests.
- We put those tools here for easier maintainance when the core of Apache SIS is modified.
- </p>
-
- <h2>How to apply EPSG geodetic dataset updates</h2>
- <p>
- This page explains how to convert the SQL scripts published by EPSG into the more compact form used by Apache SIS.
- The compact form is about half the size of the original files. Compaction is achieved by avoiding redundant statements.
- This conversion applies only to the data types, the integrity constraints and the way the SQL scripts are written.
- No data value should be altered. Steps to follow:
- </p>
- <ol>
- <li><p>Download the latest SQL scripts for PostgreSQL from <a href="https://epsg.org/">https://epsg.org/</a>
- (require registration).</p></li>
-
- <li><p>Unzip in the directory of your choice and remember the path to that directory:</p>
-
- <pre>unzip EPSG-PSQL-export-<i><version></i>.zip
-export EPSG_SCRIPTS=$PWD</pre>
- </li>
-
- <li><p>If a copy of the original SQL scripts (as downloaded from EPSG) for the previous version is still available,
- and if the following commands report no difference, then jump to step 4.</p>
-
- <pre>cd <i><directory containing EPSG scripts of previous version></i>
-diff PostgreSQL_Table_Script.sql $EPSG_SCRIPTS/PostgreSQL_Table_Script.sql
-diff PostgreSQL_FKey_Script.sql $EPSG_SCRIPTS/PostgreSQL_FKey_Script.sql</pre>
-
- <details>
- <summary>Otherwise:</summary>
- <ol style="list-style-type: lower-roman">
- <li><p>Move to the directory which contains the Apache SIS scripts:</p>
- <pre>cd <SIS_HOME>/non-free/sis-epsg/src/main/resources/org/apache/sis/referencing/factory/sql/epsg/</pre>
- </li>
-
- <li><p>Overwrite <code>Tables.sql</code> and <code>FKeys.sql</code> with the new SQL scripts
- Do not overwrite <code>Data.sql</code> and <code>Indexes.sql</code>:</p>
- <pre>cp $EPSG_SCRIPTS/PostgreSQL_Table_Script.sql Tables.sql
-cp $EPSG_SCRIPTS/PostgreSQL_FKey_Script.sql FKeys.sql</pre>
- </li>
-
- <li><p>Open the <code>Tables.sql</code> file for edition:</p>
- <ul>
- <li>Keep the header comments that existed in the overwritten file.</li>
- <li>In the statement creating the <code>coordinateaxis</code> table,
- add the <code>NOT NULL</code> constraint to the <code>coord_axis_code</code> column.</li>
- <li>In the statement creating the <code>change</code> table,
- remove the <code>UNIQUE</code> constraint on the <code>change_id</code> column
- and add a <code>CONSTRAINT pk_change PRIMARY KEY (change_id)</code> line instead.</li>
- <li>In the statement creating the <code>epsg_datum</code> table,
- change the type of the <code>realization_epoch</code> column to <code>DATE</code>.</li>
- <li>Change the type of <code>ellipsoid_shape</code>, <code>reverse_op</code>, <code>param_sign_reversal</code>
- <code>show_crs</code>, <code>show_operation</code> and all <code>deprecated</code> fields from <code>SMALLINT</code>
- (or sometimes <code>VARCHAR(3)</code>) to <code>BOOLEAN</code>.</li>
- <li>Change the type of every <code>table_name</code> columns from <code>VARCHAR(80)</code> to <code>epsg_table_name</code>.</li>
- <li>Change the type of <code>coord_ref_sys_kind</code> column from <code>VARCHAR(24)</code> to <code>epsg_crs_kind</code>.</li>
- <li>Change the type of <code>coord_sys_type</code> column from <code>VARCHAR(24)</code> to <code>epsg_cs_kind</code>.</li>
- <li>Change the type of <code>datum_type</code> column from <code>VARCHAR(24)</code> to <code>epsg_datum_kind</code>.</li>
- <li>Suppress trailing spaces and save.</li>
- </ul>
- <p>Usually this results in no change at all compared to the previous script (ignoring white spaces),
- in which case the maintainer can just revert the changes in order to preserve the formatting.</p>
- </li>
-
- <li><p>Open the <code>FKeys.sql</code> file for edition:</p>
- <ul>
- <li>At the end of all <code>ALTER TABLE</code> statement,
- append <code>ON UPDATE RESTRICT ON DELETE RESTRICT</code>.</li>
- <li>suppress trailing spaces and save.</li>
- </ul>
- <p>In most cases this results in unmodified <code>FKeys.sql</code> file compared to the previous version.</p>
- </li>
- </ol>
- </details>
- </li>
-
- <li><p>Execute the <code>main</code> method of the
- <code>org.apache.sis.referencing.factory.sql.epsg.DataScriptFormatter</code> class
- located in the test directory of <code>sis-referencing</code> module
- (adjust version numbers as needed; we may provide an easier way after migration to Jigsaw modules):</p>
-
- <pre>cd <i><path to SIS project directory></i>
-mvn clean install
-export CLASSPATH=~/.m2/repository/org/apache/derby/derby/10.14.2.0/derby-10.14.2.0.jar
-export CLASSPATH=$PWD/core/sis-metadata/target/test-classes:$CLASSPATH
-export CLASSPATH=$PWD/target/binaries/sis-referencing-2.0-SNAPSHOT.jar:$CLASSPATH
-export CLASSPATH=$PWD/core/sis-metadata/target/test-classes:$CLASSPATH
-export CLASSPATH=$PWD/core/sis-referencing/target/test-classes:$CLASSPATH
-cd <i><path to local copy of <a href="http://svn.apache.org/repos/asf/sis/data/non-free/">http://svn.apache.org/repos/asf/sis/data/non-free/</a>></i>
-java org.apache.sis.referencing.factory.sql.epsg.DataScriptFormatter $EPSG_SCRIPTS/PostgreSQL_Data_Script.sql \
- sis-epsg/src/main/resources/org/apache/sis/referencing/factory/sql/epsg/Data.sql</pre></li>
-
- <li><p>Run the tests. It it convenient to run <code>org.apache.sis.referencing.factory.sql.EPSGInstallerTest</code> in an IDE first,
- for easier debugging if some changes in database structure or content broke some code. Then the whole Apache SIS project should be
- <a href="https://sis.apache.org/source.html#tests">tested extensively</a>, preferably with a PostgreSQL server ready to accept local
- connections to <code>SpatialMetadataTest</code> database:</p>
-
- <pre>mvn install -Dorg.apache.sis.test.extensive=true</pre></li>
-
- <li><p>Regenerate the HTML pages listing available CRS and coordinate operation methods.
- Those pages will be copied into the
- <code><a href="http://svn.apache.org/repos/asf/sis/site/trunk/content/tables/">site/content/tables/</a></code>
- directory during the <a href="https://sis.apache.org/release-management.html#update-crs-list">release process</a>,
- but for now the purpose is only to check if there is errors:</p>
- <ul>
- <li><p>Upgrade the <code>FACTORY.VERSION</code> value defined in the
- <code>org.apache.sis.referencing.report.CoordinateReferenceSystems</code> class, then execute that class.
- It can be executed from the IDE since the <code>main</code> method takes no argument.
- This class will write a <code>CoordinateReferenceSystems.html</code> file in current directory
- (the full path will be printed in the standard output).</p></li>
-
- <li><p>Execute the <code>org.apache.sis.referencing.report.CoordinateOperationMethods</code> class.
- It can be executed from the IDE since the <code>main</code> method takes no argument.
- This class will write a <code>CoordinateOperationMethods.html</code> file in current directory.</p></li>
- </ul>
- <p>Open those generated HTML files in a web browser and verify the result.</p>
- </li>
- </ol>
- </body>
-</html>
diff --git a/incubator/src/org.apache.sis.storage.shapefile/test/org/apache/sis/storage/shapefile/jdbc/readme.txt b/incubator/src/org.apache.sis.storage.shapefile/test/org/apache/sis/storage/shapefile/jdbc/README.md
similarity index 99%
rename from incubator/src/org.apache.sis.storage.shapefile/test/org/apache/sis/storage/shapefile/jdbc/readme.txt
rename to incubator/src/org.apache.sis.storage.shapefile/test/org/apache/sis/storage/shapefile/jdbc/README.md
index 2cad8137da..4a880a8b83 100644
--- a/incubator/src/org.apache.sis.storage.shapefile/test/org/apache/sis/storage/shapefile/jdbc/readme.txt
+++ b/incubator/src/org.apache.sis.storage.shapefile/test/org/apache/sis/storage/shapefile/jdbc/README.md
@@ -1,5 +1,6 @@
The SignedBikeRoute_4326_clipped.dbf used for testing in this package has this description :
+```
Field name : OBJECTID, Type : Number, Field length : 10, Decimal positions : 0
Field name : FNODE_, Type : Number, Field length : 10, Decimal positions : 0
Field name : TNODE_, Type : Number, Field length : 10, Decimal positions : 0
@@ -56,3 +57,4 @@ Field name : SIGNED_JOI, Type : Character, Field length : 5, Decimal positions :
Field name : SIGNED_FAC, Type : Character, Field length : 30, Decimal positions : 0
Field name : NEW_USE, Type : Character, Field length : 30, Decimal positions : 0
Field name : SHAPE_LEN, Type : Number, Field length : 19, Decimal positions : 11
+```