Document natural sorting and the DATABASE_EMULATE_NATURAL_SORT option

Author: jbtronics

.env

@@ -24,7 +24,7 @@ DATABASE_MYSQL_USE_SSL_CA=0
 DATABASE_MYSQL_SSL_VERIFY_CERT=1
 
 # Emulate natural sorting of strings even on databases that do not support it (like SQLite, MySQL or MariaDB < 10.7)
-# This can be slow on big databases
+# This can be slow on big databases and might have some problems and quirks, so use it with caution
 DATABASE_EMULATE_NATURAL_SORT=0
 
 ###################################################################################

docs/configuration.md

@@ -40,6 +40,9 @@ options listed, see `.env` file for the full list of possible env variables.
 * `DATABASE_MYSQL_USE_SSL_CA`: If this value is set to `1` or `true` and a MySQL connection is used, then the connection
  is encrypted by SSL/TLS and the server certificate is verified against the system CA certificates or the CA certificate
 bundled with Part-DB. Set `DATABASE_MYSQL_SSL_VERIFY_CERT` if you want to accept all certificates.
+* `DATABASE_EMULATE_NATURAL_SORT` (default 0): If set to 1, Part-DB will emulate natural sorting, even if the database 
+  does not support it natively. However this is much slower than the native sorting, and contain bugs or quirks, so use
+  it only, if you have to.
 * `DEFAULT_LANG`: The default language to use server-wide (when no language is explicitly specified by a user or via
   language chooser). Must be something like `en`, `de`, `fr`, etc.
 * `DEFAULT_TIMEZONE`: The default timezone to use globally, when a user has no timezone specified. Must be something

docs/installation/choosing_database.md

@@ -154,3 +154,29 @@ If you want to use a unix socket for the connection instead of a TCP connnection
 ```shell
 DATABASE_URL="postgresql://db_user:db_password@localhost/db_name?serverVersion=12.19&charset=utf8&unix_socket=/var/run/postgresql/.s.PGSQL.5432"
 ```
+
+
+## Natural Sorting
+
+Natural sorting is the sorting of strings in a way that numbers are sorted by their numerical value, not by their ASCII value.
+
+For example in the classical binary sorting the string `DIP-4`, `DIP-8`, `DIP-16`, `DIP-28` would be sorted as following:
+
+* `DIP-16`
+* `DIP-28`
+* `DIP-4`
+* `DIP-8`
+
+In natural sorting, it would be sorted as:
+
+* `DIP-4`
+* `DIP-8`
+* `DIP-16`
+* `DIP-28`
+
+Part-DB can sort names in part tables and tree views naturally. PostgreSQL and MariaDB 10.7+ support natural sorting natively,
+and it is automatically used if available.
+
+For SQLite and MySQL < 10.7 it has to be emulated if wanted, which is pretty slow. Therefore it has to be explicity enabled by setting the
+`DATABASE_EMULATE_NATURAL_SORT` environment variable to `1`. If it is 0 the classical binary sorting is used, on these databases. The emulations
+might have some quirks and issues, so it is recommended to use a database which supports natural sorting natively, if you want to use it.