From b0accb11f1aade55e9fc4dc0a1c1d1b8362ab5d9 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Wed, 22 Jun 2022 16:41:04 +0200 Subject: Add docs on encoding to definition, destination --- src/construct/autolink.rs | 4 ++-- src/construct/definition.rs | 10 ++++++++- src/construct/partial_destination.rs | 40 ++++++++++++++++++++++++++++++++---- 3 files changed, 47 insertions(+), 7 deletions(-) (limited to 'src') diff --git a/src/construct/autolink.rs b/src/construct/autolink.rs index 84c483d..33cb3f0 100644 --- a/src/construct/autolink.rs +++ b/src/construct/autolink.rs @@ -23,8 +23,8 @@ //! The maximum allowed size of a domain is `63` (inclusive), which is defined //! in [`AUTOLINK_DOMAIN_SIZE_MAX`][autolink_domain_size_max]. //! -//! The grammar for autolinks is quite strict and requires ASCII to be used -//! (without, for example, spaces). +//! The grammar for autolinks is quite strict and prohibits the use of ASCII control +//! characters or spaces. //! To use non-ascii characters and otherwise impossible characters, in URLs, //! you can use percent encoding: //! diff --git a/src/construct/definition.rs b/src/construct/definition.rs index b545643..57c62a5 100644 --- a/src/construct/definition.rs +++ b/src/construct/definition.rs @@ -30,7 +30,7 @@ //! space_or_tab ::= ' ' | '\t' //! ``` //! -//! Definitions in markdown to not, on their own, relate to anything in HTML. +//! Definitions in markdown do not, on their own, relate to anything in HTML. //! When connected with a link (reference), they together relate to the `` //! element in HTML. //! The definition forms its `href`, and optionally `title`, attributes. @@ -41,6 +41,12 @@ //! That means that [character escapes][character_escape] and //! [character references][character_reference] are allowed. //! +//! For info on how to encode characters in URLs, see +//! [`partial_destination`][destination]. +//! For info on how to characters are encoded as `href` on `` or `src` on +//! `` when compiling, see +//! [`sanitize_uri`][sanitize_uri]. +//! //! ## Tokens //! //! * [`Definition`][TokenType::Definition] @@ -68,6 +74,8 @@ //! [string]: crate::content::string //! [character_escape]: crate::construct::character_escape //! [character_reference]: crate::construct::character_reference +//! [destination]: crate::construct::partial_destination +//! [sanitize_uri]: crate::util::sanitize_uri //! [html]: https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-a-element //! //! diff --git a/src/construct/partial_destination.rs b/src/construct/partial_destination.rs index b2ceeb8..03dcbee 100644 --- a/src/construct/partial_destination.rs +++ b/src/construct/partial_destination.rs @@ -21,14 +21,45 @@ //! before it. //! Escaped parens do not count in balancing. //! -//! It is recommended to use the enclosed variant of destinations, as it allows -//! arbitrary parens, and also allows for whitespace and other characters in -//! URLs. -//! //! The destination is interpreted as the [string][] content type. //! That means that [character escapes][character_escape] and //! [character references][character_reference] are allowed. //! +//! The grammar for enclosed destinations (``) prohibits the use of `<`, +//! `>`, and line endings to form URLs. +//! The angle brackets can be encoded as a character reference, character +//! escape, or percent encoding: for `<` as `<`, `\<`, or `%3c` and for +//! `>` as `>`, `\>`, or `%3e`. +//! +//! The grammar for raw destinations (`x`) prohibits space (` `) and all +//! [ASCII control][char::is_ascii_control] characters, which thus must be +//! encoded. +//! Unbalanced arens can be encoded as a character reference, character escape, +//! or percent encoding: for `(` as `(`, `\(`, or `%28` and for `)` as +//! `)`, `\)`, or `%29`. +//! +//! It is recommended to use the enclosed variant of destinations, as it allows +//! the most characters, including arbitrary parens, in URLs. +//! +//! There are several cases where incorrect encoding of URLs would, in other +//! languages, result in a parse error. +//! In markdown, there are no errors, and URLs are normalized. +//! In addition, unicode characters are percent encoded +//! ([`sanitize_uri`][sanitize_uri]). +//! For example: +//! +//! ```markdown +//! [x] +//! +//! [x]: +//! ``` +//! +//! Yields: +//! +//! ```html +//!

x

+//! ``` +//! //! ## References //! //! * [`micromark-factory-destination/index.js` in `micromark`](https://github.com/micromark/micromark/blob/main/packages/micromark-factory-destination/dev/index.js) @@ -37,6 +68,7 @@ //! [string]: crate::content::string //! [character_escape]: crate::construct::character_escape //! [character_reference]: crate::construct::character_reference +//! [sanitize_uri]: crate::util::sanitize_uri //! //! -- cgit