diff --git a/content/docs/concept/the-logic-of-cue/en.md b/content/docs/concept/the-logic-of-cue/en.md index e797d58da..8bc59d413 100644 --- a/content/docs/concept/the-logic-of-cue/en.md +++ b/content/docs/concept/the-logic-of-cue/en.md @@ -536,10 +536,12 @@ even across files. Once set, there is no need to look at the individual values and files to know these constraints apply. Such information is not readily available for -fully expanded configurations.[$^1$](#footnotes) +fully expanded configurations.[^a] But also with inheritance-based solutions that allow arbitrary overrides, templates give little information. +[^a]: Although CUE could be used to verify those properties in such data-only configurations. + The ability to enforce constraints top down is crucial for any large-scale configuration setup. GCL and Jsonnet address this with assertions. @@ -692,7 +694,12 @@ In CUE, though, we typically refer to `acmeMonitoring` as a constraint. After all, applying it will guarantee that a job implements monitoring in a certain way. If such a constraint also contains sensible defaults, however, -it simultaneously validates _and_ reduces boilerplate.[$^2$](#footnotes) +it simultaneously validates _and_ reduces boilerplate.[^b] + +[^b]: TFSs typically don't have default values, it is the structure itself that +is boilerplate removing, as the structure itself is what is the useful value. +But that is a different topic. It doesn't work quite as well if one needs +numeric values. This is why CUE adds defaults. This ability to simultaneously enforce constraints and remove boilerplate @@ -755,8 +762,10 @@ just plain ol' logic. Most cycles that do not result in infinite structures can be handled by CUE. In fact, it could handle most infinite structures in bounded time as well, but it puts limits on such cycles for -practical reasons.[$^3$](#footnotes) +practical reasons.[^c] +[^c]: Detection of structural cycles (an occurs check) is not yet implemented, +and thus printing infinite structures will still result in a loop. ### File organization @@ -796,21 +805,3 @@ One can read more about this in Ann Copestake's (2002, CSLI Publications, ISBN 1-57586-261-1). ## Footnotes - - -
    -
  1. Although CUE could be used to verify those properties in such - data-only configurations. - -
  2. TFSs typically don't have default values, it is the structure - itself that is boilerplate removing, as the structure itself - is what is the useful value. - But that is a different topic. - It doesn't work quite as well if one needs numeric values. - This is why CUE adds defaults. - -
  3. Detection of structural cycles (an occurs check) - is not yet implemented, and thus printing infinite structures - will still result in a loop. -
- diff --git a/content/examples/basic/text/en.md b/content/examples/basic/text/en.md index b2cc446d7..4771abd0d 100644 --- a/content/examples/basic/text/en.md +++ b/content/examples/basic/text/en.md @@ -233,6 +233,56 @@ My favorite project is [CUE](https://cuelang.org "CUElang.org"). --- +## Footnotes + +The Markdown flavour understood by Hugo support footnotes. +Each footnote is composed of two elements: the link to the footnote, and the footnote itself. +The footnote gains an automatic link back to the initial link's location on the page. +Each link is a superscript number, linked to the relevant numbered footnote. +The footnote source reference id must match between the footnote link and the +footnote text, but the reference id isn't exposed on the rendered page. + +The footnote will appear at the end of the page, **no matter where the +footnote's text is specified in the Markdown document**. The footnote does need +to be specified as a paragraph by itself, however, so it's not a bad idea to +specify the note immediately after the paragraph containing the link, so that +context isn't lost for the author. + +Because the location of the footnote block can't be controlled (and is at the +bottom of the page, following the rendered document), consider including a +"`## Footnotes`" H2-heading as the very last source line of any document that +uses footnotes. This heading has been added to this page as an example. + +Here's an example of a footnote: + +``` +This is a link to a footnote.[^foo] +This is the sentence following the link to the footnote. + +[^foo]: This is the footnote. It continues until the end of the paragraph. +This means that source newlines don't stop the footnote. +The entire paragraph is rendered at the bottom of the page. +One or more newlines can be inserted using the standard trailing-backslash mechanism ...\ +\ +... but they don't look *great*. Probably best avoided. + +This is a new paragraph that's not part of the footnote. +``` + +This is a link to a footnote.[^foo] +This is the sentence following the link to the footnote. + +[^foo]: This is the footnote. It continues until the end of the paragraph. +This means that source newlines don't stop the footnote. +The entire paragraph is rendered at the bottom of the page. +One or more newlines can be inserted using the standard trailing-backslash mechanism ...\ +\ +... but they don't look *great*. Probably best avoided. + +This is a new paragraph that's not part of the footnote. + +--- + ## Escaping Characters To display a literal character that would otherwise be used to format text in a Markdown document, add a backslash (\\) in front of the character. @@ -266,3 +316,5 @@ You can use a backslash to escape the following characters. | \! | Exclamation sign | | | | | Pipe | In tables use `|` | {{< /table >}} + +## Footnotes diff --git a/hugo/content/en/docs/concept/the-logic-of-cue/index.md b/hugo/content/en/docs/concept/the-logic-of-cue/index.md index 76815e90d..202d8ac6e 100644 --- a/hugo/content/en/docs/concept/the-logic-of-cue/index.md +++ b/hugo/content/en/docs/concept/the-logic-of-cue/index.md @@ -536,10 +536,12 @@ even across files. Once set, there is no need to look at the individual values and files to know these constraints apply. Such information is not readily available for -fully expanded configurations.[$^1$](#footnotes) +fully expanded configurations.[^a] But also with inheritance-based solutions that allow arbitrary overrides, templates give little information. +[^a]: Although CUE could be used to verify those properties in such data-only configurations. + The ability to enforce constraints top down is crucial for any large-scale configuration setup. GCL and Jsonnet address this with assertions. @@ -681,7 +683,12 @@ In CUE, though, we typically refer to `acmeMonitoring` as a constraint. After all, applying it will guarantee that a job implements monitoring in a certain way. If such a constraint also contains sensible defaults, however, -it simultaneously validates _and_ reduces boilerplate.[$^2$](#footnotes) +it simultaneously validates _and_ reduces boilerplate.[^b] + +[^b]: TFSs typically don't have default values, it is the structure itself that +is boilerplate removing, as the structure itself is what is the useful value. +But that is a different topic. It doesn't work quite as well if one needs +numeric values. This is why CUE adds defaults. This ability to simultaneously enforce constraints and remove boilerplate @@ -741,8 +748,10 @@ just plain ol' logic. Most cycles that do not result in infinite structures can be handled by CUE. In fact, it could handle most infinite structures in bounded time as well, but it puts limits on such cycles for -practical reasons.[$^3$](#footnotes) +practical reasons.[^c] +[^c]: Detection of structural cycles (an occurs check) is not yet implemented, +and thus printing infinite structures will still result in a loop. ### File organization @@ -782,21 +791,3 @@ One can read more about this in Ann Copestake's (2002, CSLI Publications, ISBN 1-57586-261-1). ## Footnotes - - -
    -
  1. Although CUE could be used to verify those properties in such - data-only configurations. - -
  2. TFSs typically don't have default values, it is the structure - itself that is boilerplate removing, as the structure itself - is what is the useful value. - But that is a different topic. - It doesn't work quite as well if one needs numeric values. - This is why CUE adds defaults. - -
  3. Detection of structural cycles (an occurs check) - is not yet implemented, and thus printing infinite structures - will still result in a loop. -
- diff --git a/hugo/content/en/examples/basic/text/index.md b/hugo/content/en/examples/basic/text/index.md index b2cc446d7..4771abd0d 100644 --- a/hugo/content/en/examples/basic/text/index.md +++ b/hugo/content/en/examples/basic/text/index.md @@ -233,6 +233,56 @@ My favorite project is [CUE](https://cuelang.org "CUElang.org"). --- +## Footnotes + +The Markdown flavour understood by Hugo support footnotes. +Each footnote is composed of two elements: the link to the footnote, and the footnote itself. +The footnote gains an automatic link back to the initial link's location on the page. +Each link is a superscript number, linked to the relevant numbered footnote. +The footnote source reference id must match between the footnote link and the +footnote text, but the reference id isn't exposed on the rendered page. + +The footnote will appear at the end of the page, **no matter where the +footnote's text is specified in the Markdown document**. The footnote does need +to be specified as a paragraph by itself, however, so it's not a bad idea to +specify the note immediately after the paragraph containing the link, so that +context isn't lost for the author. + +Because the location of the footnote block can't be controlled (and is at the +bottom of the page, following the rendered document), consider including a +"`## Footnotes`" H2-heading as the very last source line of any document that +uses footnotes. This heading has been added to this page as an example. + +Here's an example of a footnote: + +``` +This is a link to a footnote.[^foo] +This is the sentence following the link to the footnote. + +[^foo]: This is the footnote. It continues until the end of the paragraph. +This means that source newlines don't stop the footnote. +The entire paragraph is rendered at the bottom of the page. +One or more newlines can be inserted using the standard trailing-backslash mechanism ...\ +\ +... but they don't look *great*. Probably best avoided. + +This is a new paragraph that's not part of the footnote. +``` + +This is a link to a footnote.[^foo] +This is the sentence following the link to the footnote. + +[^foo]: This is the footnote. It continues until the end of the paragraph. +This means that source newlines don't stop the footnote. +The entire paragraph is rendered at the bottom of the page. +One or more newlines can be inserted using the standard trailing-backslash mechanism ...\ +\ +... but they don't look *great*. Probably best avoided. + +This is a new paragraph that's not part of the footnote. + +--- + ## Escaping Characters To display a literal character that would otherwise be used to format text in a Markdown document, add a backslash (\\) in front of the character. @@ -266,3 +316,5 @@ You can use a backslash to escape the following characters. | \! | Exclamation sign | | | | | Pipe | In tables use `|` | {{< /table >}} + +## Footnotes