dream.mli: use #folders-and-files in example links (#360)

src/dream.mli

@@ -21,11 +21,11 @@ and response = server message
 
 and handler = request -> response promise
 (** Handlers are asynchronous functions from requests to responses. Example
-    {{:https://github.com/aantron/dream/tree/master/example/1-hello#files}
+    {{:https://github.com/aantron/dream/tree/master/example/1-hello#folders-and-files}
     [1-hello]} shows the simplest handler, an anonymous function which we pass
     to {!Dream.run}. This creates a complete Web server! You can also see the
     Reason version in example
-    {{:https://github.com/aantron/dream/tree/master/example/r-hello#files}
+    {{:https://github.com/aantron/dream/tree/master/example/r-hello#folders-and-files}
     [r-hello]}.
 
     {[
@@ -37,7 +37,7 @@ and handler = request -> response promise
 and middleware = handler -> handler
 (** Middlewares are functions that take a {!handler}, and run some code before
     or after — producing a “bigger” handler. Example
-    {{:https://github.com/aantron/dream/tree/master/example/2-middleware#files}
+    {{:https://github.com/aantron/dream/tree/master/example/2-middleware#folders-and-files}
     [2-middleware]} inserts the {!Dream.logger} middleware into a Web app:
 
     {[
@@ -48,9 +48,9 @@ and middleware = handler -> handler
     ]}
 
     Examples
-    {{:https://github.com/aantron/dream/tree/master/example/4-counter#files}
+    {{:https://github.com/aantron/dream/tree/master/example/4-counter#folders-and-files}
     [4-counter]} and
-    {{:https://github.com/aantron/dream/tree/master/example/5-promise#files}
+    {{:https://github.com/aantron/dream/tree/master/example/5-promise#folders-and-files}
     [5-promise]} show user-defined middlewares:
 
     {[
@@ -72,7 +72,7 @@ and middleware = handler -> handler
 and route
 (** Routes tell {!Dream.router} which handler to select for each request. See
     {!section-routing} and example
-    {{:https://github.com/aantron/dream/tree/master/example/3-router#files}
+    {{:https://github.com/aantron/dream/tree/master/example/3-router#folders-and-files}
     [3-router]}. Routes are created by helpers such as {!Dream.get} and
     {!Dream.scope}:
 
@@ -122,7 +122,7 @@ and server = Dream_pure.Message.server
 and 'a promise = 'a Lwt.t
 (** Dream uses {{:https://github.com/ocsigen/lwt} Lwt} for promises and
     asynchronous I/O. See example
-    {{:https://github.com/aantron/dream/tree/master/example/5-promise#files}
+    {{:https://github.com/aantron/dream/tree/master/example/5-promise#folders-and-files}
     [5-promise]}.
 
     Use [raise] to reject promises. If you are writing a library, you may prefer
@@ -402,7 +402,7 @@ val query : request -> string -> string option
 (** First query parameter with the given name. See
     {{:https://tools.ietf.org/html/rfc3986#section-3.4} RFC 3986 §3.4} and
     example
-    {{:https://github.com/aantron/dream/tree/master/example/w-query#files}
+    {{:https://github.com/aantron/dream/tree/master/example/w-query#folders-and-files}
     [w-query]}. *)
 
 val queries : request -> string -> string list
@@ -449,7 +449,7 @@ val html :
 
     As your Web app develops, consider adding [Content-Security-Policy] headers,
     as described in example
-    {{:https://github.com/aantron/dream/tree/master/example/w-content-security-policy#files}
+    {{:https://github.com/aantron/dream/tree/master/example/w-content-security-policy#folders-and-files}
     [w-content-security-policy]}. These headers are completely optional, but
     they can provide an extra layer of defense for a mature app. *)
 
@@ -460,7 +460,7 @@ val json :
     string -> response promise
 (** Same as {!Dream.respond}, but adds [Content-Type: application/json]. See
     {!Dream.application_json} and example
-    {{:https://github.com/aantron/dream/tree/master/example/e-json#files}
+    {{:https://github.com/aantron/dream/tree/master/example/e-json#folders-and-files}
     [e-json]}. *)
 
 val redirect :
@@ -526,7 +526,7 @@ val set_header : 'a message -> string -> string -> unit
     {!Dream.set_cookie} and {!Dream.cookie} are designed for round-tripping
     secure cookies. The most secure settings applicable to the current server
     are inferred automatically. See example
-    {{:https://github.com/aantron/dream/tree/master/example/c-cookie#files}
+    {{:https://github.com/aantron/dream/tree/master/example/c-cookie#folders-and-files}
     [c-cookie]}.
 
     {[
@@ -568,7 +568,7 @@ val set_cookie :
     decrypt cookies from prior starts.
 
     See example
-    {{:https://github.com/aantron/dream/tree/master/example/c-cookie#files}
+    {{:https://github.com/aantron/dream/tree/master/example/c-cookie#folders-and-files}
     [c-cookie]}.
 
     Most of the optional arguments are for overriding inferred defaults.
@@ -655,7 +655,7 @@ val cookie :
   ?secure:bool ->
     request -> string -> string option
 (** First cookie with the given name. See example
-    {{:https://github.com/aantron/dream/tree/master/example/c-cookie#files}
+    {{:https://github.com/aantron/dream/tree/master/example/c-cookie#folders-and-files}
     [c-cookie]}.
 
     {[
@@ -676,7 +676,7 @@ val all_cookies : request -> (string * string) list
 
 val body : 'a message -> string promise
 (** Retrieves the entire body. See example
-    {{:https://github.com/aantron/dream/tree/master/example/6-echo#files}
+    {{:https://github.com/aantron/dream/tree/master/example/6-echo#folders-and-files}
     [6-echo]}. *)
 
 val set_body : 'a message -> string -> unit
@@ -700,7 +700,7 @@ val stream :
     (stream -> unit promise) -> response promise
 (** Creates a response with a {!type-stream} open for writing, and passes the
     stream to the callback when it is ready. See example
-    {{:https://github.com/aantron/dream/tree/master/example/j-stream#files}
+    {{:https://github.com/aantron/dream/tree/master/example/j-stream#folders-and-files}
     [j-stream]}.
 
     {[
@@ -714,7 +714,7 @@ val stream :
 
 val read : stream -> string option promise
 (** Retrieves a body chunk. See example
-    {{:https://github.com/aantron/dream/tree/master/example/j-stream#files}
+    {{:https://github.com/aantron/dream/tree/master/example/j-stream#folders-and-files}
     [j-stream]}. *)
 (* TODO Document difference between receiving a request and receiving on a
    WebSocket. *)
@@ -848,7 +848,7 @@ val websocket :
 (** Creates a fresh [101 Switching Protocols] response. Once this response is
     returned to Dream's HTTP layer, the callback is passed a new
     {!type-websocket}, and the application can begin using it. See example
-    {{:https://github.com/aantron/dream/tree/master/example/k-websocket#files}
+    {{:https://github.com/aantron/dream/tree/master/example/k-websocket#folders-and-files}
     [k-websocket]}.
 
     {[
@@ -909,7 +909,7 @@ val close_websocket : ?code:int -> websocket -> unit promise
     for generating JSON parsers and serializers for OCaml data types.
 
     See example
-    {{:https://github.com/aantron/dream/tree/master/example/e-json#files}
+    {{:https://github.com/aantron/dream/tree/master/example/e-json#folders-and-files}
     [e-json]}. *)
 
 val origin_referrer_check : middleware
@@ -961,7 +961,7 @@ val origin_referrer_check : middleware
     ]}
 
     See example
-    {{:https://github.com/aantron/dream/tree/master/example/d-form#files}
+    {{:https://github.com/aantron/dream/tree/master/example/d-form#folders-and-files}
     [d-form]}. *)
 
 type 'a form_result = [
@@ -975,7 +975,7 @@ type 'a form_result = [
 ]
 (** Form CSRF checking results, in order from least to most severe. See
     {!Dream.val-form} and example
-    {{:https://github.com/aantron/dream/tree/master/example/d-form#files}
+    {{:https://github.com/aantron/dream/tree/master/example/d-form#folders-and-files}
     [d-form]}.
 
     The first three constructors, [`Ok], [`Expired], and [`Wrong_session] can
@@ -1060,7 +1060,7 @@ type multipart_form =
     ]}
 
     See example
-    {{:https://github.com/aantron/dream/tree/master/example/g-upload#files}
+    {{:https://github.com/aantron/dream/tree/master/example/g-upload#folders-and-files}
     [g-upload]} and {{:https://datatracker.ietf.org/doc/html/rfc7578} RFC 7578}.
 
     Note that clients such as curl can send files with no filename ([None]),
@@ -1090,7 +1090,7 @@ val multipart : ?csrf:bool -> request -> multipart_form form_result promise
     ]}
 
     See section {!section-templates}, and example
-    {{:https://github.com/aantron/dream/tree/master/example/g-upload#files}
+    {{:https://github.com/aantron/dream/tree/master/example/g-upload#folders-and-files}
     [g-upload]}.
 
     Note that, like {!Dream.form}, this function sorts form fields by field
@@ -1193,18 +1193,18 @@ let render message =
     v}
 
     See examples
-    {{:https://github.com/aantron/dream/tree/master/example/7-template#files}
+    {{:https://github.com/aantron/dream/tree/master/example/7-template#folders-and-files}
     [7-template]} and
-    {{:https://github.com/aantron/dream/tree/master/example/r-template#files}
+    {{:https://github.com/aantron/dream/tree/master/example/r-template#folders-and-files}
     [r-template]}.
 
     There is also a typed alternative, provided by an external library,
     {{:https://github.com/ocsigen/tyxml} TyXML}. It is shown in example
-    {{:https://github.com/aantron/dream/tree/master/example/w-tyxml#files}
+    {{:https://github.com/aantron/dream/tree/master/example/w-tyxml#folders-and-files}
     [w-tyxml]}. If you are using Reason syntax, TyXML can be used with
     {{:https://ocsigen.org/tyxml/latest/manual/jsx} server-side JSX}. See
     example
-    {{:https://github.com/aantron/dream/tree/master/example/r-tyxml#files}
+    {{:https://github.com/aantron/dream/tree/master/example/r-tyxml#folders-and-files}
     [r-tyxml]}.
 
     To use the built-in templates, add this to [dune]:
@@ -1227,9 +1227,9 @@ let render message =
     supported presently is [%% response] for streaming the template using
     {!Dream.write}, to a {!type-response} that is in scope. This is shown in
     examples
-    {{:https://github.com/aantron/dream/tree/master/example/w-template-stream#files}
+    {{:https://github.com/aantron/dream/tree/master/example/w-template-stream#folders-and-files}
     [w-template-stream]} and
-    {{:https://github.com/aantron/dream/tree/master/example/r-template-stream#files}
+    {{:https://github.com/aantron/dream/tree/master/example/r-template-stream#folders-and-files}
     [r-template-stream]}.
 
     A template ends...
@@ -1360,7 +1360,7 @@ val router : route list -> handler
 (** Creates a router. If none of the routes match the request, the router
     responds with [404 Not Found]. Route components starting with [:] are
     parameters, which can be retrieved with {!Dream.param}. See example
-    {{:https://github.com/aantron/dream/tree/master/example/3-router#files}
+    {{:https://github.com/aantron/dream/tree/master/example/3-router#folders-and-files}
     [3-router]}.
 
     {[
@@ -1481,7 +1481,7 @@ val static :
   ?loader:(string -> string -> handler) ->
     string -> handler
 (** Serves static files from a local directory. See example
-    {{:https://github.com/aantron/dream/tree/master/example/f-static#files}
+    {{:https://github.com/aantron/dream/tree/master/example/f-static#folders-and-files}
     [f-static]}.
 
     {[
@@ -1506,7 +1506,7 @@ val static :
     - [path] is what was substituted for [**].
 
     The default loader is {!Dream.from_filesystem}. See example
-    {{:https://github.com/aantron/dream/tree/master/example/w-one-binary#files}
+    {{:https://github.com/aantron/dream/tree/master/example/w-one-binary#folders-and-files}
     [w-one-binary]} for a loader that serves files from memory instead. *)
 
 val from_filesystem : string -> string -> handler
@@ -1563,7 +1563,7 @@ val mime_lookup : string -> (string * string) list
     the next request that it is assigned to.
 
     See example
-    {{:https://github.com/aantron/dream/tree/master/example/b-session#files}
+    {{:https://github.com/aantron/dream/tree/master/example/b-session#folders-and-files}
     [b-session]}. *)
 
 val session_field : request -> string -> string option
@@ -1624,7 +1624,7 @@ val session_expires_at : request -> float
     Flash messages are short strings which are stored in cookies during one
     request, to be made available for the next request. The typical use case is
     to provide form feedback across a redirect. See example
-    {{:https://github.com/aantron/dream/tree/master/example/w-flash#files}
+    {{:https://github.com/aantron/dream/tree/master/example/w-flash#folders-and-files}
     [w-flash]}. *)
 
 val flash : middleware
@@ -1643,11 +1643,11 @@ val add_flash_message : request -> string -> string -> unit
     Dream integrates {{:https://github.com/andreas/ocaml-graphql-server#readme}
     ocaml-graphql-server}. See examples:
 
-    - {{:https://github.com/aantron/dream/tree/master/example/i-graphql#files}
+    - {{:https://github.com/aantron/dream/tree/master/example/i-graphql#folders-and-files}
       [i-graphql]}
-    - {{:https://github.com/aantron/dream/tree/master/example/r-graphql#files}
+    - {{:https://github.com/aantron/dream/tree/master/example/r-graphql#folders-and-files}
       [r-graphql]}
-    - {{:https://github.com/aantron/dream/tree/master/example/w-graphql-subscription#files}
+    - {{:https://github.com/aantron/dream/tree/master/example/w-graphql-subscription#folders-and-files}
       [w-graphql-subscription]}.
 
     If you are also
@@ -1719,7 +1719,7 @@ val graphiql : ?default_query:string -> string -> handler
     Dream provides thin convenience functions over
     {{:https://github.com/paurkedal/ocaml-caqti/#readme} Caqti}, an SQL
     interface with several back ends. See example
-    {{:https://github.com/aantron/dream/tree/master/example/h-sql#files}
+    {{:https://github.com/aantron/dream/tree/master/example/h-sql#folders-and-files}
     [h-sql]}.
 
     Dream installs the core {{:https://opam.ocaml.org/packages/caqti/} [caqti]}
@@ -1754,7 +1754,7 @@ val sql_pool : ?size:int -> string -> middleware
 
 val sql : request -> (Caqti_lwt.connection -> 'a promise) -> 'a promise
 (** Runs the callback with a connection from the SQL pool. See example
-    {{:https://github.com/aantron/dream/tree/master/example/h-sql#files}
+    {{:https://github.com/aantron/dream/tree/master/example/h-sql#folders-and-files}
     [h-sql]}.
 
     {[
@@ -1784,7 +1784,7 @@ val sql : request -> (Caqti_lwt.connection -> 'a promise) -> 'a promise
 
 val logger : middleware
 (** Logs and times requests. Time spent logging is included. See example
-    {{:https://github.com/aantron/dream/tree/master/example/2-middleware#files}
+    {{:https://github.com/aantron/dream/tree/master/example/2-middleware#folders-and-files}
     [2-middleware]}. *)
 
 val log : ('a, Format.formatter, unit, unit) format4 -> 'a
@@ -1793,7 +1793,7 @@ val log : ('a, Format.formatter, unit, unit) format4 -> 'a
     {{:https://v2.ocaml.org/api/Printf.html#VALfprintf} [Printf]} and
     {{:https://v2.ocaml.org/api/Format.html#VALfprintf} [Format]}. The rest of
     the arguments are determined by the format string. See example
-    {{:https://github.com/aantron/dream/tree/master/example/a-log#files}
+    {{:https://github.com/aantron/dream/tree/master/example/a-log#folders-and-files}
     [a-log]}.
 
     {[
@@ -1820,7 +1820,7 @@ val error     : ('a, unit) conditional_log
 (** Formats a message and writes it to the log at level [`Error]. The inner
     formatting function is called only if the {{!initialize_log} current log
     level} is [`Error] or higher. See example
-    {{:https://github.com/aantron/dream/tree/master/example/a-log#files}
+    {{:https://github.com/aantron/dream/tree/master/example/a-log#folders-and-files}
     [a-log]}.
 
     {[
@@ -1865,7 +1865,7 @@ val sub_log : ?level:[< log_level] -> string -> sub_log
     unless {!Dream.set_log_level} is used.
 
     See [README] of example
-    {{:https://github.com/aantron/dream/tree/master/example/a-log#files}
+    {{:https://github.com/aantron/dream/tree/master/example/a-log#folders-and-files}
     [a-log]}. *)
 
 val initialize_log :
@@ -2043,7 +2043,7 @@ type error_handler = error -> response option promise
 val error_template :
   (error -> string -> response -> response promise) -> error_handler
 (** Builds an {!error_handler} from a template. See example
-    {{:https://github.com/aantron/dream/tree/master/example/9-error#files}
+    {{:https://github.com/aantron/dream/tree/master/example/9-error#folders-and-files}
     [9-error]}.
 
     {[
@@ -2127,19 +2127,19 @@ val run :
       promise that never resolves.
     - [~error_handler] handles all errors, both from the application, and
       low-level errors. See {!section-errors} and example
-      {{:https://github.com/aantron/dream/tree/master/example/9-error#files}
+      {{:https://github.com/aantron/dream/tree/master/example/9-error#folders-and-files}
       [9-error]}.
       {!Dream.debug_error_handler} is a default error handler that can be passed
       here to help debug Web apps. See example
-      {{:https://github.com/aantron/dream/tree/master/example/8-debug#files}
+      {{:https://github.com/aantron/dream/tree/master/example/8-debug#folders-and-files}
       [8-debug]}.
     - [~tls:true] enables TLS. You should also specify [~certificate_file] and
       [~key_file]. However, for development, Dream includes an insecure
       compiled-in
-      {{:https://github.com/aantron/dream/tree/master/src/certificate#files}
+      {{:https://github.com/aantron/dream/tree/master/src/certificate#folders-and-files}
       localhost certificate}. Enabling HTTPS also enables transparent upgrading
       of connections to HTTP/2. See example
-      {{:https://github.com/aantron/dream/tree/master/example/l-https#files}
+      {{:https://github.com/aantron/dream/tree/master/example/l-https#folders-and-files}
       [l-https]}.
     - [~certificate_file] and [~key_file] specify the certificate and key file,
       respectively, when using [~tls]. They are not required for development,