diff --git a/readme.md b/readme.md index e7fceab..bad92da 100644 --- a/readme.md +++ b/readme.md @@ -7,8 +7,6 @@ Crate docs are currently at ### Docs -- [ ] (1) Go through all docs -- [ ] (1) Go through all bnf docs - [ ] (1) Add overview docs on how everything works - [ ] (1) Add more examples diff --git a/src/construct/autolink.rs b/src/construct/autolink.rs index 9890aaf..b25dc32 100644 --- a/src/construct/autolink.rs +++ b/src/construct/autolink.rs @@ -1,8 +1,8 @@ -//! Autolinks occur in the [text][] content type. +//! Autolink occurs in the [text][] content type. //! //! ## Grammar //! -//! Autolinks form with the following BNF +//! Autolink forms with the following BNF //! (see [construct][crate::construct] for character groups): //! //! ```bnf diff --git a/src/construct/label_end.rs b/src/construct/label_end.rs index 4752639..5e31444 100644 --- a/src/construct/label_end.rs +++ b/src/construct/label_end.rs @@ -1,11 +1,14 @@ -//! Label end is a construct that occurs in the [text][] content type. +//! Label end occurs in the [text][] content type. //! -//! It forms with the following BNF: +//! ## Grammar +//! +//! Label end forms with the following BNF +//! (see [construct][crate::construct] for character groups): //! //! ```bnf -//! label_end ::= ']' [ resource | reference_full | reference_collapsed ] +//! label_end ::= ']' [resource | reference_full | reference_collapsed] //! -//! resource ::= '(' [ whitespace ] destination [ whitespace title ] [ whitespace ] ')' +//! resource ::= '(' [space_or_tab_eol] destination [space_or_tab_eol title] [space_or_tab_eol] ')' //! reference_full ::= '[' label ']' //! reference_collapsed ::= '[' ']' //! @@ -14,15 +17,7 @@ //! ``` //! //! See [`destination`][destination], [`label`][label], and [`title`][title] -//! 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 `` 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 `` element. -//! See [*§ 4.8.3 The `img` element*][html-img] in the HTML spec for more info. +//! for grammar, notes, and recommendations on each part. //! //! In the case of a resource, the destination and title are given directly //! with the label end. @@ -49,7 +44,7 @@ //! //! 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. +//! `src` attribute in case of a [label start (image)][label_start_image]. //! The title is formed, optionally, on either `` or ``. //! //! For info on how to encode characters in URLs, see @@ -94,12 +89,29 @@ //!

