| Author | DaveJarvis <email> |
|---|---|
| Date | 2025-09-01 22:02:42 GMT-0700 |
| Commit | b693cfc8307e00442b08bc4c9e66b99c95ff1e30 |
| Parent | 7ce5bd7 |
| Delta | 57 lines added, 20 lines removed, 37-line increase |
| -# Variable definitions | ||
| +# Variables | ||
| -Variable definitions provide a way to insert key names having associated values into a document. The variable names and values are declared inside an external file using the YAML file format. Simply put, variables are written in the file as follows: | ||
| +Variables are placeholders for values that can be defined once and reused | ||
| +throughout the document. When the document is built, each variable is replaced | ||
| +with its corresponding value. | ||
| -``` | ||
| +Variables are declared in an external file as follows: | ||
| + | ||
| +``` yaml | ||
| key: value | ||
| ``` | ||
| Any number of variables can be defined, in any order: | ||
| -``` | ||
| +``` yaml | ||
| key_1: Value 1 | ||
| key_2: Value 2 | ||
| ``` | ||
| -Variables can reference other variables by bookending the key name within symbols, provided the reference is enclosed in quotation marks: | ||
| +A variable's value can reference other variables by enclosing the referenced key in double curly braces (`{{ }}`), wrapped in quotation marks: | ||
| -``` | ||
| +``` yaml | ||
| key: Value | ||
| key_1: "{{key}} 1" | ||
| key_2: "{{key}} 2" | ||
| ``` | ||
| -Variables can use a nested structure to help group related information: | ||
| +Variables can be nested to group related information: | ||
| -``` | ||
| -novel: | ||
| +``` yaml | ||
| +document: | ||
| title: Book Title | ||
| author: Author Name | ||
| isbn: 978-3-16-148410-0 | ||
| ``` | ||
| -Use a period to reference nested keys, such as: | ||
| +Reference nested keys using a period, such as: | ||
| -``` | ||
| +``` yaml | ||
| novel: | ||
| author: Author Name | ||
| copyright: | ||
| owner: "{{novel.author}}" | ||
| ``` | ||
| -Save the variable definitions in a file having an extension of `.yaml` or `.yml`. | ||
| +This file format for defining key-value pairs is known as YAML. Save the | ||
| +variable definitions in a file having an extension of `.yaml` or `.yml`. | ||
| ## Document editing |
| ``` | ||
| -That command will convert `01.md` into the respective file formats. In the first case, it will become an HTML page. In the second case, it will become a Markdown document with all variables interpolated and replaced. | ||
| +That command will convert `01.md` into the respective file formats. In the | ||
| +first case, it will become an XHTML page. In the second case, it will become a | ||
| +Markdown document with all variables interpolated and replaced. | ||
| A more complex example follows: |
| # Fenced divs | ||
| -This chapter provides a comprehensive overview of the fenced div syntax used to generate XHTML `div` elements within Markdown documents. It covers the basic, extended, and nested syntax forms, illustrating how to structure fenced divs and how they translate into XHTML. | ||
| +This chapter provides a comprehensive overview of the fenced div syntax used to | ||
| +generate XHTML `div` elements within Markdown documents. It covers the basic, | ||
| +extended, and nested syntax forms, illustrating how to structure fenced divs | ||
| +and how they translate into XHTML. | ||
| ## Basic syntax |
| ## History | ||
| -The origins of quotation marks can be traced back to Ancient Greek. By around 625 BCE, they were adopted as the diplé (⸖). This early form foreshadowed the curved shape of modern quotation marks. | ||
| +The origins of quotation marks can be traced back to scholarly annotation | ||
| +practices in Ancient Greece. Rather than punctuation embedded in the text, | ||
| +Greek scribes used marginal symbols to highlight notable or quoted passages. | ||
| +Chief among these was the diplé (`⟩`), a wedge-shaped mark placed beside lines | ||
| +to signal commentary or quotation. A variant, the diplé periestigmene (`⸖`)---a | ||
| +diplé accompanied by dots---was used by scholars to indicate disagreement with | ||
| +earlier interpretations. These marks were not quotation marks in the modern | ||
| +sense, but they laid the groundwork for distinguishing quoted or significant | ||
| +text. | ||
| -By the seventeenth century, quotation marks became common in writing. During the nineteenth century, Western Europe adopted the convention of turning the convexity of quotation mark pairs outward. | ||
| +By the seventeenth century, quotation marks began appearing regularly in | ||
| +printed texts. During the nineteenth century, Western European typographers | ||
| +adopted the convention of turning the convexity of quotation mark pairs | ||
| +outward, giving rise to the familiar “double curved” style (« » or “ ”), | ||
| +depending on language and region. | ||
| -Early mechanical typewriters, dating from around 1825, lacked many punctuation marks. As technology improved, additional keys were added, though some keys had dual roles (sometimes capital `I` was used for the number `1`). Straight single and double quotes were used to represent quotation marks, apostrophes, feet and inches marks, as well as primes and double-primes. There was no pressing need to type curled versions because readers relied on contextual understanding. | ||
| +Early mechanical typewriters, dating from around 1825, lacked many punctuation | ||
| +marks. As technology improved, additional keys were added, though some had dual | ||
| +roles (for example, capital `I` often substituted for the number `1`). Straight | ||
| +single and double quotes were used to represent quotation marks, apostrophes, | ||
| +feet and inches, as well as primes and double-primes. Readers had enough | ||
| +context to interpret meaning. | ||
| -Eventually, straight quotes were codified for computers. Unfortunately, this legacy from typewriters created challenges for encoding. Apostrophes inherited the straight quote form, and early encoding standards failed to capture the nuanced meanings in English typography. Computers forced users to treat the apostrophe as a straight quote. | ||
| +Eventually, straight quotes were codified in computer character sets. | ||
| +Apostrophes inherited the straight quote form, and early encoding standards | ||
| +failed to distinguish between typographic and semantic roles. | ||
| -Standards bodies recommended using the right single quotation mark for an apostrophe instead, which disregarded its semantic meaning. As a result, text containing English quotations---especially in British English---is now riddled with ambiguity. | ||
| +Standards bodies later recommended using the right single quotation mark (’) | ||
| +for apostrophes, which does not capture any semantic nuance. Consequently, | ||
| +English text---especially in British usage, which favors single quotes for | ||
| +dialogue---is now riddled with typographic ambiguity. | ||
| Consider the sentence: |
| ## Extension System Architecture | ||
| -An extension is an addition to the Markdown parser, flexmark-java, that is used when converting the document's abstract syntax tree into an HTML document. The `{{app.classes.processors.markdown}}` contains both prepackaged and custom extensions. This extensible architecture allows for specialized processing of various Markdown elements, enabling support for advanced features like mathematical expressions, enhanced image handling, and custom block types. | ||
| +An extension is an addition to the Markdown parser, flexmark-java, that is used | ||
| +when converting the document's abstract syntax tree into an XHTML document. The | ||
| +`{{app.classes.processors.markdown}}` contains both prepackaged and custom | ||
| +extensions. This extensible architecture allows for specialized processing of | ||
| +various Markdown elements, enabling support for advanced features like | ||
| +mathematical expressions, enhanced image handling, and custom block types. | ||