From e6fb301a9ba91b8d38a4128d5fc7559175d3d7a0 Mon Sep 17 00:00:00 2001 From: jutty Date: Wed, 7 Jan 2026 01:04:48 -0300 Subject: [PATCH] Cleanup and update docs --- static/graph.toml | 171 +++++++++++++++------------------------------- 1 file changed, 54 insertions(+), 117 deletions(-) diff --git a/static/graph.toml b/static/graph.toml index a31f3b1..308bf74 100644 --- a/static/graph.toml +++ b/static/graph.toml @@ -26,7 +26,7 @@ See |CLI| for defaults and details on the CLI options. ## Graph Syntax -The graph is a TOML file. You can create nodes by adding text such as: +The graph is a |TOML| file. You can create nodes by adding text such as: ` [nodes.Computer] @@ -241,8 +241,6 @@ particles|ParticlePhysics This example will render as "particles|ParticlePhysics": the word particles pointing to a node with id `ParticlePhysics`. -This allows you to specify what to display as the anchor text, but just the ID wrapped inside two `|` characters also works: - en can resolve IDs case insensitively (with priority to case-sensitive matches) and will also collapse spaces when trying to resolve an ID, so you can also write: ` @@ -254,15 +252,9 @@ And if an anchor with the id `enDocumentation` or any other case-insensitive com In summary, all of the anchors below are valid and lead to the same page: ` -|en Syntax|https://en.jutty.dev/node/Syntax| -|en Syntax|https://en.jutty.dev/node/Syntax -Syntax|https://en.jutty.dev/node/Syntax - -Syntax|/node/syntax - |syntax|Syntax Syntax|syntax -Syntax|syntax| +Syntax|syn tax| |Syntax| |syntax| @@ -271,9 +263,20 @@ Syntax|syntax| While flexible, this can sometimes be ambiguous. See |AnchorSyntax| for some caveats regarding anchors. -## Preformatted and unformatted +## Formatting -The backtick character can be used to render preformatted blocks and code tags: +Supported formatting syntax includes: + +- `*` for bold +- `_` for italics +- `__` for underline +- `~~` for strikethrough + +To apply these, you can wrap a word in the formatting operators, so for instance `*this*` will be rnered as the word "this" in bold: *this*. + +## Rendering unformatted text + +The backtick character `\\`` can be used to render unformatted blocks and inline text: ` The asterisk `*` is special in en markup syntax. @@ -281,7 +284,7 @@ The asterisk `*` is special in en markup syntax. Using the syntax above, the asterisk won't be interpreted as the start of bold formatting. -This is useful for code but also for escaping characters with special meaning you wish to mention literally or render text with all spacing and line breaks unchanged. +This is useful for code but also for rendering characters with special meaning you wish to mention literally. Backticks on their own line will render a block of unformatted text such as the ones being used throughout this documentation to show code: @@ -291,9 +294,10 @@ everything in here will be rendered without formatting \\` ` -Finally, you can use the backslash `\\` anywhere to fully "escape" that character from being processed by en. +Finally, you can precede any character with a `\\\\` to fully _escape_ that character from being interpreted. Because |TOML| also treats backslashes specially, you'll likely need to use double slashes, as in `\\\\\\\\`. See |Escaping| for more details and examples. -## Lines + +## Paragraphs A block of lines not separated by an empty line is always joined together. This means if you write: @@ -307,15 +311,6 @@ You still get "a b c" as a result. The exception to this are lists, which are explained below and must have their lines grouped together. -## Formatting - -Supported formatting syntax includes: - -- `*` for bold -- `_` for italics -- `__` for underline -- `~~` for strikethrough - ### Lists A block of lines starting with a `-` character will be rendered as an unordered list: @@ -342,6 +337,39 @@ Inside lists, you can use `[ ]` and `[x]` to render checkboxes: ` """ +[nodes.Escaping] +text = """ +The backslash (`\\\\`) works by immediately adding the following character as a literal and skipping any further interpretation of it. + +For example, if you want to write inline unformatted text containing a backtick, you will need to escape it, so that to render `println!("\\`")` as unformatted inline text, you'd write `\\`println!("\\\\\\`")\\``, otherwise the second backtick would close the code tag midway through it. + +If you want to render a literal backslash, you can escape the backslash itself by using two backslashes: `\\\\\\\\`. + +## Interactions with TOML escaping + +Notice that TOML itself also handles escape codes, so to pass a backslash you will need to escape it as a double backslash inside strings delimited by double quotes or triple double quotes. You can use a single backslash inside a string delimited by single quotes: + +` +[node.Double] +text = "You need double slashes to escape an asterisk here: \\\\\\\\*" + +[node.TripleDouble] +text = \""" +Just as here: \\\\\\\\* +\""" + +[node.Single] +text = 'Here you need just one: \\\\*" + +[node.TripleSingle] +text = ''' +Here too: \\\\* +''' +` + +This has nothing to do with en's markup syntax per se, it's just a consequence of how newlines are also special in |TOML| syntax. For more details, see the |TOML documentation on Strings|https://toml.io/en/v1.1.0#string|. +""" + [nodes.AnchorSyntax] title = "Anchor Syntax" text = """ @@ -349,7 +377,7 @@ en's anchor syntax can be very flexible, but some situations lead to ambiguity. In short, following these two rules should keep you out of trouble: -- *Avoid special characters in your node IDs*: TOML allows you to use a wide range of characters in identifiers, but when writing your graph it's better keep your IDs simple +- *Avoid special characters in your node IDs*: |TOML| allows you to use a wide range of characters in identifiers, but when writing your graph it's better keep your IDs simple - When needed, use full three-pipe `|text|destination|` syntax to make your anchors fully unambiguous ## Punctuation in destinations @@ -440,7 +468,7 @@ It does this by looking at the destination and checking if it contains a `:`. Th text = """ en is a tool to write non-linear, connected pieces of text and have their references mapped out as a graph of connected information. -It works by ingesting a TOML file containing your node specification and serving it as a website that allows nodes to be browsed, searched and listed in relation to each other or as a shallow tree of nodes. +It works by ingesting a |TOML| file containing your node specification and serving it as a website that allows nodes to be browsed, searched and listed in relation to each other or as a shallow tree of nodes. ## Motivation @@ -487,97 +515,6 @@ en is only possible thanks to a number of projects and people: - Serde|https://serde.rs/ and the |toml crate|https://github.com/toml-rs/toml """ -[nodes.Test] -hidden = true -text = """ - -This node is just for testing syntax rendering, but I appreciate your curiosity. - -` -|en purple|https://purple.en/n/purple -cyan|https://cyan.en/n/cyan - -|en Giraffe|/node/Giraffe -|Gorilla|/node/Gorilla -Crow|/node/Crow - -|Circle|Circle -Circle|Circle -|Circle| -` - -|en purple|https://purple.en/n/purple -cyan|https://cyan.en/n/cyan - -|en Giraffe|/node/Giraffe -Crow|/node/Crow - -Circle|Circle -|Circle| - -These `|anchors|` are inside `|backticks|Backtick` and should `|not render|https://test.com` as backticks but as `|raw text|` instead. This `|syntax is|` now `being demonstrated|https://test.com` here. - -Well |have I ever found such a long anchor in my entire life|Nowhere|, have I? - -This failed to parse due to a misunderstanding about what `parts.push(peaker.next().unwrap_or_else(|| unreachable!() ));` really meant. - -This greedy anchor is |at the end of a line|Somewhere -This greedy anchor is |at the end of a line|Somewhere| -This greedy anchor is |at the end of a line with a period|Somewhere|. -This inline code is `at the end of a line` -This inline code is `at the end of a line with a period`. - ---- - -For trailing characters you don't want as part of destination, add a third `|`: - -` -This gem|PreciousStone|, though green, was not an emerald. -` - -Which renders as: - -This gem|PreciousStone|, though green, was not an emerald. - -Supported for punctuation only. - -### Node anchors - -We saw example `docs|/node/Documentation`, but shorter syntax exists. - -## Green -## Green -## Green -## Purple -## Purple -## Purple -## Cyan -### Cyan -#### Cyan -### Cyan -## Cyan -## Épistème -## Épistème -## Epistème -## Epistēmē -### Epistēmē -#### Epistēmē -#### Epistēmē - -|en Syntax|https://en.jutty.dev/node/Syntax| -|en Syntax|https://en.jutty.dev/node/Syntax -Syntax|https://en.jutty.dev/node/Syntax - -Syntax|/node/syntax - -|syntax|Syntax -Syntax|syntax -Syntax|syntax| - -|Syntax| -|syntax| -`""" - [meta.config] content_language = "en" footer_credits = false