More documentation updates for 3.11.0 (#3553)

* mkdocs: add string_view examples

* mkdocs: reference underlying operators

* mkdocs: add operator<=> examples

* mkdocs: fix style check issues

* mkdocs: tweak BJData page

* mkdocs: add CMake option hints to macros

* mkdocs: fix JSON_DISABLE_ENUM_SERIALIZATION definition

* mkdocs: fix link to unit-udt.cpp

* mkdocs: fix "Arbitrary Type Conversions" title

* mkdocs: link to api/macros/*.md instead of features/macros.md

* mkdocs: document JSON_DisableEnumSerialization CMake option

* mkdocs: encode required C++ standard in example files

* docset: detect gsed/sed

* docset: update index

* docset: fix CSS patching

* docset: add list_missing_pages make target

* docset: add list_removed_paths make target

* docset: replace page titles with name from index

* docset: add install target for Zeal docset browser

* Use GCC_TOOL in ci_test_documentation target

docs/mkdocs/docs/api/basic_json/at.md

@@ -137,11 +137,11 @@ Strong exception safety: if an exception occurs, the original value stays intact
     --8<-- "examples/at__object_t_key_type.output"
     ```
 
-??? example "Example (2) access specified object element with bounds checking"
+??? example "Example: (2) access specified object element with bounds checking"
 
     The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
     that can be thrown.
-        
+    
     ```cpp
     --8<-- "examples/at__object_t_key_type_const.cpp"
     ```
@@ -152,34 +152,64 @@ Strong exception safety: if an exception occurs, the original value stays intact
     --8<-- "examples/at__object_t_key_type_const.output"
     ```
 
-??? example "Example (4) access specified element via JSON Pointer"
+??? example "Example: (3) access specified object element using string_view with bounds checking"
+
+    The example below shows how object elements can be read and written using `at()`. It also demonstrates the different
+    exceptions that can be thrown.
+    
+    ```cpp
+    --8<-- "examples/at__keytype.c++17.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/at__keytype.c++17.output"
+    ```
+
+??? example "Example: (3) access specified object element using string_view with bounds checking"
+
+    The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
+    that can be thrown.
+    
+    ```cpp
+    --8<-- "examples/at__keytype_const.c++17.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/at__keytype_const.c++17.output"
+    ```
+
+??? example "Example: (4) access specified element via JSON Pointer"
 
     The example below shows how object elements can be read and written using `at()`. It also demonstrates the different
     exceptions that can be thrown.
         
     ```cpp
-    --8<-- "examples/at_json_pointer.cpp"
+    --8<-- "examples/at__json_pointer.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/at_json_pointer.output"
+    --8<-- "examples/at__json_pointer.output"
     ```
 
-??? example "Example (4) access specified element via JSON Pointer"
+??? example "Example: (4) access specified element via JSON Pointer"
 
     The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
     that can be thrown.
         
     ```cpp
-    --8<-- "examples/at_json_pointer_const.cpp"
+    --8<-- "examples/at__json_pointer_const.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/at_json_pointer_const.output"
+    --8<-- "examples/at__json_pointer_const.output"
     ```
 
 ## See also

docs/mkdocs/docs/api/basic_json/contains.md

@@ -69,32 +69,46 @@ Logarithmic in the size of the JSON object.
 
 ## Examples
 
-??? example "Example (1) check with key"
+??? example "Example: (1) check with key"
 
     The example shows how `contains()` is used.
     
     ```cpp
-    --8<-- "examples/contains.cpp"
+    --8<-- "examples/contains__object_t_key_type.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/contains.output"
+    --8<-- "examples/contains__object_t_key_type.output"
     ```
 
-??? example "Example (3) check with JSON pointer"
+??? example "Example: (2) check with key using string_view"
 
     The example shows how `contains()` is used.
     
     ```cpp
-    --8<-- "examples/contains_json_pointer.cpp"
+    --8<-- "examples/contains__keytype.c++17.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/contains_json_pointer.output"
+    --8<-- "examples/contains__keytype.c++17.output"
+    ```
+
+??? example "Example: (3) check with JSON pointer"
+
+    The example shows how `contains()` is used.
+    
+    ```cpp
+    --8<-- "examples/contains__json_pointer.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/contains__json_pointer.output"
     ```
 
 ## Version history

docs/mkdocs/docs/api/basic_json/count.md

@@ -44,18 +44,32 @@ This method always returns `0` when executed on a JSON type that is not an objec
 
 ## Examples
 
-??? example
+??? example "Example: (1) count number of elements"
 
     The example shows how `count()` is used.
     
     ```cpp
-    --8<-- "examples/count.cpp"
+    --8<-- "examples/count__object_t_key_type.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/count.output"
+    --8<-- "examples/count__object_t_key_type.output"
+    ```
+
+??? example "Example: (2) count number of elements using string_view"
+
+    The example shows how `count()` is used.
+    
+    ```cpp
+    --8<-- "examples/count__keytype.c++17.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/count__keytype.c++17.output"
     ```
 
 ## Version history

docs/mkdocs/docs/api/basic_json/erase.md

@@ -165,13 +165,27 @@ Strong exception safety: if an exception occurs, the original value stays intact
     The example shows the effect of `erase()` for different JSON types using an object key.
     
     ```cpp
-    --8<-- "examples/erase__key_type.cpp"
+    --8<-- "examples/erase__object_t_key_type.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/erase__key_type.output"
+    --8<-- "examples/erase__object_t_key_type.output"
+    ```
+
+??? example "Example: (4) remove element from a JSON object given a key using string_view"
+
+    The example shows the effect of `erase()` for different JSON types using an object key.
+    
+    ```cpp
+    --8<-- "examples/erase__keytype.c++17.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/erase__keytype.c++17.output"
     ```
 
 ??? example "Example: (5) remove element from a JSON array given an index"

docs/mkdocs/docs/api/basic_json/find.md

@@ -48,18 +48,32 @@ This method always returns `end()` when executed on a JSON type that is not an o
 
 ## Examples
 
-??? example
+??? example "Example: (1) find object element by key"
 
     The example shows how `find()` is used.
     
     ```cpp
-    --8<-- "examples/find__key_type.cpp"
+    --8<-- "examples/find__object_t_key_type.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/find__key_type.output"
+    --8<-- "examples/find__object_t_key_type.output"
+    ```
+
+??? example "Example: (2) find object element by key using string_view"
+
+    The example shows how `find()` is used.
+    
+    ```cpp
+    --8<-- "examples/find__keytype.c++17.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/find__keytype.c++17.output"
     ```
 
 ## See also

docs/mkdocs/docs/api/basic_json/meta.md

@@ -48,7 +48,8 @@ Constant.
 
 ## See also
 
-- [**NLOHMANN_JSON_VERSION_MAJOR**/**NLOHMANN_JSON_VERSION_MINOR**/**NLOHMANN_JSON_VERSION_PATCH**](../macros/nlohmann_json_version_major.md) - library version information
+- [**NLOHMANN_JSON_VERSION_MAJOR**/**NLOHMANN_JSON_VERSION_MINOR**/**NLOHMANN_JSON_VERSION_PATCH**](../macros/nlohmann_json_version_major.md)
+  \- library version information
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json/operator[].md

@@ -111,89 +111,117 @@ Strong exception safety: if an exception occurs, the original value stays intact
 
 ## Examples
 
-??? example "Example (1): access specified array element"
+??? example "Example: (1) access specified array element"
 
     The example below shows how array elements can be read and written using `[]` operator. Note the addition of
     `#!json null` values.
         
     ```cpp
-    --8<-- "examples/operatorarray__size_type.cpp"
+    --8<-- "examples/operator_array__size_type.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/operatorarray__size_type.output"
+    --8<-- "examples/operator_array__size_type.output"
     ```
 
-??? example "Example (1): access specified array element"
+??? example "Example: (1) access specified array element (const)"
 
     The example below shows how array elements can be read using the `[]` operator.
 
     ```cpp
-    --8<-- "examples/operatorarray__size_type_const.cpp"
+    --8<-- "examples/operator_array__size_type_const.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/operatorarray__size_type_const.output"
+    --8<-- "examples/operator_array__size_type_const.output"
     ```
 
-??? example "Example (2): access specified object element"
+??? example "Example: (2) access specified object element"
 
     The example below shows how object elements can be read and written using the `[]` operator.
     
     ```cpp
-    --8<-- "examples/operatorarray__key_type.cpp"
+    --8<-- "examples/operator_array__object_t_key_type.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/operatorarray__key_type.output"
+    --8<-- "examples/operator_array__object_t_key_type.output"
     ```
 
-??? example "Example (2): access specified object element (const)"
+??? example "Example: (2) access specified object element (const)"
 
     The example below shows how object elements can be read using the `[]` operator.
     
     ```cpp
-    --8<-- "examples/operatorarray__key_type_const.cpp"
+    --8<-- "examples/operator_array__object_t_key_type_const.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/operatorarray__key_type_const.output"
+    --8<-- "examples/operator_array__object_t_key_type_const.output"
     ```
 
-??? example "Example (4): access specified element via JSON Pointer"
+??? example "Example: (3) access specified object element using string_view"
+
+    The example below shows how object elements can be read using the `[]` operator.
+    
+    ```cpp
+    --8<-- "examples/operator_array__keytype.c++17.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/operator_array__keytype.c++17.output"
+    ```
+
+??? example "Example: (3) access specified object element using string_view (const)"
+
+    The example below shows how object elements can be read using the `[]` operator.
+    
+    ```cpp
+    --8<-- "examples/operator_array__keytype_const.c++17.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/operator_array__keytype_const.c++17.output"
+    ```
+
+??? example "Example: (4) access specified element via JSON Pointer"
 
     The example below shows how values can be read and written using JSON Pointers.
     
     ```cpp
-    --8<-- "examples/operatorjson_pointer.cpp"
+    --8<-- "examples/operator_array__json_pointer.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/operatorjson_pointer.output"
+    --8<-- "examples/operator_array__json_pointer.output"
     ```
 
-??? example "Example (4): access specified element via JSON Pointer (const)"
+??? example "Example: (4) access specified element via JSON Pointer (const)"
 
     The example below shows how values can be read using JSON Pointers.
     
     ```cpp
-    --8<-- "examples/operatorjson_pointer_const.cpp"
+    --8<-- "examples/operator_array__json_pointer_const.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/operatorjson_pointer_const.output"
+    --8<-- "examples/operator_array__json_pointer_const.output"
     ```
 
 ## See also

docs/mkdocs/docs/api/basic_json/operator_ValueType.md

@@ -78,5 +78,5 @@ Linear in the size of the JSON value.
 ## Version history
 
 - Since version 1.0.0.
-- Macros `JSON_EXPLICIT`/[`JSON_USE_IMPLICIT_CONVERSIONS`](../../features/macros.md#json_use_implicit_conversions) added
+- Macros `JSON_EXPLICIT`/[`JSON_USE_IMPLICIT_CONVERSIONS`](../macros/json_use_implicit_conversions.md) added
   in version 3.9.0.

docs/mkdocs/docs/api/basic_json/operator_ge.md

@@ -15,7 +15,7 @@ bool operator>=(ScalarType lhs, const const_reference rhs) noexcept;  // (2)
    according to the following rules:
     - The comparison always yields `#!cpp false` if (1) either operand is discarded, or (2) either
       operand is `NaN` and the other operand is either `NaN` or any other number.
-    - Otherwise, returns the result of `#!cpp !(lhs < rhs)`.
+    - Otherwise, returns the result of `#!cpp !(lhs < rhs)` (see [**operator<**](operator_lt.md)).
 
 2. Compares wether a JSON value is greater than or equal to a scalar or a scalar is greater than or
    equal to a JSON value by converting the scalar to a JSON value and comparing both JSON values

docs/mkdocs/docs/api/basic_json/operator_gt.md

@@ -15,7 +15,7 @@ bool operator>(ScalarType lhs, const const_reference rhs) noexcept;  // (2)
   following rules:
     - The comparison always yields `#!cpp false` if (1) either operand is discarded, or (2) either
       operand is `NaN` and the other operand is either `NaN` or any other number.
-    - Otherwise, returns the result of `#!cpp !(lhs <= rhs)`.
+    - Otherwise, returns the result of `#!cpp !(lhs <= rhs)` (see [**operator<=**](operator_le.md)).
 
 2. Compares wether a JSON value is greater than a scalar or a scalar is greater than a JSON value by
    converting the scalar to a JSON value and comparing both JSON values according to 1.

docs/mkdocs/docs/api/basic_json/operator_le.md

@@ -15,7 +15,7 @@ bool operator<=(ScalarType lhs, const const_reference rhs) noexcept;  // (2)
    according to the following rules:
     - The comparison always yields `#!cpp false` if (1) either operand is discarded, or (2) either
       operand is `NaN` and the other operand is either `NaN` or any other number.
-    - Otherwise, returns the result of `#!cpp !(rhs < lhs)`.
+    - Otherwise, returns the result of `#!cpp !(rhs < lhs)` (see [**operator<**](operator_lt.md)).
 
 1. Compares wether a JSON value is less than or equal to a scalar or a scalar is less than or equal
    to a JSON value by converting the scalar to a JSON value and comparing both JSON values according

docs/mkdocs/docs/api/basic_json/operator_spaceship.md

@@ -55,6 +55,36 @@ Linear.
         2. Comparing a `NaN` with another `NaN`.
         3. Comparing a `NaN` and any other number.
 
+## Examples
+
+??? example "Example: (1) comparing JSON values"
+
+    The example demonstrates comparing several JSON values.
+    
+    ```cpp
+    --8<-- "examples/operator_spaceship__const_reference.c++20.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/operator_spaceship__const_reference.c++20.output"
+    ```
+
+??? example "Example: (2) comparing JSON values and scalars"
+
+    The example demonstrates comparing several JSON values and scalars.
+    
+    ```cpp
+    --8<-- "examples/operator_spaceship__scalartype.c++20.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/operator_spaceship__scalartype.c++20.output"
+    ```
+
 ## See also
 
 - [**operator==**](operator_eq.md) - comparison: equal

docs/mkdocs/docs/api/basic_json/value.md

@@ -105,32 +105,46 @@ changes to any JSON value.
 
 ## Examples
 
-??? example "Example (1): access specified object element with default value"
+??? example "Example: (1) access specified object element with default value"
 
     The example below shows how object elements can be queried with a default value.
     
     ```cpp
-    --8<-- "examples/basic_json__value.cpp"
+    --8<-- "examples/value__object_t_key_type.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/basic_json__value.output"
+    --8<-- "examples/value__object_t_key_type.output"
     ```
 
-??? example "Example (3): access specified object element via JSON Pointer with default value"
+??? example "Example: (2) access specified object element using string_view with default value"
 
     The example below shows how object elements can be queried with a default value.
     
     ```cpp
-    --8<-- "examples/basic_json__value_ptr.cpp"
+    --8<-- "examples/value__keytype.c++17.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/basic_json__value_ptr.output"
+    --8<-- "examples/value__keytype.c++17.output"
+    ```
+
+??? example "Example: (3) access specified object element via JSON Pointer with default value"
+
+    The example below shows how object elements can be queried with a default value.
+    
+    ```cpp
+    --8<-- "examples/value__json_ptr.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/value__json_ptr.output"
     ```
 
 ## See also

docs/mkdocs/docs/api/macros/index.md

@@ -25,7 +25,8 @@ header. See also the [macro overview page](../../features/macros.md).
 ## Library version
 
 - [**JSON_SKIP_LIBRARY_VERSION_CHECK**](json_skip_library_version_check.md) - skip library version check
-- [**NLOHMANN_JSON_VERSION_MAJOR**<br>**NLOHMANN_JSON_VERSION_MINOR**<br>**NLOHMANN_JSON_VERSION_PATCH**](nlohmann_json_version_major.md) - library version information
+- [**NLOHMANN_JSON_VERSION_MAJOR**<br>**NLOHMANN_JSON_VERSION_MINOR**<br>**NLOHMANN_JSON_VERSION_PATCH**](nlohmann_json_version_major.md)
+  \- library version information
 
 ## Library namespace
 
@@ -45,7 +46,11 @@ header. See also the [macro overview page](../../features/macros.md).
 
 ## Serialization/deserialization macros
 
-- [**NLOHMANN_DEFINE_TYPE_INTRUSIVE(type, member...)**<br>**NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT(type, member...)**](nlohmann_define_type_intrusive.md) - serialization/deserialization of types _with_ access to private variables
-- [**NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(type, member...)**<br>**NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT(type, member...)**](nlohmann_define_type_non_intrusive.md) - serialization/deserialization of types _without_ access to private variables
-- [**NLOHMANN_JSON_SERIALIZE_ENUM(type, ...)**](nlohmann_json_serialize_enum.md) - serialization/deserialization of enum
-  types
+- [**NLOHMANN_DEFINE_TYPE_INTRUSIVE(type, member...)**<br>**NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT(type, member...)**][DefInt]
+  \- serialization/deserialization of types _with_ access to private variables
+- [**NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(type, member...)**<br>**NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT(type, member...)**][DefNonInt]
+  \- serialization/deserialization of types _without_ access to private variables
+- [**NLOHMANN_JSON_SERIALIZE_ENUM(type, ...)**](nlohmann_json_serialize_enum.md) - serialization/deserialization of enum types
+
+[DefInt]: nlohmann_define_type_intrusive.md
+[DefNonInt]: nlohmann_define_type_non_intrusive.md

docs/mkdocs/docs/api/macros/json_diagnostics.md

@@ -11,9 +11,6 @@ When enabled, exception messages contain a [JSON Pointer](../json_pointer/json_p
 triggered the exception. Note that enabling this macro increases the size of every JSON value by one pointer and adds
 some  runtime overhead.
 
-The diagnostics messages can also be controlled with the CMake option `JSON_Diagnostics` (`OFF` by default) which sets
-`JSON_DIAGNOSTICS` accordingly.
-
 ## Default definition
 
 The default value is `0` (extended diagnostics are switched off).
@@ -37,6 +34,12 @@ When the macro is not defined, the library will define it to its default value.
     
     Where possible, it is still recommended that all code define this the same way for maximum interoperability.
 
+!!! hint "CMake option"
+
+    Diagnostic messages can also be controlled with the CMake option
+    [`JSON_Diagnostics`](../../integration/cmake.md#json_diagnostics) (`OFF` by default)
+    which defines `JSON_DIAGNOSTICS` accordingly.
+
 ## Examples
 
 ??? example "Example 1: default behavior"

docs/mkdocs/docs/api/macros/json_disable_enum_serialization.md

@@ -1,10 +1,12 @@
 # JSON_DISABLE_ENUM_SERIALIZATION
 
 ```cpp
-#define JSON_DISABLE_ENUM_SERIALIZATION
+#define JSON_DISABLE_ENUM_SERIALIZATION /* value */
 ```
 
-When defined, default serialization and deserialization functions for enums are excluded and have to be provided by the user, for example, using [`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md) (see [arbitrary type conversions](../../features/arbitrary_types.md) for more details).
+When defined to `1`, default serialization and deserialization functions for enums are excluded and have to be provided
+by the user, for example, using [`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md) (see
+[arbitrary type conversions](../../features/arbitrary_types.md) for more details).
 
 Parsing or serializing an enum will result in a compiler error.
 
@@ -12,17 +14,26 @@ This works for both unscoped and scoped enums.
 
 ## Default definition
 
-By default, `#!cpp JSON_DISABLE_ENUM_SERIALIZATION` is not defined.
+The default value is `0`.
 
 ```cpp
-#undef JSON_DISABLE_ENUM_SERIALIZATION
+#define JSON_DISABLE_ENUM_SERIALIZATION 0
 ```
 
+## Notes
+
+!!! hint "CMake option"
+
+    Enum serialization can also be controlled with the CMake option
+    [`JSON_DisableEnumSerialization`](../../integration/cmake.md#json_disableenumserialization)
+    (`OFF` by default) which defines `JSON_DISABLE_ENUM_SERIALIZATION` accordingly.
+
 ## Examples
 
 ??? example "Example 1: Disabled behavior"
 
-    The code below forces the library **not** to create default serialization/deserialization functions `from_json` and `to_json`, meaning the code below **does not** compile.
+    The code below forces the library **not** to create default serialization/deserialization functions `from_json` and `to_json`, meaning the code below
+    **does not** compile.
 
     ```cpp
     #define JSON_DISABLE_ENUM_SERIALIZATION 1
@@ -48,7 +59,8 @@ By default, `#!cpp JSON_DISABLE_ENUM_SERIALIZATION` is not defined.
 
 ??? example "Example 2: Serialize enum macro"
 
-    The code below forces the library **not** to create default serialization/deserialization functions `from_json` and `to_json`, but uses [`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md) to parse and serialize the enum.
+    The code below forces the library **not** to create default serialization/deserialization functions `from_json` and `to_json`, but uses
+    [`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md) to parse and serialize the enum.
 
     ```cpp
     #define JSON_DISABLE_ENUM_SERIALIZATION 1
@@ -80,7 +92,8 @@ By default, `#!cpp JSON_DISABLE_ENUM_SERIALIZATION` is not defined.
 
 ??? example "Example 3: User-defined serialization/deserialization functions"
 
-    The code below forces the library **not** to create default serialization/deserialization functions `from_json` and `to_json`, but uses user-defined functions to parse and serialize the enum.
+    The code below forces the library **not** to create default serialization/deserialization functions `from_json` and `to_json`, but uses user-defined
+    functions to parse and serialize the enum.
 
     ```cpp
     #define JSON_DISABLE_ENUM_SERIALIZATION 1

docs/mkdocs/docs/api/macros/json_has_ranges.md

@@ -13,6 +13,19 @@ The default value is detected based on the preprocessor macro `#!cpp __cpp_lib_r
 
 When the macro is not defined, the library will define it to its default value.
 
+## Examples
+
+??? example
+
+    The code below forces the library to enable support for ranges:
+
+    ```cpp
+    #define JSON_HAS_RANGES 1
+    #include <nlohmann/json.hpp>
+
+    ...
+    ```
+
 ## Version history
 
 - Added in version 3.11.0.

docs/mkdocs/docs/api/macros/json_has_three_way_comparison.md

@@ -14,6 +14,19 @@ and `#!cpp __cpp_lib_three_way_comparison`.
 
 When the macro is not defined, the library will define it to its default value.
 
+## Examples
+
+??? example
+
+    The code below forces the library to use 3-way comparison:
+
+    ```cpp
+    #define JSON_HAS_THREE_WAY_COMPARISON 1
+    #include <nlohmann/json.hpp>
+
+    ...
+    ```
+
 ## Version history
 
 - Added in version 3.11.0.

docs/mkdocs/docs/api/macros/json_use_implicit_conversions.md

@@ -7,9 +7,6 @@
 When defined to `0`, implicit conversions are switched off. By default, implicit conversions are switched on. The
 value directly affects [`operator ValueType`](../basic_json/operator_ValueType.md).
 
-Implicit conversions can also be controlled with the CMake option `JSON_ImplicitConversions` (`ON` by default) which
-sets `JSON_USE_IMPLICIT_CONVERSIONS` accordingly.
-
 ## Default definition
 
 By default, implicit conversions are enabled.
@@ -27,6 +24,12 @@ By default, implicit conversions are enabled.
     You can prepare existing code by already defining `JSON_USE_IMPLICIT_CONVERSIONS` to `0` and replace any implicit
     conversions with calls to [`get`](../basic_json/get.md).
 
+!!! hint "CMake option"
+
+    Implicit conversions can also be controlled with the CMake option
+    [`JSON_ImplicitConversions`](../../integration/cmake.md#json_legacydiscardedvaluecomparison)
+    (`ON` by default) which defines `JSON_USE_IMPLICIT_CONVERSIONS` accordingly.
+
 ## Examples
 
 ??? example

docs/mkdocs/docs/api/macros/json_use_legacy_discarded_value_comparison.md

@@ -56,6 +56,25 @@ When the macro is not defined, the library will define it to its default value.
     New code should not depend on it and existing code should try to remove or rewrite
     expressions relying on it.
 
+!!! hint "CMake option"
+
+    Legacy comparison can also be controlled with the CMake option
+    [`JSON_LegacyDiscardedValueComparison`](../../integration/cmake.md#json_legacydiscardedvaluecomparison)
+    (`OFF` by default) which defines `JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON` accordingly.
+
+## Examples
+
+??? example
+
+    The code below switches on the legacy discarded value comparison behavior in the library.
+
+    ```cpp
+    #define JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON 1
+    #include <nlohmann/json.hpp>
+
+    ...
+    ```
+
 ## Version history
 
 - Added in version 3.11.0.

docs/mkdocs/docs/api/macros/nlohmann_define_type_intrusive.md

@@ -40,10 +40,12 @@ See examples below for the concrete generated code.
 
 !!! info "Prerequisites"
 
-    1. The type `type` must be default constructible. See [How can I use `get()` for non-default constructible/non-copyable types?](../../features/arbitrary_types.md#how-can-i-use-get-for-non-default-constructiblenon-copyable-types)
+    1. The type `type` must be default constructible. See [How can I use `get()` for non-default constructible/non-copyable types?][GetNonDefNonCopy]
        for how to overcome this limitation.
     2. The macro must be used inside the type (class/struct).
 
+[GetNonDefNonCopy]: ../../features/arbitrary_types.md#how-can-i-use-get-for-non-default-constructiblenon-copyable-types
+
 !!! warning "Implementation limits"
 
     - The current implementation is limited to at most 64 member variables. If you want to serialize/deserialize types
@@ -116,7 +118,7 @@ See examples below for the concrete generated code.
 
 - [NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE / NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT](nlohmann_define_type_non_intrusive.md)
   for a similar macro that can be defined _outside_ the type.
-- [Arbitrary Types Conversions](../../features/arbitrary_types.md) for an overview.
+- [Arbitrary Type Conversions](../../features/arbitrary_types.md) for an overview.
 
 ## Version history
 

docs/mkdocs/docs/api/macros/nlohmann_define_type_non_intrusive.md

@@ -40,11 +40,13 @@ See examples below for the concrete generated code.
 
 !!! info "Prerequisites"
 
-    1. The type `type` must be default constructible. See [How can I use `get()` for non-default constructible/non-copyable types?](../../features/arbitrary_types.md#how-can-i-use-get-for-non-default-constructiblenon-copyable-types)
+    1. The type `type` must be default constructible. See [How can I use `get()` for non-default constructible/non-copyable types?][GetNonDefNonCopy]
        for how to overcome this limitation.
     2. The macro must be used outside the type (class/struct).
     3. The passed members must be public.
 
+[GetNonDefNonCopy]: ../../features/arbitrary_types.md#how-can-i-use-get-for-non-default-constructiblenon-copyable-types
+
 !!! warning "Implementation limits"
 
     - The current implementation is limited to at most 64 member variables. If you want to serialize/deserialize types
@@ -116,7 +118,7 @@ See examples below for the concrete generated code.
 
 - [NLOHMANN_DEFINE_TYPE_INTRUSIVE / NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT](nlohmann_define_type_intrusive.md)
   for a similar macro that can be defined _inside_ the type.
-- [Arbitrary Types Conversions](../../features/arbitrary_types.md) for an overview.
+- [Arbitrary Type Conversions](../../features/arbitrary_types.md) for an overview.
 
 ## Version history
 

docs/mkdocs/docs/features/arbitrary_types.md

@@ -1,4 +1,4 @@
-# Arbitrary Types Conversions
+# Arbitrary Type Conversions
 
 Every type can be serialized in JSON, not just STL containers and scalar types. Usually, you would do something along those lines:
 
@@ -219,7 +219,7 @@ namespace nlohmann {
 
 ## Can I write my own serializer? (Advanced use)
 
-Yes. You might want to take a look at [`unit-udt.cpp`](https://github.com/nlohmann/json/blob/develop/test/src/unit-udt.cpp) in the test suite, to see a few examples.
+Yes. You might want to take a look at [`unit-udt.cpp`](https://github.com/nlohmann/json/blob/develop/tests/src/unit-udt.cpp) in the test suite, to see a few examples.
 
 If you write your own serializer, you'll need to do a few things:
 

docs/mkdocs/docs/features/binary_formats/bjdata.md

@@ -9,7 +9,7 @@ unambigiously map common binary numeric types; furthermore, it uses little-endia
 (LE) to store all numerics instead of big-endian (BE) as in UBJSON to avoid
 unnecessary conversions on commonly available platforms.
 
-Compared to other binary-JSON-like formats such as MessagePack and CBOR, both BJData and
+Compared to other binary JSON-like formats such as MessagePack and CBOR, both BJData and
 UBJSON demonstrate a rare combination of being both binary and **quasi-human-readable**. This
 is because all semantic elements in BJData and UBJSON, including the data-type markers
 and name/string types are directly human-readable. Data stored in the BJData/UBJSON format
@@ -63,7 +63,7 @@ The library uses the following mapping from JSON values types to BJData types ac
 
 	The following values can **not** be converted to a BJData value:
 
-      - strings with more than 18446744073709551615 bytes (theoretical)
+      - strings with more than 18446744073709551615 bytes, i.e., $2^{64}-1$ bytes (theoretical)
 
 !!! info "Unused BJData markers"
 
@@ -84,36 +84,37 @@ The library uses the following mapping from JSON values types to BJData types ac
 	A breaking difference between BJData and UBJSON is the endianness
     of numerical values. In BJData, all numerical data types (integers
     `UiuImlML` and floating-point values `hdD`) are stored in the little-endian (LE)
-    byte order as opposed to big-endian as used by UBJSON. To adopt LE
+    byte order as opposed to big-endian as used by UBJSON. Adopting LE
     to store numeric records avoids unnecessary byte swapping on most modern
     computers where LE is used as the default byte order.
 
 !!! info "Optimized formats"
 
-	The optimized formats for containers are supported: Parameter
-    `use_size` adds size information to the beginning of a container and
-    removes the closing marker. Parameter `use_type` further checks
-    whether all elements of a container have the same type and adds the
-    type marker to the beginning of the container. The `use_type`
-    parameter must only be used together with `use_size = true`.
+	Optimized formats for containers are supported via two parameters of
+    [`to_bjdata`](../../api/basic_json/to_bjdata.md):
+
+    - Parameter `use_size` adds size information to the beginning of a container and
+      removes the closing marker.
+    - Parameter `use_type` further checks whether all elements of a container have the
+      same type and adds the type marker to the beginning of the container.
+      The `use_type` parameter must only be used together with `use_size = true`.
 
     Note that `use_size = true` alone may result in larger representations -
     the benefit of this parameter is that the receiving side is
-    immediately informed on the number of elements of the container.
+    immediately informed of the number of elements in the container.
 
 !!! info "ND-array optimized format"
 
-	BJData extends UBJSON's optimized array **size** marker to support
-    ND-array of uniform numerical data types (referred to as the *packed array*).
-    For example, 2-D `uint8` integer array `[[1,2],[3,4],[5,6]]` that can be stored
+	BJData extends UBJSON's optimized array **size** marker to support ND-arrays of
+    uniform numerical data types (referred to as *packed arrays*).
+    For example, the 2-D `uint8` integer array `[[1,2],[3,4],[5,6]]`, stored
     as nested optimized array in UBJSON `[ [$U#i2 1 2 [$U#i2 3 4 [$U#i2 5 6 ]`,
-    can be further compressed in BJData and stored as `[$U#[$i#i2 2 3 1 2 3 4 5 6`
+    can be further compressed in BJData to `[$U#[$i#i2 2 3 1 2 3 4 5 6`
     or `[$U#[i2 i3] 1 2 3 4 5 6`.
 
-    In order to maintain the type and dimension information of an ND-array,
-    when this library parses a BJData ND-array via `from_bjdata`, it converts the
-    data into a JSON object, following the **annotated array format** as defined in the
-    [JData specification (Draft 3)](https://github.com/NeuroJSON/jdata/blob/master/JData_specification.md#annotated-storage-of-n-d-arrays).
+    To maintina type and size information, ND-arrays are converted to JSON objects following the
+    **annotated array format** (defined in the [JData specification (Draft 3)][JDataAAFmt]),
+    when parsed using [`from_bjdata`](../../api/basic_json/from_bjdata.md).
     For example, the above 2-D `uint8` array can be parsed and accessed as
 
     ```json
@@ -124,14 +125,16 @@ The library uses the following mapping from JSON values types to BJData types ac
     }
     ```
 
-    In the reversed direction, when `to_bjdata` detects a JSON object in the
-    above form, it automatically converts such object into a BJData ND-array
-    to generate compact output. The only exception is that when the 1-D dimensional
-    vector stored in `"_ArraySize_"` contains a single integer, or two integers with
-    one being 1, a regular 1-D optimized array is generated.
+    Likewise, when a JSON object in the above form is serialzed using
+    [`to_bjdata`](../../api/basic_json/to_bjdata.md), it is automatically converted
+    into a compact BJData ND-array. The only exception is, that when the 1-dimensional
+    vector stored in `"_ArraySize_"` contains a single integer or two integers with one
+    being 1, a regular 1-D optimized array is generated.
 
-    The current version of this library has not yet supported automatic
-    recognition and conversion from a nested JSON array input to a BJData ND-array.
+    The current version of this library does not yet support automatic detection of and
+    conversion from a nested JSON array input to a BJData ND-array.
+
+    [JDataAAFmt]: https://github.com/NeuroJSON/jdata/blob/master/JData_specification.md#annotated-storage-of-n-d-arrays)
 
 !!! info "Restrictions in optimized data types for arrays and objects"
 
@@ -147,7 +150,7 @@ The library uses the following mapping from JSON values types to BJData types ac
 
 	If the JSON data contains the binary type, the value stored is a list
     of integers, as suggested by the BJData documentation.  In particular,
-    this means that serialization and the deserialization of a JSON
+    this means that the serialization and the deserialization of JSON
     containing binary values into BJData and back will result in a
     different JSON object.
 

docs/mkdocs/docs/home/exceptions.md

@@ -74,7 +74,7 @@ Exceptions in the library are thrown in the local context of the JSON value they
 
 To create better diagnostics messages, each JSON value needs a pointer to its parent value such that a global context (i.e., a path from the root value to the value that lead to the exception) can be created. That global context is provided as [JSON Pointer](../features/json_pointer.md).
 
-As this global context comes at the price of storing one additional pointer per JSON value and runtime overhead to maintain the parent relation, extended diagnostics are disabled by default. They can, however, be enabled by defining the preprocessor symbol [`JSON_DIAGNOSTICS`](../features/macros.md#json_diagnostics) to `1` before including `json.hpp`.
+As this global context comes at the price of storing one additional pointer per JSON value and runtime overhead to maintain the parent relation, extended diagnostics are disabled by default. They can, however, be enabled by defining the preprocessor symbol [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md) to `1` before including `json.hpp`.
 
 ??? example
 

docs/mkdocs/docs/home/faq.md

@@ -126,7 +126,7 @@ Yes, see [Parsing and exceptions](../features/parsing/parse_exceptions.md).
 
 	Can I get the key of the object item that caused an exception?
 
-Yes, you can. Please define the symbol [`JSON_DIAGNOSTICS`](../features/macros.md#json_diagnostics) to get [extended diagnostics messages](exceptions.md#extended-diagnostic-messages).
+Yes, you can. Please define the symbol [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md) to get [extended diagnostics messages](exceptions.md#extended-diagnostic-messages).
 
 
 ## Serialization issues

docs/mkdocs/docs/integration/cmake.md

@@ -135,7 +135,12 @@ Enable CI build targets. The exact targets are used during the several CI steps
 
 ### `JSON_Diagnostics`
 
-Enable [extended diagnostic messages](../home/exceptions.md#extended-diagnostic-messages) by defining macro [`JSON_DIAGNOSTICS`](../features/macros.md#json_diagnostics). This option is `OFF` by default.
+Enable [extended diagnostic messages](../home/exceptions.md#extended-diagnostic-messages) by defining macro [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md). This option is `OFF` by default.
+
+### `JSON_DisableEnumSerialization`
+
+Disable default `enum` serialization by defining the macro
+[`JSON_DISABLE_ENUM_SERIALIZATION`](../api/macros/json_disable_enum_serialization.md). This option is `OFF` by default.
 
 ### `JSON_FastTests`
 
@@ -143,7 +148,7 @@ Skip expensive/slow test suites. This option is `OFF` by default. Depends on `JS
 
 ### `JSON_ImplicitConversions`
 
-Enable implicit conversions by defining macro [`JSON_USE_IMPLICIT_CONVERSIONS`](../features/macros.md#json_use_implicit_conversions). This option is `ON` by default.
+Enable implicit conversions by defining macro [`JSON_USE_IMPLICIT_CONVERSIONS`](../api/macros/json_use_implicit_conversions.md). This option is `ON` by default.
 
 ### `JSON_Install`