Documentation links fixed; User Guide deployment script added

.github/workflows/deploy-user-guide.yml

@@ -0,0 +1,38 @@
+name: Deploy User Guide
+
+on:
+  push:
+    paths: [ "work/book/**" ]
+    branches:
+      - master
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install
+        run: |
+          mkdir book
+          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.40/mdbook-v0.4.40-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./book
+          echo `pwd`/book >> $GITHUB_PATH
+      - name: Deploy
+        run: |
+          cd work/book
+          mdbook build
+          git worktree add gh-pages
+          git config user.name "deploy-user-guide"
+          git config user.email ""
+          cd gh-pages
+          git update-ref -d refs/heads/gh-pages
+          rm -rf *
+          mv ../output/* .
+          echo "lady-deirdre.lakhin.com" > CNAME
+          git add .
+          git commit -m "Deploy User Guide $GITHUB_SHA to gh-pages"
+          git push --force --set-upstream origin gh-pages

README.md

@@ -38,8 +38,8 @@
 
 [![Crate](https://img.shields.io/crates/v/lady-deirdre?label=Crate)](https://crates.io/crates/lady-deirdre)
 [![API Docs](https://img.shields.io/docsrs/lady-deirdre?label=API%20Docs)](https://docs.rs/lady-deirdre)
-[![User Guide](https://img.shields.io/badge/User_Guide-gray)](todo)
-[![Examples](https://img.shields.io/badge/Examples-gray)](https://github.com/Eliah-Lakhin/lady-deirdre/tree/master/work/crates/examples)
+[![User Guide](https://img.shields.io/badge/User_Guide-passing-default)](https://lady-deirdre.lakhin.com/)
+[![Examples](https://img.shields.io/badge/Examples-passing-default)](https://github.com/Eliah-Lakhin/lady-deirdre/tree/master/work/crates/examples)
 
 Lady Deirdre is a framework for incremental programming language compilers,
 interpreters, and source code analyzers.
@@ -129,7 +129,7 @@ For detailed information, refer to the [Benchmarks page](https://github.com/Elia
 - [Source Code](https://github.com/Eliah-Lakhin/lady-deirdre)
 - [Main Crate](https://crates.io/crates/lady-deirdre)
 - [API Documentation](https://docs.rs/lady-deirdre)
-- [User Guide](todo)
+- [User Guide](https://lady-deirdre.lakhin.com/)
 - [Examples](https://github.com/Eliah-Lakhin/lady-deirdre/tree/master/work/crates/examples)
 - [License Agreement](https://github.com/Eliah-Lakhin/lady-deirdre/blob/master/EULA.md)
 
@@ -175,7 +175,7 @@ work in commercial products, both open-source and closed-source.
 
 This license restricts the total gross revenue you can earn using software
 products based on Lady Deirdre. Once your product exceeds this limitation, you
-can purchase the annual [Unrestricted Commercial License](todo) on my Patreon
+can purchase the annual Unrestricted Commercial License on my Patreon
 page, which removes these restrictions.
 
 ### What happens when the Unrestricted Commercial License expires?

work/book/src/code-formatters/code-formatters.md

@@ -77,4 +77,5 @@ considering the concrete tree configuration. It then feeds the source code
 tokens into the syntax-unaware Pretty Printer. The printer generates the final
 output string.
 
-The [Json Formatter](todo) example demonstrates the basic usage of both tools.
+The [Json Formatter](https://github.com/Eliah-Lakhin/lady-deirdre/tree/master/work/crates/examples/src/json_formatter)
+example demonstrates the basic usage of both tools.

work/book/src/introduction.md

@@ -59,7 +59,7 @@ the core concepts behind these tools.
 - [Source Code](https://github.com/Eliah-Lakhin/lady-deirdre)
 - [Main Crate](https://crates.io/crates/lady-deirdre)
 - [API Documentation](https://docs.rs/lady-deirdre)
-- [User Guide](todo)
+- [User Guide](https://lady-deirdre.lakhin.com/)
 - [Examples](https://github.com/Eliah-Lakhin/lady-deirdre/tree/master/work/crates/examples)
 - [License Agreement](https://github.com/Eliah-Lakhin/lady-deirdre/blob/master/EULA.md)
 

work/book/src/lexis/lexical-grammar.md

@@ -34,8 +34,9 @@
 
 # Lexical Grammar
 
-The lexical grammar is defined using the [Token derive macro](todo) on an
-arbitrary enum type, which represents the type of the token.
+The lexical grammar is defined using
+the [Token derive macro](https://docs.rs/lady-deirdre/2.0.0/lady_deirdre/lexis/derive.Token.html)
+on an arbitrary enum type, which represents the type of the token.
 
 Each enum variant represents a token variant. To specify the scanning rule for
 an individual variant, you annotate that variant with the `#[rule(...)]` macro
@@ -44,7 +45,7 @@ attribute and provide a regular expression to match the corresponding token.
 The macro uses these expressions to build an optimized finite-state automaton,
 from which it generates the scanning program..
 
-From the [JSON example](todo):
+From the [JSON example](https://github.com/Eliah-Lakhin/lady-deirdre/blob/master/work/crates/examples/src/json_grammar/lexis.rs#L47):
 
 ```rust,noplayground
 use lady_deirdre::lexis::Token;

work/book/src/lexis/source-code.md

@@ -45,7 +45,8 @@ trait, providing a minimal set of features enabling inspection of its content,
 including the source code text and its lexical structure.
 
 The crate offers specialized source code managers with distinct API options and
-performance characteristics. For instance, while the [TokenBuffer](todo) lacks
-general incremental rescanning capabilities, it offers slightly better
+performance characteristics. For instance, while
+the [TokenBuffer](https://docs.rs/lady-deirdre/2.0.0/lady_deirdre/lexis/struct.TokenBuffer.html)
+lacks general incremental rescanning capabilities, it offers slightly better
 performance than the
 mutable [Document](https://docs.rs/lady-deirdre/2.0.0/lady_deirdre/units/enum.Document.html).

work/book/src/overview.md

@@ -146,11 +146,12 @@ syntax tree's node type.
 ### Lexis
 
 First, you need to specify the type of the lexis. Typically, you can do this
-using the [derive macro](todo) on your enum type, where the enum variants denote
-individual token types. The token's lexical scanning rules are described in
-terms of regular expressions.
+using
+the [derive macro](https://docs.rs/lady-deirdre/2.0.0/lady_deirdre/lexis/derive.Token.html)
+on your enum type, where the enum variants denote individual token types.
+The token's lexical scanning rules are described in terms of regular expressions.
 
-From the [JSON example](todo):
+From the [JSON example](https://github.com/Eliah-Lakhin/lady-deirdre/blob/master/work/crates/examples/src/json_grammar/lexis.rs#L47):
 
 ```rust,noplayground
 #[derive(Token)]
@@ -179,7 +180,7 @@ during the syntax parsing stage.
 ### Syntax
 
 The syntax grammar is described similarly using enum types and
-the [derive macro](todo).
+the [derive macro](https://docs.rs/lady-deirdre/2.0.0/lady_deirdre/syntax/derive.Node.html).
 
 The node's parsing rules are described in terms of LL(1) grammars, but you can
 also implement your own custom parsers for individual node types, allowing for
@@ -194,7 +195,7 @@ the parser establishes ascending node-to-parent relationships, allowing
 traversal from nodes to the tree root. Lady Deirdre's incremental reparser
 ensures both kinds of references are kept up to date.
 
-From the [JSON example](todo):
+From the [JSON example](https://github.com/Eliah-Lakhin/lady-deirdre/blob/master/work/crates/examples/src/json_grammar/syntax.rs#L52):
 
 ```rust,noplayground
 #[derive(Node)]
@@ -369,7 +370,8 @@ let (_, attribute_value) = semantics
 ```
 
 You can find a complete setup example of the syntax tree with semantics in the
-[Chain Analysis](todo) example.
+[Chain Analysis](https://github.com/Eliah-Lakhin/lady-deirdre/blob/master/work/crates/examples/src/chain_analysis/syntax.rs)
+example.
 
 ### Concurrent Analysis
 
@@ -394,7 +396,7 @@ operations.
 These functions return RAII-guard-like objects called "tasks" through which
 necessary operations can be performed.
 
-From the [Chain Analysis](todo) example:
+From the [Chain Analysis](https://github.com/Eliah-Lakhin/lady-deirdre/blob/master/work/crates/examples/src/chain_analysis/mod.rs#L84) example:
 
 ```rust,noplayground
 let analyzer = Analyzer::<ChainNode>::new(AnalyzerConfig::default());

work/book/src/semantics/configuration-issues.md

@@ -60,8 +60,9 @@ Canonical compilers written with Lady Deirdre should be designed to be
 infallible. If you receive an abnormal error from a framework function, it
 likely indicates a bug in your program's code that needs to be fixed.
 
-In particular, the computable functions of the [Chain Analysis](todo) example
-use
+In particular, the computable functions of
+the [Chain Analysis](https://github.com/Eliah-Lakhin/lady-deirdre/blob/master/work/crates/examples/src/chain_analysis/semantics.rs#L337)
+example use
 the [unwrap_abnormal](https://docs.rs/lady-deirdre/2.0.0/lady_deirdre/analysis/type.AnalysisResult.html#method.unwrap_abnormal)
 helper function to filter out normal errors from abnormal ones, panicking if an
 abnormal error is encountered.

work/book/src/semantics/grammar-setup.md

@@ -53,7 +53,9 @@ to extend this enum type with additional metadata:
 3. Optionally, you can specify the syntax tree classifier using
    the `#[classifier]` macro attribute.
 
-From the [Chain Analysis](todo) example:
+From
+the [Chain Analysis](https://github.com/Eliah-Lakhin/lady-deirdre/tree/master/work/crates/examples/src/chain_analysis)
+example:
 
 ```rust,noplayground
 #[derive(Node)]
@@ -142,8 +144,10 @@ function.
 The type you use as a parameter of the Semantics object is called a *feature*.
 
 Typically, the semantic feature is a user-defined struct type derived from the
-Feature trait using the [Feature derive macro](todo). This structure consists of
-fields that are either attributes or other feature objects.
+Feature trait using
+the [Feature derive macro](https://docs.rs/lady-deirdre/2.0.0/lady_deirdre/analysis/derive.Feature.html).
+This structure consists of fields that are either attributes or other feature
+objects.
 
 ```rust,noplayground
 #[derive(Feature)]

work/book/src/semantics/granularity.md

@@ -44,9 +44,10 @@ the graph more efficiently. This is achieved by comparing newly computed
 attribute values with previous caches and stopping the propagation process if
 they are found to be equal.
 
-In the Chain Analysis example, the [BlockAnalysis](todo) input attribute
-initially collects all assignment statements and inner blocks into two dedicated
-maps: `assignments` and `blocks`.
+In the Chain Analysis example,
+the [BlockAnalysis](https://github.com/Eliah-Lakhin/lady-deirdre/blob/master/work/crates/examples/src/chain_analysis/semantics.rs#L197)
+input attribute initially collects all assignment statements and inner blocks
+into two dedicated maps: `assignments` and `blocks`.
 
 ```rust,noplayground
 #[derive(Default, Clone, PartialEq, Eq)]
@@ -56,16 +57,20 @@ pub struct BlockAnalysis {
 }
 ```
 
-Later on, these maps are utilized in the [LocalResolution](todo)
-and [GlobalResolution](todo) attributes. In theory, we could directly read the
-*BlockAnalysis* attribute from these computable functions. However, in practice,
-when the end user modifies the content of a block, it's likely that one of the
-BlockAnalysis maps may remain unchanged. Therefore, depending solely on changes
-in the overall BlockAnalysis attribute to read just one of the two maps is
-probably unnecessary[^blockanalysis].
+Later on, these maps are utilized in
+the [LocalResolution](https://github.com/Eliah-Lakhin/lady-deirdre/blob/master/work/crates/examples/src/chain_analysis/semantics.rs#L155)
+and
+[GlobalResolution](https://github.com/Eliah-Lakhin/lady-deirdre/blob/master/work/crates/examples/src/chain_analysis/semantics.rs#L85)
+attributes. In theory, we could directly read the *BlockAnalysis* attribute from
+these computable functions. However, in practice, when the end user modifies the
+content of a block, it's likely that one of the BlockAnalysis maps may remain
+unchanged. Therefore, depending solely on changes in the overall BlockAnalysis
+attribute to read just one of the two maps is probably unnecessary[^blockanalysis].
 
 For these reasons, we spread both maps into the
-intermediate [BlockAssignmentMap](todo) and [BlockNamespaceMap](todo) attributes
+intermediate
+[BlockAssignmentMap](https://github.com/Eliah-Lakhin/lady-deirdre/blob/master/work/crates/examples/src/chain_analysis/semantics.rs#L310)
+and [BlockNamespaceMap](https://github.com/Eliah-Lakhin/lady-deirdre/blob/master/work/crates/examples/src/chain_analysis/semantics.rs#L337) attributes
 by cloning the hash maps into them. Subsequently, we read these maps in the
 final attributes through these intermediaries independently.
 
@@ -127,9 +132,12 @@ The `SharedComputable::compute_shared` function is a mandatory computation
 function through which you return `Shared<T>` instead of `T`.
 
 This trait is especially handy for propagating the Shared value through
-intermediate attributes. For instance, the [BlockAssignmentMap](todo) simply
-clones a shared map from the [BlockAnalysis](todo) (which is cheap, as it
-merely creates a new smart pointer to the same allocation).
+intermediate attributes. For instance,
+the [BlockAssignmentMap](https://github.com/Eliah-Lakhin/lady-deirdre/blob/master/work/crates/examples/src/chain_analysis/semantics.rs#L328)
+simply clones a shared map from
+the [BlockAnalysis](https://github.com/Eliah-Lakhin/lady-deirdre/blob/master/work/crates/examples/src/chain_analysis/semantics.rs#L198)
+(which is cheap, as it merely creates a new smart pointer to the same
+allocation).
 
 ```rust,noplayground
 #[derive(Default, Clone, PartialEq, Eq)]

work/book/src/semantics/incremental-computations.md

@@ -99,14 +99,18 @@ caches of these attributes. If this metadata is crucial to the attribute's
 computable function implementation, it should be reflected in the initial
 semantic model objects by the input attributes.
 
-In the Chain Analysis example, only the [BlockAnalysis](todo) attribute (which
-is a `#[scoped]` attribute of the `#[scope]` node syntax tree node) iterates
-through the block's inner let-statements and the inner blocks and collects them
-into HashMaps usable for further analysis. Moreover, this attribute does not
-inspect the inner structure of its nested blocks too, because the sub-block's
-inner syntax structure is outside of the current block scope.
-
-Other attributes directly (e.g., [BlockAssignmentMap](todo)) or indirectly
-(e.g., [LocalResolution](todo) and [GlobalResolution](todo)) read the
-BlockAnalysis's HashMaps, but they do not perform deeper inspection of the
-node's syntax tree structure inside their computable functions.
+In the Chain Analysis example, only
+the [BlockAnalysis](https://github.com/Eliah-Lakhin/lady-deirdre/blob/master/work/crates/examples/src/chain_analysis/semantics.rs#L202)
+attribute (which is a `#[scoped]` attribute of the `#[scope]` node syntax tree
+node) iterates through the block's inner let-statements and the inner blocks and
+collects them into HashMaps usable for further analysis. Moreover, this
+attribute does not inspect the inner structure of its nested blocks too, because
+the sub-block's inner syntax structure is outside of the current block scope.
+
+Other attributes directly (e.g.,
+[BlockAssignmentMap](https://github.com/Eliah-Lakhin/lady-deirdre/blob/master/work/crates/examples/src/chain_analysis/semantics.rs#L310))
+or indirectly (e.g.,
+[LocalResolution](https://github.com/Eliah-Lakhin/lady-deirdre/blob/master/work/crates/examples/src/chain_analysis/semantics.rs#L155)
+and [GlobalResolution](https://github.com/Eliah-Lakhin/lady-deirdre/blob/master/work/crates/examples/src/chain_analysis/semantics.rs#L85))
+read the BlockAnalysis's HashMaps, but they do not perform deeper inspection of
+the node's syntax tree structure inside their computable functions.

work/book/src/semantics/scope-access.md

@@ -43,7 +43,8 @@ node within the node's scope. The Analyzer is responsible for maintaining the
 accuracy of this attribute's value, and you can utilize it within any computable
 functions.
 
-For instance, in the Chain Analysis example, the [LocalResolution](todo)
+For instance, in the Chain Analysis example,
+the [LocalResolution](https://github.com/Eliah-Lakhin/lady-deirdre/blob/master/work/crates/examples/src/chain_analysis/semantics.rs#L172)
 function accesses the scope block of the `ChainNode::Key` node by utilizing this
 attribute.
 
@@ -82,9 +83,9 @@ parent scopes. The `ChainNode::Block` node, which serves as a top node of a
 scope, is nested within its parent, Block[^parent]. By iteratively climbing up,
 you will eventually reach the root of the syntax tree.
 
-The [GlobalResolution](todo) attribute leverages this feature to calculate the
-ultimate resolution of the `ChainNode::Key` value by ascending through the
-hierarchy of nested blocks.
+The [GlobalResolution](https://github.com/Eliah-Lakhin/lady-deirdre/blob/master/work/crates/examples/src/chain_analysis/semantics.rs#L85)
+attribute leverages this feature to calculate the ultimate resolution of
+the `ChainNode::Key` value by ascending through the hierarchy of nested blocks.
 
 ```rust,noplayground
 impl Computable for GlobalResolution {

work/book/src/semantics/semantic-graph.md

@@ -120,7 +120,8 @@ Similarly to the syntax analysis stage, semantic analysis should be resilient to
 errors. If the computable function cannot fully infer the target value, it
 attempts to compute as much metadata as possible or fallback to reasonable
 defaults without causing a panic. For this reason, most semantic model objects
-in the [Chain Analysis](todo) example implement the Default trait.
+in the [Chain Analysis](https://github.com/Eliah-Lakhin/lady-deirdre/blob/master/work/crates/examples/src/chain_analysis/semantics.rs#L147)
+example implement the Default trait.
 
 For instance, in Rust source code, when introducing a variable with `let x;`,
 the variable's type depends on the initialization expression. In the
@@ -142,9 +143,11 @@ Inside the computable function of the attribute, you can read other attribute
 values. This mechanism allows you to infer more specific semantic facts from
 more general facts.
 
-For instance, in the Chain Analysis example, the [LocalResolution](todo)
+For instance, in the Chain Analysis example,
+the [LocalResolution](https://github.com/Eliah-Lakhin/lady-deirdre/blob/master/work/crates/examples/src/chain_analysis/semantics.rs#L155)
 attribute infers let-statement references within the local block in which it was
-declared based on all local assignments ([BlockAssignmentMap](todo) attribute)
+declared based on all local assignments
+([BlockAssignmentMap](https://github.com/Eliah-Lakhin/lady-deirdre/blob/master/work/crates/examples/src/chain_analysis/semantics.rs#L306) attribute)
 within this block.
 
 ```rust,noplayground

work/book/src/semantics/semantics.md

@@ -65,7 +65,8 @@ the compilation project.
 
 ## Chain Analysis Example
 
-The subchapters of this book section refer to the [Chain Analysis](todo)
+The subchapters of this book section refer to
+the [Chain Analysis](https://github.com/Eliah-Lakhin/lady-deirdre/tree/master/work/crates/examples/src/chain_analysis)
 example, which illustrates the basic concepts of the framework.
 
 The example program attempts to analyze a simple programming language consisting

work/book/src/semantics/tasks-management.md

@@ -161,9 +161,10 @@ function calls. In principle, it is not capable of checking this event during
 function execution. To make the trigger handle state examination more granular,
 you can manually check its state in long-running computable functions.
 
-For instance, in the [BlockAnalysis](todo) attribute of the Chain Analysis
-example, we are checking the interruption state during the iteration through the
-assignment statements of the block.
+For instance, in
+the [BlockAnalysis](https://github.com/Eliah-Lakhin/lady-deirdre/blob/master/work/crates/examples/src/chain_analysis/semantics.rs#L223)
+attribute of the Chain Analysis example, we are checking the interruption state
+during the iteration through the assignment statements of the block.
 
 ```rust,noplayground
 impl Computable for BlockAnalysis {

work/book/src/semantics/tree-index.md

@@ -98,8 +98,10 @@ the [Classifier](https://docs.rs/lady-deirdre/2.0.0/lady_deirdre/analysis/trait.
 trait. It denotes classes of nodes, essentially serving as indices, and the
 function that partitions requested nodes between these classes.
 
-In the [Chain Analysis](todo) example, we define just one class for
-all `ChainNode::Key` nodes within the syntax tree.
+In
+the [Chain Analysis](https://github.com/Eliah-Lakhin/lady-deirdre/blob/master/work/crates/examples/src/chain_analysis/semantics.rs#L411)
+example, we define just one class for all `ChainNode::Key` nodes within the
+syntax tree.
 
 ```rust,noplayground
 #[derive(Clone, PartialEq, Eq, Hash)]