diff options
Diffstat (limited to 'src/construct/label_end.rs')
| -rw-r--r-- | src/construct/label_end.rs | 153 |
1 files changed, 150 insertions, 3 deletions
diff --git a/src/construct/label_end.rs b/src/construct/label_end.rs index a814302..05c7635 100644 --- a/src/construct/label_end.rs +++ b/src/construct/label_end.rs @@ -1,4 +1,148 @@ -//! To do +//! Label end is a construct that occurs in the [text][] content type. +//! +//! It forms with the following BNF: +//! +//! ```bnf +//! label_end ::= ']' [ resource | reference_full | reference_collapsed ] +//! +//! resource ::= '(' [ whitespace ] destination [ whitespace title ] [ whitespace ] ')' +//! reference_full ::= '[' label ']' +//! reference_collapsed ::= '[' ']' +//! +//! ; See the `destination`, `title`, and `label` constructs for the BNF of +//! ; those parts. +//! ``` +//! +//! See [`destination`][destination], [`title`][title], and [`label`][label] +//! for grammar, notes, and recommendations. +//! +//! Label end does not, on its own, relate to anything in HTML. +//! When matched with a [label start (link)][label_start_link], they together +//! relate to the `<a>` element in HTML. +//! See [*§ 4.5.1 The `a` element*][html-a] in the HTML spec for more info. +//! It can also match with [label start (image)][label_start_image], in which +//! case they form an `<img>` element. +//! See [*§ 4.8.3 The `img` element*][html-img] in the HTML spec for more info. +//! +//! In the case of a resource, the destination and title are given directly +//! with the label end. +//! In the case of a reference, this information is provided by a matched +//! [definition][]. +//! Full references (`[x][y]`) match to definitions through their explicit, +//! second, label (`y`). +//! Collapsed labels (`[x][]`) and shortcut labels (`[x]`) match by +//! interpreting the text provided between the first, implicit, label (`x`). +//! To match, the effective label of the reference must be equal to the label +//! of the definition after normalizing with +//! [`normalize_identifier`][normalize_identifier]. +//! +//! Importantly, while the label of a full reference *can* include [string][] +//! content, and in case of collapsed and shortcut references even [text][] +//! content, that content is not considered when matching. +//! To illustrate, neither label matches the definition: +//! +//! ```markdown +//! [a&b]: https://example.com +//! +//! [x][a&b], [a\&b][] +//! ``` +//! +//! When the resource or reference matches, the destination forms the `href` +//! attribute in case of a [label start (link)][label_start_link], and an +//! `src` attribute otherwise. +//! The title is, optionally, formed, on either `<a>` or `<img>`. +//! +//! For info on how to encode characters in URLs, see +//! [`destination`][destination]. +//! For info on how to characters are encoded as `href` on `<a>` or `src` on +//! `<img>` when compiling, see +//! [`sanitize_uri`][sanitize_uri]. +//! +//! In case of a matched [label start (link)][label_start_link], the interpreted +//! content between it and the label end, is placed between the opening and +//! closing tags. +//! Otherwise, the text is also interpreted, but used *without* the resulting +//! tags: +//! +//! ```markdown +//! [a *b* c](#) +//! +//!  +//! ``` +//! +//! Yields: +//! +//! ```html +//! <p><a href="#">a <em>b</em> c</a></p> +//! <p><img src="#" alt="a b c" /></p> +//! ``` +//! +//! It is possible to use images in links. +//! It’s, somewhat, possible to have links in images (the text will be used, +//! not the HTML, see above). +//! But it’s not possible to use links in links, and the “deepest” link wins. +//! To illustrate: +//! +//! ```markdown +//! a [b [c](#) d](#) e +//! ``` +//! +//! Yields: +//! +//! ```html +//! <p>a [b <a href="#">c</a> d](#) e</p> +//! ``` +//! +//! This limiation is imposed because links in links is invalid according to +//! HTML. +//! Technically though, it is possible by using an [autolink][] in a link, +//! but you definitely should not do that. +//! +//! ## Tokens +//! +//! * [`Link`][TokenType::Link] +//! * [`Image`][TokenType::Image] +//! * [`Label`][TokenType::Label] +//! * [`LabelText`][TokenType::LabelText] +//! * [`LabelEnd`][TokenType::LabelEnd] +//! * [`LabelMarker`][TokenType::LabelMarker] +//! * [`Resource`][TokenType::Resource] +//! * [`ResourceMarker`][TokenType::ResourceMarker] +//! * [`ResourceDestination`][TokenType::ResourceDestination] +//! * [`ResourceDestinationLiteral`][TokenType::ResourceDestinationLiteral] +//! * [`ResourceDestinationLiteralMarker`][TokenType::ResourceDestinationLiteralMarker] +//! * [`ResourceDestinationRaw`][TokenType::ResourceDestinationRaw] +//! * [`ResourceDestinationString`][TokenType::ResourceDestinationString] +//! * [`ResourceTitle`][TokenType::ResourceTitle] +//! * [`ResourceTitleMarker`][TokenType::ResourceTitleMarker] +//! * [`ResourceTitleString`][TokenType::ResourceTitleString] +//! * [`Reference`][TokenType::Reference] +//! * [`ReferenceMarker`][TokenType::ReferenceMarker] +//! * [`ReferenceString`][TokenType::ReferenceString] +//! * [`Data`][TokenType::Data] +//! * [`SpaceOrTab`][TokenType::SpaceOrTab] +//! * [`LineEnding`][TokenType::LineEnding] +//! +//! ## References +//! +//! * [`label-end.js` in `micromark`](https://github.com/micromark/micromark/blob/main/packages/micromark-core-commonmark/dev/lib/label-end.js) +//! * [*§ 4.7 Link reference definitions* in `CommonMark`](https://spec.commonmark.org/0.30/#link-reference-definitions) +//! * [*§ 6.3 Links* in `CommonMark`](https://spec.commonmark.org/0.30/#links) +//! * [*§ 6.4 Images* in `CommonMark`](https://spec.commonmark.org/0.30/#images) +//! +//! [string]: crate::content::string +//! [text]: crate::content::text +//! [destination]: crate::construct::partial_destination +//! [title]: crate::construct::partial_title +//! [label]: crate::construct::partial_label +//! [label_start_image]: crate::construct::label_start_image +//! [label_start_link]: crate::construct::label_start_link +//! [definition]: crate::construct::definition +//! [autolink]: crate::construct::autolink +//! [sanitize_uri]: crate::util::sanitize_uri::sanitize_uri +//! [normalize_identifier]: crate::util::normalize_identifier +//! [html-a]: https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-a-element +//! [html-img]: https://html.spec.whatwg.org/multipage/embedded-content.html#the-img-element use crate::constant::RESOURCE_DESTINATION_BALANCE_MAX; use crate::construct::{ @@ -16,14 +160,17 @@ use crate::util::{ span::{serialize, Span}, }; +/// State needed to parse label end. #[derive(Debug)] struct Info { - /// To do. + /// Index into `label_start_stack` of the corresponding opening. label_start_index: usize, - /// To do. + /// The proposed `Media` that this seems to represent. media: Media, } +/// Resolve media: turn correct label start (image, link) and label end +/// into links and images, or turn them back into data. #[allow(clippy::too_many_lines)] pub fn resolve_media(tokenizer: &mut Tokenizer) -> Vec<Event> { let mut left: Vec<LabelStart> = tokenizer.label_start_list_loose.drain(..).collect(); |