forks/vimwiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rename component to element

Browse Source
This commit is contained in:
Chip Senkbeil
2020-10-04 10:36:52 -05:00
committed by Tinmarino
parent 1b2f34f5e0
commit 4f0df71d84
1 changed files with 40 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/specification.wiki
+40 -41
View File
@@ -30,9 +30,8 @@ mode) until the language has become relatively stable.
== Language == == Language ==
The following will describe the individual elements - hereby described as The following will describe the individual elements of the vimwiki language.
components - of the vimwiki language. It will cover each component's purpose It will cover each element's purpose and a clear description of the syntax.
and a clear description of the syntax.
For details on parsing prescedence, see the [[#Specification#Parser Details|companion section]]. For details on parsing prescedence, see the [[#Specification#Parser Details|companion section]].
@@ -40,7 +39,7 @@ For details on parsing prescedence, see the [[#Specification#Parser Details|comp
In order to define the vimwiki language, we first need to present several In order to define the vimwiki language, we first need to present several
definitions for primitive building blocks used to shape up higher-level definitions for primitive building blocks used to shape up higher-level
components. Relevant definitions are borrowed from elements. Relevant definitions are borrowed from
[[https://spec.commonmark.org/0.29/#characters-and-lines|commonmark characters and lines]]. [[https://spec.commonmark.org/0.29/#characters-and-lines|commonmark characters and lines]].
A *character* in vimwiki is a valid UTF-8 code point. A *character* in vimwiki is a valid UTF-8 code point.
@@ -58,10 +57,10 @@ A line with no characters, or a line containing only spaces (`U+0020`) or tabs
A *whitespace character* is a space (`U+0020`) or tab (`U+0009`). A *whitespace character* is a space (`U+0020`) or tab (`U+0009`).
=== Block Components === === Block Elements ===
The vimwiki language has a variety of syntax that represent components within The vimwiki language has a variety of syntax that represent elements within
a page. In this section, we discuss block-level components, which are vimwiki a page. In this section, we discuss block-level elements, which are vimwiki
syntax that are standalone and can comprise one or more entire lines within syntax that are standalone and can comprise one or more entire lines within
a file. a file.
@@ -133,16 +132,16 @@ zero or more [[#definition line|definition lines]]
A *term line* is represented by the following: A *term line* is represented by the following:
1. Starts at the beginning of a line 1. Starts at the beginning of a line
2. One or more [[#inline components|inline components]] before the sequence `::` 2. One or more [[#inline elements|inline elements]] before the sequence `::`
3. The sequence `::` 3. The sequence `::`
4. An optional one or more [[#inline components|inline components]] before [[#line ending|line ending]] 4. An optional one or more [[#inline elements|inline elements]] before [[#line ending|line ending]]
to be the first definition to be the first definition
5. A [[#line ending|line ending]] or end of input 5. A [[#line ending|line ending]] or end of input
A *definition line* is represented by the following: A *definition line* is represented by the following:
1. Starts at the beginning of a line 1. Starts at the beginning of a line
2. The sequence `::` 2. The sequence `::`
3. One or more [[#inline components|inline components]] before [[#line ending|line ending]] 3. One or more [[#inline elements|inline elements]] before [[#line ending|line ending]]
4. A [[#line ending|line ending]] or end of input 4. A [[#line ending|line ending]] or end of input
*Extra Notes*: Each term and definition is trimmed to remove all leading and *Extra Notes*: Each term and definition is trimmed to remove all leading and
@@ -182,7 +181,7 @@ A *header* is represented by the following:
2. Zero or more [[#whitespace character|whitespace characters]] (implying 2. Zero or more [[#whitespace character|whitespace characters]] (implying
whether or not a header is centered) whether or not a header is centered)
3. One or more equal sign (`U+003D`) characters 3. One or more equal sign (`U+003D`) characters
4. One or more [[#inline components|inline components]] 4. One or more [[#inline elements|inline elements]]
5. An equivalent number of equal sign characters as in step #3 5. An equivalent number of equal sign characters as in step #3
6. A [[#line ending|line ending]] or end of input 6. A [[#line ending|line ending]] or end of input
@@ -193,7 +192,7 @@ For example, `= header =` is equal to `=header=`.
==== List ==== ==== List ====
A list is composed of a series list items, each being comprised A list is composed of a series list items, each being comprised
of [[#inline components|inline components]] and [[#list|sub lists]]. It mirrors the of [[#inline elements|inline elements]] and [[#list|sub lists]]. It mirrors the
functionality available in an [[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ul|HTML Unordered List]] functionality available in an [[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ul|HTML Unordered List]]
and [[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ol|HTML Ordered List]]. and [[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ol|HTML Ordered List]].
@@ -238,7 +237,7 @@ A *starting list item line* is represented by the following:
for an ordered list for an ordered list
4. A [[#whitespace character|whitespace character]] 4. A [[#whitespace character|whitespace character]]
5. An optional [[#todo attribute|todo attribute]] and additional [[#whitespace character|whitespace character]] 5. An optional [[#todo attribute|todo attribute]] and additional [[#whitespace character|whitespace character]]
6. Zero or more [[#inline components|inline components]] 6. Zero or more [[#inline elements|inline elements]]
7. A [[#line ending|line ending]] or end of input 7. A [[#line ending|line ending]] or end of input
A *companion list item line* is represented by the following: A *companion list item line* is represented by the following:
@@ -248,7 +247,7 @@ A *companion list item line* is represented by the following:
3. One of the following: 3. One of the following:
* The start of a new [[#list|list]] (to be treated as a sublist of the * The start of a new [[#list|list]] (to be treated as a sublist of the
current list item) current list item)
* A series of one or more [[#inline components|inline components]] * A series of one or more [[#inline elements|inline elements]]
(to be added to the content of the current list item) followed by (to be added to the content of the current list item) followed by
a [[#line ending|line ending]] or end of input a [[#line ending|line ending]] or end of input
* A [[#blank line|blank line]] if there is guaranteed to still be some * A [[#blank line|blank line]] if there is guaranteed to still be some
@@ -343,7 +342,7 @@ A *paragraph line* is represented by the following:
* [[#blockquote|blockquote]] * [[#blockquote|blockquote]]
* [[#divider|divider]] * [[#divider|divider]]
* [[#placeholder|placeholder]] * [[#placeholder|placeholder]]
4. One or more [[#inline components|inline components]] 4. One or more [[#inline elements|inline elements]]
5. A [[#line ending|line ending]] or end of input 5. A [[#line ending|line ending]] or end of input
TODO ... should we combine [[#non-blank line|non-blank line]] with paragraph TODO ... should we combine [[#non-blank line|non-blank line]] with paragraph
@@ -473,7 +472,7 @@ An *ending preformatted text line* is represented by the following:
==== Table ==== ==== Table ====
A table is composed of a series of rows containing various other components. It A table is composed of a series of rows containing various other elements. It
mirrors [[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table|HTML Table]]. mirrors [[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table|HTML Table]].
{{{vimwiki {{{vimwiki
@@ -526,7 +525,7 @@ A *span left cell* is represented by the following:
A *content cell* is represented by the following: A *content cell* is represented by the following:
1. Zero or more [[#whitespace character|whitespace characters]] 1. Zero or more [[#whitespace character|whitespace characters]]
2. One or more [[#inline components|inline components]] not comprised of `|` 2. One or more [[#inline elements|inline elements]] not comprised of `|`
3. Zero or more [[#whitespace character|whitespace characters]] 3. Zero or more [[#whitespace character|whitespace characters]]
A *cell boundary* is represented by the pipe character (`U+007C` aka `|`). A *cell boundary* is represented by the pipe character (`U+007C` aka `|`).
@@ -534,7 +533,7 @@ A *cell boundary* is represented by the pipe character (`U+007C` aka `|`).
==== Non-blank Line ==== ==== Non-blank Line ====
A non-blank line is a single line that is not a paragraph. It is used to A non-blank line is a single line that is not a paragraph. It is used to
capture text not represented by any other component. capture text not represented by any other element.
{{{vimwiki {{{vimwiki
Some other text containing *bold* and [[links]]. Some other text containing *bold* and [[links]].
@@ -544,22 +543,22 @@ capture text not represented by any other component.
A *non-blank line* is represented by the following: A *non-blank line* is represented by the following:
1. Between one and three [[#whitespace character|whitespace characters]] 1. Between one and three [[#whitespace character|whitespace characters]]
2. One or more [[#inline components|inline components]] 2. One or more [[#inline elements|inline elements]]
3. A [[#line ending|line ending]] or end of input 3. A [[#line ending|line ending]] or end of input
TODO ... should we combine [[#non-blank line|non-blank line]] with paragraph TODO ... should we combine [[#non-blank line|non-blank line]] with paragraph
by having a paragraph trim all leading [[#whitespace character|whitespace]]? by having a paragraph trim all leading [[#whitespace character|whitespace]]?
=== Inline Components === === Inline Elements ===
The vimwiki language also has a variety of syntax that can be used within a The vimwiki language also has a variety of syntax that can be used within a
line on a page. These are referred to as *inline components* and can be found line on a page. These are referred to as *inline elements* and can be found
within a variety of [[#block components|block components]] as well as nested within a variety of [[#block elements|block elements]] as well as nested
within other inline components. within other inline elements.
==== Math Inline ==== ==== Math Inline ====
A math inline component is composed of a single-line formula. A math inline element is composed of a single-line formula.
Like its big brother, the [[#math block|math block]], it is rendered in HTML Like its big brother, the [[#math block|math block]], it is rendered in HTML
using the [[https://www.mathjax.org/|MathJax engine]]. using the [[https://www.mathjax.org/|MathJax engine]].
@@ -568,23 +567,23 @@ $ \sum_i a_i^2 = 1 $
}}} }}}
TODO ... is there a way to escape the `$` used to mark the beginning and end TODO ... is there a way to escape the `$` used to mark the beginning and end
of an inline math component? Is `$` even a concern within an of an inline math element? Is `$` even a concern within an
inline formula? If it is, maybe an escape sequence of `\$` would inline formula? If it is, maybe an escape sequence of `\$` would
be applicable. be applicable.
===== Syntax ===== ===== Syntax =====
An *inline math* component is represented by the following: An *inline math* element is represented by the following:
1. A dollar sign (`U+0024` aka `$`) 1. A dollar sign (`U+0024` aka `$`)
2. One or more characters that are not a dollar sign or [[#line ending|line ending]] 2. One or more characters that are not a dollar sign or [[#line ending|line ending]]
3. A dollar sign (`U+0024` aka `$`) 3. A dollar sign (`U+0024` aka `$`)
*Extra Notes*: The formula within the inline component is trimmed to remove all *Extra Notes*: The formula within the inline element is trimmed to remove all
leading and trailing [[#whitespace character|whitespace characters]]. leading and trailing [[#whitespace character|whitespace characters]].
==== Tags ==== ==== Tags ====
A tags component is composed of a series of individual tag elements. It is used A tags element is composed of a series of individual tag elements. It is used
both to mark various places within a page as well as act as an [[#anchor|anchor]]. both to mark various places within a page as well as act as an [[#anchor|anchor]].
{{{vimwiki {{{vimwiki
@@ -593,7 +592,7 @@ both to mark various places within a page as well as act as an [[#anchor|anchor]
===== Syntax ===== ===== Syntax =====
A *tags* component is represented by the following: A *tags* element is represented by the following:
1. A [[#tag separator|tag separator]] 1. A [[#tag separator|tag separator]]
2. A sequence of [[#tag|tag]] separated by [[#tag separator|tag separator]] 2. A sequence of [[#tag|tag]] separated by [[#tag separator|tag separator]]
3. A [[#tag separator|tag separator]] 3. A [[#tag separator|tag separator]]
@@ -607,7 +606,7 @@ TODO ... should tags with whitespace be allowed?
==== Link ==== ==== Link ====
A link is a crucial inline component of vimwiki and is able to connect pages A link is a crucial inline element of vimwiki and is able to connect pages
with each other as well as external wikis and resources. with each other as well as external wikis and resources.
{{{vimwiki {{{vimwiki
@@ -699,9 +698,9 @@ A *link description* is represented by one of the following:
* One or more characters that are not a [[#link end seq|link end seq]] or [[#line ending|line ending]] * One or more characters that are not a [[#link end seq|link end seq]] or [[#line ending|line ending]]
A *link anchor* is represented by a series of pairs, each comprised of A *link anchor* is represented by a series of pairs, each comprised of
a [[#link anchor prefix|link anchor prefix]] and a [[#link anchor component|link anchor component]] a [[#link anchor prefix|link anchor prefix]] and a [[#link anchor element|link anchor element]]
A *link anchor component* is represented by one or more characters that are A *link anchor element* is represented by one or more characters that are
not a [[#link anchor prefix|link anchor prefix]], [[#link inner separator|link inner separator]], not a [[#link anchor prefix|link anchor prefix]], [[#link inner separator|link inner separator]],
[[#link end seq|link end seq]], or [[#line ending|line ending]] [[#link end seq|link end seq]], or [[#line ending|line ending]]
@@ -829,7 +828,7 @@ A *keyword* is represented as one of the following:
==== Text ==== ==== Text ====
Text is a plain series of characters that have no special stylings applied Text is a plain series of characters that have no special stylings applied
directly, but can be included in other [[#inline components|inline components]]. directly, but can be included in other [[#inline elements|inline elements]].
===== Syntax ===== ===== Syntax =====
@@ -844,8 +843,8 @@ is encountered:
=== Comments === === Comments ===
Separately from [[#block components|block components]] and [[#inline components|inline components]], Separately from [[#block elements|block elements]] and [[#inline elements|inline elements]],
comments are another component available within vimwiki. There are two comments are another element available within vimwiki. There are two
classifications: classifications:
1. Line comment in the form of `%%CONTENT` 1. Line comment in the form of `%%CONTENT`
@@ -901,8 +900,8 @@ first linesecond line
== Parser Details == == Parser Details ==
When building a parser for the vimwiki language, certain components may overlap When building a parser for the vimwiki language, certain elements may overlap
in the text that they can match. This means that the order in which components in the text that they can match. This means that the order in which elements
are evaluated can affect how a page is perceived. are evaluated can affect how a page is perceived.
Additionally, the inclusion of [[#comments|comments]] further complicates the Additionally, the inclusion of [[#comments|comments]] further complicates the
@@ -912,14 +911,14 @@ multi-line comments can remove [[#line ending|line ending]] characters.
To that end, a two-pass parser is required to support properly extracting To that end, a two-pass parser is required to support properly extracting
comments prior to parsing the full vimwiki syntax: comments prior to parsing the full vimwiki syntax:
1. Parse all comments and remove from input 1. Parse all comments and remove from input
2. Parse a page that is full of [[#block components|block components]] 2. Parse a page that is full of [[#block elements|block elements]]
{{{ {{{
Comment = Comment =
| Multi Line Comment | Multi Line Comment
| Line Comment | Line Comment
Page = (Block Component)+ Page = (Block Element)+
Block Component = Block Element =
| Header | Header
| Definition List | Definition List
| List | List
@@ -931,7 +930,7 @@ Block Component =
| Placeholder | Placeholder
| Paragraph | Paragraph
| Non-blank Line | Non-blank Line
Inline Component = Inline Element =
| Math Inline | Math Inline
| Tags | Tags
| Link | Link