Make hidden content visible; add TODOs on every page

john-cd · Oct 16, 2024 · 80fd41b · 80fd41b
1 parent 360db4e
commit 80fd41b
Show file tree

Hide file tree

Showing 228 changed files with 679 additions and 743 deletions.
diff --git a/drafts/asref.md b/drafts/asref.md
@@ -1,8 +1,9 @@
-<div class="hidden">
-TODO:
+# AsRef and &T
 
 [When and why to use AsRef<T>instead of &T][stackoverflow-asref]⮳
 
 [stackoverflow-asref]: https://stackoverflow.com/questions/66026309/when-and-why-to-use-asreft-instead-of-t
 
+<div class="hidden">
+TODO: write
 </div>
diff --git a/drafts/cd_ci.md b/drafts/cd_ci.md
@@ -24,7 +24,7 @@
         cargo pants
 ```
 
-[`install-action`][install-action]{{hi:install-action}}⮳ is a GitHub Action for installing development tools (mainly from GitHub Releases).
+[`install-action`][install_action-github]{{hi:install-action}}⮳ is a GitHub Action for installing development tools (mainly from GitHub Releases).
 
 ```yaml
 - uses: taiki-e/install-action@v2
@@ -136,21 +136,14 @@ Example `.github/workflows/<name>.yml`
 [How to cache docker-compose build inside github-action][stackoverflow-how-to-cache-docker-compose-build-inside-github-action]⮳
 [stackoverflow-how-to-cache-docker-compose-build-inside-github-action]: https://stackoverflow.com/questions/61491484/how-to-cache-docker-compose-build-inside-github-action
 
