docs/concept: logic-of-cue: use proper footnotes

The site's Markdown flavour recognises footnotes, and renders them more nicely than the ad-hoc homebrew equivalent that we use in The Logic Of CUE concept guide. This updates that guide to use the supported form of footnote, whilst also adding a section demonstrating them to the relevant /examples/basic/text page. Preview-Path: /docs/concept/the-logic-of-cue/ Preview-Path: /examples/basic/text/ Signed-off-by: Jonathan Matthews <[email protected]> Change-Id: I90c3bebcaba8093cdbb70b63d9ef763938a87c38 Reviewed-on: https://review.gerrithub.io/c/cue-lang/cuelang.org/+/1199894 TryBot-Result: CUEcueckoo <[email protected]> Reviewed-by: Paul Jolly <[email protected]>
cue-lang · Aug 28, 2024 · 3b76385 · 3b76385
1 parent b24925a
commit 3b76385
Show file tree

Hide file tree

Showing 4 changed files with 128 additions and 42 deletions.
diff --git 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
-
-<small>
-<ol>
-<li> Although CUE could be used to verify those properties in such
-   data-only configurations.
-
-<li> 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.
-
-<li> Detection of structural cycles (an occurs check)
-   is not yet implemented, and thus printing infinite structures
-   will still result in a loop.
-</ol>
-</small>
diff --git 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    |                             |
 | &#124; | Pipe                | In tables use `&#124;`      |
 {{< /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
@@ -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
-
-<small>
-<ol>
-<li> Although CUE could be used to verify those properties in such
-   data-only configurations.
-
-<li> 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.
-
-<li> Detection of structural cycles (an occurs check)
-   is not yet implemented, and thus printing infinite structures
-   will still result in a loop.
-</ol>
-</small>
diff --git 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    |                             |
 | &#124; | Pipe                | In tables use `&#124;`      |
 {{< /table >}}
+
+## Footnotes