From 90889ac38dee7b3ad3c9b6c8b3e5aeb66e8b5846 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Thu, 30 Jun 2022 11:46:43 +0200 Subject: Refactor some docs, fix some grammar --- src/compiler.rs | 2 -- src/construct/definition.rs | 8 ++++---- src/construct/hard_break_escape.rs | 3 ++- src/construct/heading_setext.rs | 6 ++++-- src/construct/label_end.rs | 26 +++++++++++++++----------- src/content/text.rs | 5 +++-- 6 files changed, 28 insertions(+), 22 deletions(-) (limited to 'src') diff --git a/src/compiler.rs b/src/compiler.rs index b29a27c..7a11870 100644 --- a/src/compiler.rs +++ b/src/compiler.rs @@ -248,8 +248,6 @@ struct CompileContext<'a> { pub protocol_src: Option>, pub line_ending_default: LineEnding, pub allow_dangerous_html: bool, - /// Data inferred about the document. - // To do: definitions. /// Intermediate results. pub buffers: Vec>, pub index: usize, diff --git a/src/construct/definition.rs b/src/construct/definition.rs index aca22a6..af94d12 100644 --- a/src/construct/definition.rs +++ b/src/construct/definition.rs @@ -3,7 +3,7 @@ //! They’re formed with the following BNF: //! //! ```bnf -//! definition ::= label ':' whitespace destination [ whitespace title ] [ space_or_tab ] +//! definition ::= label ':' [ whitespace ] destination [ whitespace title ] [ space_or_tab ] //! //! ; See the `destination`, `title`, and `label` constructs for the BNF of //! ; those parts. @@ -20,7 +20,7 @@ //! See [*§ 4.5.1 The `a` element*][html-a] and //! [*§ 4.8.3 The `img` element*][html-img] in the HTML spec for more info. //! -//! The `label`, `destination`, and `title` parts are interpreted as the +//! The `destination`, `label`, and `title` parts are interpreted as the //! [string][] content type. //! That means that [character escapes][character_escape] and //! [character references][character_reference] are allowed. @@ -28,7 +28,7 @@ //! Definitions match to references through their label. //! To match, both labels must be equal after normalizing with //! [`normalize_identifier`][normalize_identifier]. -//! One definitions can match to multiple references. +//! One definition can match to multiple references. //! Multiple definitions with the same, normalized, identifier are ignored: the //! first definition is preferred. //! To illustrate, the definition with a destination of `x` wins: @@ -53,7 +53,7 @@ //! //! For info on how to encode characters in URLs, see //! [`destination`][destination]. -//! For info on how to characters are encoded as `href` on `` or `src` on +//! For info on how characters are encoded as `href` on `` or `src` on //! `` when compiling, see //! [`sanitize_uri`][sanitize_uri]. //! diff --git a/src/construct/hard_break_escape.rs b/src/construct/hard_break_escape.rs index 4458ccb..1e755a3 100644 --- a/src/construct/hard_break_escape.rs +++ b/src/construct/hard_break_escape.rs @@ -15,7 +15,8 @@ //! It is also possible to create a hard break with a //! [hard break (trailing)][hard_break_trailing]. //! That construct is not recommended because trailing spaces are typically -//! invisible in editors, or even automatically removed, making them to use. +//! invisible in editors, or even automatically removed, making them hard to +//! use. //! //! It is also possible to escape punctuation characters with a similar //! construct: a [character escape][character_escape] is a backslash followed diff --git a/src/construct/heading_setext.rs b/src/construct/heading_setext.rs index 63f3c30..03a2e55 100644 --- a/src/construct/heading_setext.rs +++ b/src/construct/heading_setext.rs @@ -25,8 +25,10 @@ //! headings. //! Due to this limitation, it is recommended to use atx headings. //! -//! [Thematic breaks][thematic_break] formed with dashes (without whitespace) -//! can also form heading (setext). +//! [Thematic breaks][thematic_break] formed with dashes and without whitespace +//! could be interpreted as a heading (setext). +//! Which one forms depends on whether there is text directly in fron of the +//! sequence. //! //! > 🏛 **Background**: the word *setext* originates from a small markup //! > language by Ian Feldman from 1991. diff --git a/src/construct/label_end.rs b/src/construct/label_end.rs index f43a740..888355b 100644 --- a/src/construct/label_end.rs +++ b/src/construct/label_end.rs @@ -30,7 +30,7 @@ //! [definition][]. //! Full references (`[x][y]`) match to definitions through their explicit, //! second, label (`y`). -//! Collapsed labels (`[x][]`) and shortcut labels (`[x]`) match by +//! Collapsed references (`[x][]`) and shortcut references (`[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 @@ -50,11 +50,11 @@ //! 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 `` or ``. +//! The title is formed, optionally, on either `` or ``. //! //! For info on how to encode characters in URLs, see //! [`destination`][destination]. -//! For info on how to characters are encoded as `href` on `` or `src` on +//! For info on how characters are encoded as `href` on `` or `src` on //! `` when compiling, see //! [`sanitize_uri`][sanitize_uri]. //! @@ -78,9 +78,10 @@ //! ``` //! //! 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. +//! 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. +//! The “deepest” link wins. //! To illustrate: //! //! ```markdown @@ -95,8 +96,9 @@ //! //! This limiation is imposed because links in links is invalid according to //! HTML. -//! Technically though, it is still possible to construct them by using an -//! [autolink][] in a link, but you definitely should not do that. +//! Technically though, in markdown it is still possible to construct them by +//! using an [autolink][] in a link. +//! You definitely should not do that. //! //! ## Tokens //! @@ -140,7 +142,7 @@ //! [definition]: crate::construct::definition //! [autolink]: crate::construct::autolink //! [sanitize_uri]: crate::util::sanitize_uri::sanitize_uri -//! [normalize_identifier]: crate::util::normalize_identifier +//! [normalize_identifier]: crate::util::normalize_identifier::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 @@ -169,8 +171,10 @@ struct Info { media: Media, } -/// Resolve media: turn correct label start (image, link) and label end -/// into links and images, or turn them back into data. +/// Resolve media. +/// +/// This turns correct label start (image, link) and label end into links and +/// images, or turns them back into data. #[allow(clippy::too_many_lines)] pub fn resolve_media(tokenizer: &mut Tokenizer) -> Vec { let mut left: Vec = tokenizer.label_start_list_loose.drain(..).collect(); diff --git a/src/content/text.rs b/src/content/text.rs index 5718617..183072e 100644 --- a/src/content/text.rs +++ b/src/content/text.rs @@ -11,8 +11,9 @@ //! * [Hard break (escape)][crate::construct::hard_break_escape] //! * [Hard break (trailing)][crate::construct::hard_break_trailing] //! * [Code (text)][crate::construct::code_text] -//! * Label start (image) -//! * Label start (link) +//! * [Label start (image)][crate::construct::label_start_image] +//! * [Label start (link)][crate::construct::label_start_link] +//! * [Label end][crate::construct::label_end] //! * [Character escape][crate::construct::character_escape] //! * [Character reference][crate::construct::character_reference] -- cgit