Add documentation for extend sax parser

docs/mkdocs/docs/api/json_sax/index.md

@@ -37,8 +37,11 @@ processing the input.
 - [**start_array**](start_array.md) (_virtual_) - the beginning of an array was read
 - [**start_object**](start_object.md) (_virtual_) - the beginning of an object was read
 - [**string**](string.md) (_virtual_) - a string value was read
+- [**next_token_start**](next_token_start.md) - called to provide the start of the next element in the parsed input.
+- [**next_token_end**](next_token_end.md) - called to provide the end (one past convention) of the next element in the parsed input.
 
 ## Version history
 
 - Added in version 3.2.0.
 - Support for binary values (`binary_t`, `binary`) added in version 3.8.0.
+- Support for parser location information (`next_token_start`, `next_token_end`) added in version ???.???.???.

docs/mkdocs/docs/api/json_sax/next_token_end.md

@@ -0,0 +1,73 @@
+# <small>nlohmann::json_sax::</small>next_token_end
+
+Informs the sax parser about the end of the next element.
+There are two possible signatures for this method:
+
+1. 
+```cpp
+void next_token_end(std::size_t pos);
+```
+This version is called with the byte position after the next element ends. This version also works when parsing binary formats such as [msgpack](../basic_json/input_format_t.md).
+
+2. 
+```cpp
+template<class BasicJsonType, class InputAdapterType>
+void next_token_end(const nlohmann::detail::lexer<BasicJsonType, InputAdapterType>& lex)
+```
+This version is called with the lexer after the last character of the next element was parsed. The lexer can provide additional information about the current parse context. This version only available when calling `nlohmann::json::sax_parse` with `nlohmann::json::input_format_t::json` and takes precedence.
+
+## Template parameters
+1. 
+(none)
+2. 
+`BasicJsonType`
+:   a specialization of `basic_json` used by the lexer. (Leave this as a template parameter)
+`InputAdapterType`
+:   The input adapter used by the lexer. (Leave this as a template parameter)
+
+## Parameters
+1. 
+`pos` (in)
+:   Byte position one after the next elements last byte.
+2. 
+`lex` (in)
+:   Lexer after the last char of the next element was parsed.
+
+## Notes
+
+Implementing either version is optional, and no function is called if neither version of `next_token_end` is available in the sax parser.
+
+It is recommended, but not required, to also implement [next_token_start](next_token_start.md).
+
+## Examples
+
+??? example
+
+    The example below shows a SAX parser using the first version of this method to log the location.
+
+    ```cpp
+    --8<-- "examples/sax_parse_with_src_location.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/sax_parse_with_src_location.output"
+    ```
+
+??? example
+
+    The example below shows a SAX parser using the second version of this method and storing the location information in each json node using a [base class](../basic_json/json_base_class_t.md) for `nlohmann::json` as customization point.
+
+    ```cpp
+    --8<-- "examples/sax_parse_with_src_location_in_json.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/sax_parse_with_src_location_in_json.output"
+    ```
+## Version history
+
+- Added in version ???.???.???.

docs/mkdocs/docs/api/json_sax/next_token_start.md

@@ -0,0 +1,73 @@
+# <small>nlohmann::json_sax::</small>next_token_start
+
+Informs the sax parser about the start of the next element.
+There are two possible signatures for this method:
+
+1. 
+```cpp
+void next_token_start(std::size_t pos);
+```
+This version is called with the byte position where the next element starts. This version also works when parsing binary formats such as [msgpack](../basic_json/input_format_t.md).
+
+2. 
+```cpp
+template<class BasicJsonType, class InputAdapterType>
+void next_token_start(const nlohmann::detail::lexer<BasicJsonType, InputAdapterType>& lex)
+```
+This version is called with the lexer after the first character of the next element was parsed. The lexer can provide additional information about the current parse context. This version only available when calling `nlohmann::json::sax_parse` with `nlohmann::json::input_format_t::json` and takes precedence.
+
+## Template parameters
+1. 
+(none)
+2. 
+`BasicJsonType`
+:   a specialization of `basic_json` used by the lexer. (Leave this as a template parameter)
+`InputAdapterType`
+:   The input adapter used by the lexer. (Leave this as a template parameter)
+
+## Parameters
+1. 
+`pos` (in)
+:   Byte position where the next element starts.
+2. 
+`lex` (in)
+:   Lexer after the first char of the next element was parsed.
+
+## Notes
+
+Implementing either version is optional, and no function is called if neither version of `next_token_start` is available in the sax parser.
+
+It is recommended, but not required, to also implement [next_token_end](next_token_end.md).
+
+## Examples
+
+??? example
+
+    The example below shows a SAX parser using the first version of this method to log the location.
+
+    ```cpp
+    --8<-- "examples/sax_parse_with_src_location.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/sax_parse_with_src_location.output"
+    ```
+
+??? example
+
+    The example below shows a SAX parser using the second version of this method and storing the location information in each json node using a [base class](../basic_json/json_base_class_t.md) for `nlohmann::json` as customization point.
+
+    ```cpp
+    --8<-- "examples/sax_parse_with_src_location_in_json.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/sax_parse_with_src_location_in_json.output"
+    ```
+## Version history
+
+- Added in version ???.???.???.