a [b c d](#) e

//! ``` //! -//! This limiation is imposed because links in links is invalid according to +//! This limitation is imposed because links in links is invalid according to //! HTML. //! Technically though, in markdown it is still possible to construct them by //! using an [autolink][] in a link. //! You definitely should not do that. //! +//! ## HTML +//! +//! 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 `` 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 `` element. +//! See [*§ 4.8.3 The `img` element*][html_img] in the HTML spec for more info. +//! +//! ## Recommendation +//! +//! It is recommended to use labels instead of [autolinks][autolink]. +//! Labels allow more characters in URLs, and allow relative URLs and `www.` +//! URLs. +//! They also allow for descriptive text to explain the URL in prose. +//! //! ## Tokens //! //! * [`Data`][Name::Data] @@ -143,8 +155,8 @@ //! [autolink]: crate::construct::autolink //! [sanitize_uri]: crate::util::sanitize_uri::sanitize_uri //! [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 +//! [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::partial_space_or_tab_eol::space_or_tab_eol; diff --git a/src/construct/label_start_image.rs b/src/construct/label_start_image.rs index ffc1aee..8d35df2 100644 --- a/src/construct/label_start_image.rs +++ b/src/construct/label_start_image.rs @@ -1,16 +1,20 @@ -//! Label start (image) is a construct that occurs in the [text][] content -//! type. +//! Label start (image) occurs in the [text][] content type. //! -//! It forms with the following BNF: +//! ## Grammar +//! +//! Label start (image) forms with the following BNF +//! (see [construct][crate::construct] for character groups): //! //! ```bnf //! label_start_image ::= '!' '[' //! ``` //! +//! ## HTML +//! //! Label start (image) does not, on its own, relate to anything in HTML. //! When matched with a [label end][label_end], they together relate to the //! `` element in HTML. -//! See [*§ 4.8.3 The `img` element*][html-img] in the HTML spec for more info. +//! See [*§ 4.8.3 The `img` element*][html_img] in the HTML spec for more info. //! Without an end, the characters (`![`) are output. //! //! ## Tokens @@ -26,7 +30,7 @@ //! //! [text]: crate::construct::text //! [label_end]: crate::construct::label_end -//! [html-img]: https://html.spec.whatwg.org/multipage/embedded-content.html#the-img-element +//! [html_img]: https://html.spec.whatwg.org/multipage/embedded-content.html#the-img-element use crate::event::Name; use crate::resolve::Name as ResolveName; diff --git a/src/construct/label_start_link.rs b/src/construct/label_start_link.rs index dad6884..e079b2d 100644 --- a/src/construct/label_start_link.rs +++ b/src/construct/label_start_link.rs @@ -1,17 +1,21 @@ -//! Label start (link) is a construct that occurs in the [text][] content -//! type. +//! Label start (link) occurs in the [text][] content type. //! -//! It forms with the following BNF: +//! ## Grammar +//! +//! Label start (link) forms with the following BNF +//! (see [construct][crate::construct] for character groups): //! //! ```bnf //! label_start_link ::= '[' //! ``` //! +//! ## HTML +//! //! Label start (link) does not, on its own, relate to anything in HTML. //! When matched with a [label end][label_end], they together relate to the //! `` element in HTML. -//! See [*§ 4.5.1 The `a` element*][html-a] in the HTML spec for more info. -//! Without an end, the characters (`[`) are output. +//! See [*§ 4.5.1 The `a` element*][html_a] in the HTML spec for more info. +//! Without an end, the character (`[`) is output. //! //! ## Tokens //! @@ -25,7 +29,7 @@ //! //! [text]: crate::construct::text //! [label_end]: crate::construct::label_end -//! [html-a]: https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-a-element +//! [html_a]: https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-a-element use crate::event::Name; use crate::resolve::Name as ResolveName; diff --git a/src/construct/list_item.rs b/src/construct/list_item.rs index 09678dd..3e632fb 100644 --- a/src/construct/list_item.rs +++ b/src/construct/list_item.rs @@ -1,27 +1,41 @@ -//! List item is a construct that occurs in the [document][] content type. +//! List item occurs in the [document][] content type. //! -//! It forms with, roughly, the following BNF: +//! ## Grammar +//! +//! List item forms with the following BNF +//! (see [construct][crate::construct] for character groups): //! //! ```bnf -//! ; Restriction: there must be `eol | space_or_tab` after the start. +//! ; Restriction: if there is no space after the marker, the start must be followed by an `eol`. //! ; Restriction: if the first line after the marker is not blank and starts with `5( space_or_tab )`, //! ; only the first `space_or_tab` is part of the start. -//! list_item_start ::= '*' | '+' | '-' | 1*9( ascii_decimal ) ( '.' | ')' ) [ 1*4 space_or_tab ] +//! list_item_start ::= '*' | '+' | '-' | 1*9(ascii_decimal) ('.' | ')') [1*4 space_or_tab] +//! //! ; Restriction: blank line allowed, except when this is the first continuation after a blank start. //! ; Restriction: if not blank, the line must be indented, exactly `n` times. -//! list_item_cont ::= [ n( space_or_tab ) ] +//! list_item_cont ::= [n(space_or_tab)] //! ``` //! -//! Further lines that are not prefixed with `list_item_cont` cause the item -//! to be exited, except when those lines are lazy continuation. -//! Like so many things in markdown, list (items) too, are very complex. -//! See [*§ Phase 1: block structure*][commonmark-block] for more on parsing -//! details. +//! Further lines that are not prefixed with `list_item_cont` cause the list +//! item to be exited, except when those lines are lazy continuation. +//! Like so many things in markdown, list items too, are complex. +//! See [*§ Phase 1: block structure* in `CommonMark`][commonmark_block] for +//! more on parsing details. +//! +//! As list item is a container, it takes several bytes from the start of the +//! line, while the rest of the line includes more containers or flow. +//! +//! ## HTML +//! +//! List item relates to the `
  • `, `
      `, and `