LitBlock

Tags #literate #specifications #compositionality #litblock Repository: https://code.pandasportal.net/panda/litblock Version v0.1.2 Last Updated: 18-12-2025

The building blocks for find, extract and processing blocks of literate codeblock.

A litblock is a markdown codeblock that begins on the first character, and a literate token represented by «a label for the literate codeblock», which can be extracted using litblock "a label for the literate codeblock" <FILE>.

In order for the following codeblock to avoid hiding the literate token, it is recommended to write that the following codeblock is «list litblock» (using the U+00AB and U+00BB, with fcitx5 on linux, I type CTRL+SHIFT+U then type ab (to get «) or bb (to get »).

#!/usr/bin/env sh
LITBLOCK_SRC="$(pwd)/README.md"
./bin/litblock --list "$LITBLOCK_SRC"

Running litblock "list litblocks" should output:

«list litblocks»
«shell pipe example»

Another way to show a literate codeblock is to indent it four spaces.

```sh «list litblocks»
#!/usr/bin/env sh
LITBLOCK_SRC="$(pwd)/README.md"
./bin/litblock --list "$LITBLOCK_SRC"
```

Also it supports piped input, so cat README.md | litblock --list should also work.

Motivation

The story can be put together like a choose your own adventure, and exploring and documenting the ways of thinking in persuant to a goal, creating a documented context on what lead to said changes, implicitly capturing requirements.

The writing process aims to write well enough that the code and documentation can be weaved and composed like blocks. The idea to be able to work on complex systems, and have the context kept locally proximal to the source of truth, which is a specification that can self-assemble, and regenerate in different variations.

Donald Knuth pioneered this method of writing, and there is an idea, that literate writing could produce some of the agents/resources in the society of mind and emotion machine, and some of his writings on the Wayback machine, that challenges certain ways of viewing things, and how we update and extend our knoweldge, and providing the tools to make Minskys work easier to play with.

Some useful tools

The parallel program is quite useful as you can use shell functions, as follows:

#!/usr/bin/env sh

h3(){
	text="${1:-Missing Text}"
	cat <<-H3_TEMPLATE
	$(echo "$text" | sed 's/^/### /')
	$(echo )
	H3_TEMPLATE
}

p(){
	text="${1:-Missing Text}"
	cat <<-P_TEMPLATE
	$(echo "$text")
	$(echo )
	P_TEMPLATE
}
export -f h3
export -f p

body=$(
cat <<EOF
content 1
content 2
EOF
)

h3 "Header"
echo "$body" | parallel p

This is a terrible example but:

cat README.md | litblock "parallel example" | sh - | md2html

Outputs:

<h3>Header</h3>
<p>content 1</p>
<p>content 2</p>

Panda's Literate Markdown Spec

LitSpec Conventions

Representation of Literate Markdown

A non-literate block of a literate codeblocks in a non-literate context, such as in explanations, requires that the formatting is applied by common markdown renders and tools, also to allow nested examples, we will uses the 4 space indenting. A non-literate inclusion of a literate codeblock SHOULD BE indented with 4 spaces. Which should result in the following.

```sh  «add example of literate markdown»
litblock "add example of literate markdown" README.md
## Example of Literate Markdown Presentation
```

Features

Support shell and pipe operations

** Demo: Listing Command Pipelines**

This works for me, adjust to something for you.

#!/usr/bin/env sh
export LITBLOCK_PROJECT_PATH="${LITBLOCK_PROJECT_PATH:-$HOME/repos/litblock}"
export LITBLOCK_EXECUTABLE="${LITBLOCK_EXECUTABLE:-$LITBLOCK_PROJECT_PATH/bin/litblock}"

find_files(){
    search_path="${1:-$(pwd)}"
    fd --glob '*.md'  "$search_path"
}


list_blocks(){
    litblock_src="$1"
    printf '%s:\n%s\n' "$litblock_src" "$($LITBLOCK_EXECUTABLE --list "$litblock_src" | sed 's/^/  /g')"
}


export -f find_files
export -f list_blocks

parallel find_files {} ::: "$LITBLOCK_PROJECT_PATH" | parallel list_blocks {}