diff --git a/docs/index.mld b/docs/index.mld index 057b98a..4f21d5f 100644 --- a/docs/index.mld +++ b/docs/index.mld @@ -3,9 +3,9 @@ {1 Links} {ul - {- {{!page:quickstart} Quickstart tutorial}} - {- {{!page:design} Our design philosophy}} - {- {{!module:Asai} API reference}}} + {- {{!page:quickstart} 🔰 Quickstart tutorial}} + {- {{!page:design} 💡 Our design philosophy}} + {- {{!module:Asai} 📔 API reference}}} {1 What is "asai"?} diff --git a/docs/quickstart.mld b/docs/quickstart.mld index ceb7419..2f6f20e 100644 --- a/docs/quickstart.mld +++ b/docs/quickstart.mld @@ -1,6 +1,6 @@ {0 Quick Start} -This tutorial is for an implementer to adopt this library as quickly as possible. We will assume you are already familiar with OCaml and are using a typical OCaml package structure. +This tutorial is for an implementer (you!) to adopt this library as quickly as possible. We will assume you are already familiar with OCaml and are using a typical OCaml package structure. {1 Define Error Codes} @@ -47,7 +47,7 @@ where [Greeting] is the message code of this message. The fancier version is {{! {[ Logger.emitf TypeError "@[<2>This term doesn't look right:@ %a@]" Syntax.pp term ]} -Note that you should not include any control characters (for example newlines [\n]) anywhere when using {{!val:Asai.Logger.S.emitf}emitf}. Use break hints (such as [@,] and [@ ]) and boxes instead. If you must, use forced newlines ([@\n]). See {!module:Stdlib.Format} for more information on boxes and break hints. +Note that you should not include any control character (for example the newline character [\n]) anywhere when using {{!val:Asai.Logger.S.emitf}emitf}. Use break hints (such as [@,] and [@ ]) and boxes instead. If you must, use forced newlines ([@\n]). See {!module:Stdlib.Format} for more information on boxes and break hints. If you wish to terminate the execution after issuing a message instead of continuing the execution, use {{!val:Asai.Logger.S.fatal}fatal} instead of {{!val:Asai.Logger.S.emit}emit}. There's also a fancier {{!val:Asai.Logger.S.fatalf}fatalf} that works in the same way as {{!val:Asai.Logger.S.emitf}emitf}. diff --git a/src/DiagnosticData.ml b/src/DiagnosticData.ml index f003ba0..2008f9c 100644 --- a/src/DiagnosticData.ml +++ b/src/DiagnosticData.ml @@ -25,7 +25,7 @@ end When we render a diagnostic, the layout engine of the rendering backend should be the one making layout choices. Therefore, we cannot pass already formatted strings. Instead, a text is defined to be a function that takes a formatter and uses it to render the content. The following two conditions must be satisfied: + {b All string (and character) literals must be encoded using UTF-8.} - + {b All string (and character) literals must not contain control characters (such as newlines [\n]).} It is okay to have break hints (such as [@,] and [@ ]) but not literal control characters. This means you should avoid pre-formatted strings, and if you must use them, use {!val:text} to convert newline characters. Control characters include `U+0000-001F` (C0 controls), `U+007F` (backspace), and `U+0080-009F` (C1 controls); in particular, `U+000A` (newline) is a C0 control character. These characters are banned because they would mess up the cursor position. *) + + {b All string (and character) literals must not contain control characters (such as the newline character [\n]).} It is okay to have break hints (such as [@,] and [@ ]) but not literal control characters. This means you should avoid pre-formatted strings, and if you must use them, use {!val:text} to convert newline characters. Control characters include `U+0000-001F` (C0 controls), `U+007F` (backspace) and `U+0080-009F` (C1 controls). These characters are banned because they would mess up the cursor position. *) type text = Format.formatter -> unit (** A message is a located {!type:text}. *)