more

doc/tutorial.mld

···
 Before diving in, it's worth understanding the difference between JSON
 Pointer and JSON Path, as they serve different purposes:
 
-{b JSON Pointer} (RFC 6901) is an {e indicator syntax} that specifies a
+{b JSON Pointer} ({{:https://datatracker.ietf.org/doc/html/rfc6901}RFC 6901}) is an {e indicator syntax} that specifies a
 {e single location} within JSON data. It always identifies at most one
 value.
 
···
 
 {1 What is JSON Pointer?}
 
-From RFC 6901, Section 1:
+From {{:https://datatracker.ietf.org/doc/html/rfc6901#section-1}RFC 6901, Section 1}:
 
 {i JSON Pointer defines a string syntax for identifying a specific value
 within a JavaScript Object Notation (JSON) document.}
···
 
 {1 Syntax: Reference Tokens}
 
-RFC 6901, Section 3 defines the syntax:
+{{:https://datatracker.ietf.org/doc/html/rfc6901#section-3}RFC 6901, Section 3} defines the syntax:
 
 {i A JSON Pointer is a Unicode string containing a sequence of zero or more
 reference tokens, each prefixed by a '/' (%x2F) character.}
···
 
 {1 Evaluation: Navigating JSON}
 
-Now we come to the heart of JSON Pointer: evaluation. RFC 6901, Section 4
+Now we come to the heart of JSON Pointer: evaluation. {{:https://datatracker.ietf.org/doc/html/rfc6901#section-4}RFC 6901, Section 4}
 describes how a pointer is resolved against a JSON document:
 
 {i Evaluation of a JSON Pointer begins with a reference to the root value
···
 the document. Each reference token in the JSON Pointer is evaluated
 sequentially.}
 
-Let's use the example JSON document from RFC 6901, Section 5:
+Let's use the example JSON document from {{:https://datatracker.ietf.org/doc/html/rfc6901#section-5}RFC 6901, Section 5}:
 
 {x@ocaml[
 # let rfc_example = parse_json {|{
···
 
 {2 Array Index Rules}
 
-RFC 6901 has specific rules for array indices. Section 4 states:
+{{:https://datatracker.ietf.org/doc/html/rfc6901}RFC 6901} has specific rules for array indices. {{:https://datatracker.ietf.org/doc/html/rfc6901#section-4}Section 4} states:
 
 {i characters comprised of digits [...] that represent an unsigned base-10
 integer value, making the new referenced value the array element with
···
 
 {1 The End-of-Array Marker: [-] and Type Safety}
 
-RFC 6901, Section 4 introduces a special token:
+{{:https://datatracker.ietf.org/doc/html/rfc6901#section-4}RFC 6901, Section 4} introduces a special token:
 
 {i exactly the single character "-", making the new referenced value the
 (nonexistent) member after the last array element.}
 
 This [-] marker is unique to JSON Pointer (JSON Path has no equivalent).
-It's primarily useful for JSON Patch operations (RFC 6902) to append
+It's primarily useful for JSON Patch operations ({{:https://datatracker.ietf.org/doc/html/rfc6902}RFC 6902}) to append
 elements to arrays.
 
 {2 Navigation vs Append Pointers}
···
 
 {1 Mutation Operations}
 
-While RFC 6901 defines JSON Pointer for read-only access, RFC 6902
+While {{:https://datatracker.ietf.org/doc/html/rfc6901}RFC 6901} defines JSON Pointer for read-only access, {{:https://datatracker.ietf.org/doc/html/rfc6902}RFC 6902}
 (JSON Patch) uses JSON Pointer for modifications. The [json-pointer]
 library provides these operations.
 
···
 
 {1:escaping Escaping Special Characters}
 
-RFC 6901, Section 3 explains the escaping rules:
+{{:https://datatracker.ietf.org/doc/html/rfc6901#section-3}RFC 6901, Section 3} explains the escaping rules:
 
 {i Because the characters '~' (%x7E) and '/' (%x2F) have special meanings
 in JSON Pointer, '~' needs to be encoded as '~0' and '/' needs to be
···
 
 {2 The Order Matters!}
 
-RFC 6901, Section 4 is careful to specify the unescaping order:
+{{:https://datatracker.ietf.org/doc/html/rfc6901#section-4}RFC 6901, Section 4} is careful to specify the unescaping order:
 
 {i Evaluation of each reference token begins by decoding any escaped
 character sequence. This is performed by first transforming any
···
 
 {1 URI Fragment Encoding}
 
-JSON Pointers can be embedded in URIs. RFC 6901, Section 6 explains:
+JSON Pointers can be embedded in URIs. {{:https://datatracker.ietf.org/doc/html/rfc6901#section-6}RFC 6901, Section 6} explains:
 
 {i A JSON Pointer can be represented in a URI fragment identifier by
 encoding it into octets using UTF-8, while percent-encoding those
-characters not allowed by the fragment rule in RFC 3986.}
+characters not allowed by the fragment rule in {{:https://datatracker.ietf.org/doc/html/rfc3986}RFC 3986}.}
 
 This adds percent-encoding on top of the [~0]/[~1] escaping:
 
···
 - : Jsont.json = {"tasks":["buy milk","call mom"]}
 ]x}
 
-This is useful for implementing JSON Patch ([RFC 6902]) where
+This is useful for implementing JSON Patch ({{:https://datatracker.ietf.org/doc/html/rfc6902}RFC 6902}) where
 operations like ["add"] can target either existing positions or the
 append marker. If you need to distinguish between pointer types at runtime,
 use {!of_string_kind} which returns a polymorphic variant:
···
 
 {1 Summary}
 
-JSON Pointer (RFC 6901) provides a simple but powerful way to address
+JSON Pointer ({{:https://datatracker.ietf.org/doc/html/rfc6901}RFC 6901}) provides a simple but powerful way to address
 values within JSON documents:
 
 {ol
···
 {- {b Escaping}: Use [~0] for [~] and [~1] for [/] in tokens (handled automatically by the library)}
 {- {b Evaluation}: Tokens navigate through objects (by key) and arrays (by index)}
 {- {b URI Encoding}: Pointers can be percent-encoded for use in URIs}
-{- {b Mutations}: Combined with JSON Patch (RFC 6902), pointers enable structured updates}
+{- {b Mutations}: Combined with JSON Patch ({{:https://datatracker.ietf.org/doc/html/rfc6902}RFC 6902}), pointers enable structured updates}
 {- {b Type Safety}: Phantom types ([nav t] vs [append t]) prevent misuse of append pointers with retrieval operations, while the [any] existential type allows ergonomic use with mutation operations}
 }
 

dune-project

···
   (ocaml (>= 4.14.0))
   (jsont (>= 0.2.0))
   (bytesrw (>= 0.2.0))
+  mdx
   (odoc :with-doc)))