-{{#include ../refs/link-refs.md}}
-
-<div class="hidden">
-TODO:
-
-- [Optimizing CI/CD pipelines in your Rust projects][blog-optimizing-ci-cd-pipelines-rust-project]⮳
+[Optimizing CI/CD pipelines in your Rust projects][blog-optimizing-ci-cd-pipelines-rust-project]⮳
 
-[blog-optimizing-ci-cd-pipelines-rust-project]: https://blog.logrocket.com/optimizing-ci-cd-pipelines-rust-projects/
+[GitHub Action for installing development tools (mainly from GitHub Releases)][install_action-github]⮳
 
-- [GitHub Action for installing development tools (mainly from GitHub Releases)][install-action]⮳
+[Experience about deploying mdbook on github using github action - tutorials - The Rust Programming Language Forum][forum-deploying-mdbook-on-github-using-github-action]⮳
 
-[install-action]: https://github.com/taiki-e/install-action/
-
-[Experience about deploying mdbook on github using github action - tutorials - The Rust Programming Language Forum][deploying-mdbook-on-github-using-github-action]⮳
-
-[deploying-mdbook-on-github-using-github-action]: https://users.rust-lang.org/t/experience-about-deploying-mdbook-on-github-using-github-action/81408
+{{#include ../refs/link-refs.md}}
 
+<div class="hidden">
+TODO: organize see also
 </div>
diff --git a/drafts/result.md b/drafts/result.md
@@ -0,0 +1,5 @@
+# Result
+
+## See also
+
+- [what-is-the-rust-equivalent-to-a-try-catch-statement][stackoverflow-what-is-the-rust-equivalent-to-a-try-catch-statement]⮳
diff --git a/drafts/template/$section1$.incl.md b/drafts/template/$section1$.incl.md
@@ -3,5 +3,4 @@
 | [$example1$][ex-$example1$] | [![$crate1$][c-$crate1$-badge]][c-$crate1$] | [![cat-$cat1$][cat-$cat$-badge]][cat-$cat1$] |
 
 <div class="hidden">
-TODO:
 </div>
diff --git a/drafts/template/$section1$.md b/drafts/template/$section1$.md
@@ -14,6 +14,6 @@ $description1$
 
 {{#include refs.incl.md}}
 {{#include ../../refs/link-refs.md}}
+
 <div class="hidden">
-TODO:
 </div>
diff --git a/drafts/template/index.md b/drafts/template/index.md
@@ -12,6 +12,6 @@ $category-description$
 
 {{#include refs.incl.md}}
 {{#include ../../refs/link-refs.md}}
+
 <div class="hidden">
-TODO:
 </div>
diff --git a/src/categories.md b/src/categories.md
@@ -95,5 +95,4 @@
 {{#include refs/link-refs.md}}
 
 <div class="hidden">
-TODO:
 </div>
diff --git a/src/categories/algorithms/index.md b/src/categories/algorithms/index.md
@@ -14,6 +14,4 @@ Rust implementations of core algorithms{{hi:Algorithms}} such as hashing{{hi:Has
 {{#include ../../refs/link-refs.md}}
 
 <div class="hidden">
-TODO:
-
 </div>
diff --git a/src/categories/algorithms/randomness.md b/src/categories/algorithms/randomness.md
@@ -70,6 +70,7 @@ Randomly generates a string of given length ASCII characters with custom user-de
 
 {{#include refs.incl.md}}
 {{#include ../../refs/link-refs.md}}
+
 <div class="hidden">
-TODO:
+TODO: review
 </div>
diff --git a/src/categories/algorithms/sorting.md b/src/categories/algorithms/sorting.md
@@ -32,14 +32,13 @@ Sorts a vector{{hi:Vector}} of Person structs with properties `name` and `age` b
 {{#include ../../../deps/tests/sort_struct.rs}}
 ```
 
-{{#include refs.incl.md}}
-{{#include ../../refs/link-refs.md}}
-<div class="hidden">
-TODO:
+## See also
 
-## Sorting + Rust
+- A Rust implementation of Glidesort,a stable adaptive quicksort/mergesort hybrid sorting algorithm: [glidesort][c-glidesort-github]⮳
 
-- A Rust implementation of Glidesort,a stable adaptive quicksort/mergesort hybrid sorting algorithm: [glidesort][glidesort-github]⮳
+{{#include refs.incl.md}}
+{{#include ../../refs/link-refs.md}}
 
-[glidesort-github]: https://github.com/orlp/glidesort
+<div class="hidden">
+TODO: organize
 </div>
diff --git a/src/categories/api-bindings/index.md b/src/categories/api-bindings/index.md
@@ -28,5 +28,5 @@ Idiomatic wrappers of specific APIs{{hi:APIs}} for convenient access from Rust.
 {{#include ../../refs/link-refs.md}}
 
 <div class="hidden">
-TODO:
+TODO: write
 </div>
diff --git a/src/categories/asynchronous/async.md b/src/categories/asynchronous/async.md
@@ -55,5 +55,4 @@ Alternatives to the Tokio async ecosystem include:
 {{#include ../../refs/link-refs.md}}
 
 <div class="hidden">
-TODO:
 </div>
diff --git a/src/categories/asynchronous/async_and_blocking.md b/src/categories/asynchronous/async_and_blocking.md
@@ -68,5 +68,4 @@ In other cases, it may be easier to structure the application as largely synchro
 {{#include ../../refs/link-refs.md}}
 
 <div class="hidden">
-TODO:
 </div>
diff --git a/src/categories/asynchronous/async_channels.incl.md b/src/categories/asynchronous/async_channels.incl.md
@@ -3,5 +3,5 @@
 |  | [![tokio][c-tokio-badge]][c-tokio] | [![cat-asynchronous][cat-asynchronous-badge]][cat-asynchronous] |
 
 <div class="hidden">
-TODO:
+TODO: add recipe link
 </div>
diff --git a/src/categories/asynchronous/async_channels.md b/src/categories/asynchronous/async_channels.md
@@ -36,9 +36,11 @@ Another example:
 
 [![postage][c-postage-badge]][c-postage]  [![postage-lib.rs][c-postage-lib.rs-badge]][c-postage-lib.rs]
 
+Fast sync and async channel: [Kanal][c-kanal-github]
+
 {{#include refs.incl.md}}
 {{#include ../../refs/link-refs.md}}
 
 <div class="hidden">
-TODO:
+TODO: organize see also
 </div>
diff --git a/src/categories/asynchronous/async_traits.md b/src/categories/asynchronous/async_traits.md
@@ -30,5 +30,5 @@ In addition, traits that use `-> impl Trait` and `async fn` are not object-safe{
 {{#include ../../refs/link-refs.md}}
 
 <div class="hidden">
-TODO:
+TODO: add to with new Rust features
 </div>
diff --git a/src/categories/asynchronous/futures.incl.md b/src/categories/asynchronous/futures.incl.md
@@ -3,5 +3,5 @@
 |  | [![futures][c-futures-badge]][c-futures] | [![cat-asynchronous][cat-asynchronous-badge]][cat-asynchronous] |
 
 <div class="hidden">
-TODO:
+TODO: add recipe links
 </div>
diff --git a/src/categories/asynchronous/futures.md b/src/categories/asynchronous/futures.md
@@ -44,5 +44,5 @@ The [`futures`][c-futures]{{hi:futures}}⮳ crate provides an extension trait th
 {{#include ../../refs/link-refs.md}}
 
 <div class="hidden">
-TODO:
+TODO: cover future-utils ?
 </div>
diff --git a/src/categories/asynchronous/index.md b/src/categories/asynchronous/index.md
@@ -65,31 +65,12 @@ Alternatives to the Tokio async ecosystem include:
 - [![embassy][c-embassy-badge]][c-embassy]  [Embassy][c-embassy-website]⮳ [![embassy-github][c-embassy-github-badge]][c-embassy-github] for embedded systems.
 - [![mio][c-mio-badge]][c-mio]  [Mio][c-mio-crates.io]⮳ is a fast, low-level I/O library for Rust focusing on non-blocking APIs and event notification for building high performance I/O apps with as little overhead as possible over the OS abstractions. It is part of the Tokio ecosystem.
 
-{{#include refs.incl.md}}
-{{#include ../../refs/link-refs.md}}
-
-<div class="hidden">
-TODO:
-
-## Async Rust
+## See also
 
 [Asynchronous Programming in Rust][book-async-prog-rust]
 
-## Kanal
-
-- Fast sync and async channel [Kanal][kanal-github]
-
-## Tokio
-
-- [tokio.rs][tokio-rs]
-- [tokio examples][tokio-examples]
-- [tokio-rs async-stream][tokio-async-stream]
-- [tokio-rs mio][mio-github]
+{{#include refs.incl.md}}
+{{#include ../../refs/link-refs.md}}
 
-[book-async-prog-rust]: https://rust-lang.github.io/async-book/01_getting_started/01_chapter.html
-[kanal-github]: https://github.com/fereidani/kanal
-[tokio-rs]: https://tokio.rs
-[tokio-examples]: https://github.com/tokio-rs/tokio/tree/master/examples
-[tokio-async-stream]: https://github.com/tokio-rs/async-stream
-[mio-github]: https://github.com/tokio-rs/mio
+<div class="hidden">
 </div>
diff --git a/src/categories/asynchronous/streams.incl.md b/src/categories/asynchronous/streams.incl.md
@@ -3,5 +3,5 @@
 |  |  | [![cat-asynchronous][cat-asynchronous-badge]][cat-asynchronous] |
 
 <div class="hidden">
-TODO:
+TODO: add recipe and crate links
 </div>
diff --git a/src/categories/asynchronous/streams.md b/src/categories/asynchronous/streams.md
@@ -28,5 +28,5 @@ See also Tokio `async_stream`{{hi:async_stream}}.
 {{#include ../../refs/link-refs.md}}
 
 <div class="hidden">
-TODO:
+TODO: add more?
 </div>
diff --git a/src/categories/asynchronous/tokio.md b/src/categories/asynchronous/tokio.md
@@ -31,6 +31,11 @@ Example from [c-tokio_graceful_shutdown][c-tokio_graceful_shutdown]⮳:
 
 {{#include refs.incl.md}}
 {{#include ../../refs/link-refs.md}}
+
 <div class="hidden">
-TODO:
+TODO: - [tokio.rs][tokio-rs]
+- [tokio examples][tokio-examples]
+- [tokio-rs async-stream][tokio-async-stream]
+- [tokio-rs mio][mio-github]
+
 </div>
diff --git a/src/categories/authentication/index.md b/src/categories/authentication/index.md
@@ -18,5 +18,5 @@ Uses [`reqwest::RequestBuilder::basic_auth`][c-reqwest::RequestBuilder::basic_au
 {{#include ../../refs/link-refs.md}}
 
 <div class="hidden">
-TODO:
+TODO: Oauth?
 </div>
diff --git a/src/categories/caching/index.md b/src/categories/caching/index.md
@@ -16,6 +16,5 @@ Store the results of previous computations in order to reuse the results.
 {{#include ../../refs/link-refs.md}}
 
 <div class="hidden">
-TODO:
-
+TODO: expand caching, add moka
 </div>
diff --git a/src/categories/command-line-interface/ansi_terminal.md b/src/categories/command-line-interface/ansi_terminal.md
@@ -38,6 +38,7 @@ For anything more complex than plain foreground color changes, the code needs to
 
 {{#include refs.incl.md}}
 {{#include ../../refs/link-refs.md}}
+
 <div class="hidden">
-TODO:
+TODO: ansi_term is archived?
 </div>
diff --git a/src/categories/command-line-interface/arguments.md b/src/categories/command-line-interface/arguments.md
@@ -58,6 +58,4 @@ Your favorite number must be 256.
 {{#include ../../refs/link-refs.md}}
 
 <div class="hidden">
-TODO:
-
 </div>
diff --git a/src/categories/command-line-interface/index.md b/src/categories/command-line-interface/index.md
@@ -14,24 +14,15 @@ Techniques to help create command line interfaces{{hi:Command line interfaces}},
 
 [![tui][c-tui-badge]][c-tui]
 
+[ratatui][c-ratatui-github]⮳
+
 [![r3bl_tuify][c-r3bl_tuify-badge]][c-r3bl_tuify]  [![r3bl_tuify-crates.io][c-r3bl_tuify-crates.io-badge]][c-r3bl_tuify-crates.io]⮳  [![blog-tuify][blog-tuify-badge]][blog-tuify]⮳
 
+[Code][book-command-line-rust-github]⮳ for `Command-Line Rust` (O'Reilly, 2022, ISBN 9781098109417)
+
 {{#include refs.incl.md}}
 {{#include ../../refs/link-refs.md}}
 
 <div class="hidden">
-TODO:
-
-- [Command line apps in Rust][command-line-apps-in-rust]⮳
-- [Code for Command-Line Rust][command-line-rust]⮳ (O'Reilly, 2022, ISBN 9781098109417)
-
-[command-line-rust]: https://github.com/kyclark/command-line-rust/tree/main
-[command-line-apps-in-rust]: https://rust-cli.github.io/book/index.html#command-line-apps-in-rust
-
-## Ratatui
-
-- [ratatui][ratatui-github]⮳
-
-[ratatui-github]: https://github.com/ratatui-org/ratatui
-
+TODO: cover ratatui
 </div>
diff --git a/src/categories/command-line-utilities/index.md b/src/categories/command-line-utilities/index.md
@@ -55,6 +55,5 @@ apt install gping
 {{#include ../../refs/link-refs.md}}
 
 <div class="hidden">
-TODO:
-
+TODO: organize
 </div>
diff --git a/src/categories/compilers/cross_compilation.md b/src/categories/compilers/cross_compilation.md
@@ -31,6 +31,6 @@ Examples: [![cross-toml-example][c-cross-toml-example-badge]][c-cross-toml-examp
 
 {{#include refs.incl.md}}
 {{#include ../../refs/link-refs.md}}
+
 <div class="hidden">
-TODO:
 </div>
diff --git a/src/categories/compilers/faster_linking.md b/src/categories/compilers/faster_linking.md
@@ -60,6 +60,7 @@ rustflags = ["-C", "link-arg=-fuse-ld=/usr/bin/mold"]
 
 {{#include refs.incl.md}}
 {{#include ../../refs/link-refs.md}}
+
 <div class="hidden">
-TODO:
+TODO: review - some linkers are deprecated
 </div>
diff --git a/src/categories/compilers/index.md b/src/categories/compilers/index.md
@@ -14,11 +14,8 @@ Compiler{{hi:Compiler}} implementations, including interpreters{{hi:Interpreters
 
 {{#include reduce_compilation_duration.incl.md}}
 
-`cargo build`
-
 {{#include refs.incl.md}}
 {{#include ../../refs/link-refs.md}}
 
 <div class="hidden">
-TODO:
 </div>
diff --git a/src/categories/compilers/reduce_compilation_duration.md b/src/categories/compilers/reduce_compilation_duration.md
@@ -50,26 +50,27 @@ cargo build
 
 From-scratch builds with incremental compilation{{hi:Incremental compilation}} enabled adds about 15–20% overhead compared to disabled. The initial build needs to write out more intermediate state in order for later incremental builds to take advantage of it. In a CI{{hi:CI}} situation, it would be extremely unusual for there to be a later incremental build within the same job. The jobs are not making changes to source code and rebuilding. However, workflows that cache the target directory across runs might be benefiting from incremental compilation.
 
-## Reference
+### Incremental Computation
 
-[8 Solutions for Troubleshooting Your Rust Build Times][blog-rust-build-times]⮳
+### Salsa
 
-{{#include refs.incl.md}}
-{{#include ../../refs/link-refs.md}}
+[![salsa-github][c-salsa-github-badge]][c-salsa-github]  [![cat-development-tools][cat-development-tools-badge]][cat-development-tools]
 
-<div class="hidden">
-TODO:
+[Salsa][c-salsa-website]⮳
 
-## Salsa
+[Salsa (GitHub)][c-salsa-github]⮳ is a framework for on-demand, incremental computation.
 
-- [Salsa][salsa-website]⮳
+Salsa is a Rust framework for writing incremental, on-demand programs -- these are programs that want to adapt to changes in their inputs, continuously producing a new output that is up-to-date.
 
-## Rust compile duration
+## Reference
 
-- [how-i-improved-my-rust-compile-times-by-seventy-five-percent][how-i-improved-my-rust-compile-times-by-seventy-five-percent]⮳
-- [rust-compilation-time][rust-compilation-time]⮳
+- [8 Solutions for Troubleshooting Your Rust Build Times][blog-rust-build-times]⮳
+- [how-i-improved-my-rust-compile-times-by-seventy-five-percent][blog-how-i-improved-my-rust-compile-times-by-seventy-five-percent]⮳
+- [rust-compilation-time][blog-rust-compilation-time]⮳
 
-[salsa-website]: https://salsa-rs.github.io/salsa/overview.html
-[how-i-improved-my-rust-compile-times-by-seventy-five-percent]: https://benw.is/posts/how-i-improved-my-rust-compile-times-by-seventy-five-percent
-[rust-compilation-time]: https://www.williballenthin.com/post/rust-compilation-time/
+{{#include refs.incl.md}}
+{{#include ../../refs/link-refs.md}}
+
+<div class="hidden">
+TODO: fix reference section
 </div>
diff --git a/src/categories/compression/index.md b/src/categories/compression/index.md
@@ -6,6 +6,6 @@ Algorithms for making data smaller.
 
 {{#include refs.incl.md}}
 {{#include ../../refs/link-refs.md}}
+
 <div class="hidden">
-TODO:
 </div>
diff --git a/src/categories/compression/tar.md b/src/categories/compression/tar.md
@@ -38,6 +38,7 @@ Iterate over the [`tar::Archive::entries`][c-tar::Archive::entries]{{hi:tar::Arc
 
 {{#include refs.incl.md}}
 {{#include ../../refs/link-refs.md}}
+
 <div class="hidden">
-TODO:
+TODO: review
 </div>