website: Move ttyshots to be side by side with markdown files.

Also rewrite the documentation.

website/.gitignore

@@ -1,7 +1,7 @@
-/home.html
-/*/*.html
-/ttyshot/**/*.raw
-!/ttyshot/**.html
+*.html
+!/template.html
+!*.ttyshot.html
+*.raw
 /tools/*.bin
 /_*
 /Elvish.docset

website/Makefile

@@ -29,9 +29,13 @@ check-rellinks: gen
 clean:
 	rm -rf tools/*.bin $(HTMLS) $(DST_DIR) $(DOCSET_TMP_DIR) $(DOCSET_DST_DIR)
 
-ttyshot/%.html:
-	@echo Exclude ttyshots from the pattern rule for %.html
-
+ifdef TTYSHOT
+%.ttyshot.html: %.ttyshot tools/ttyshot.bin
+	tools/ttyshot.bin -o $@ $<
+else
+%.ttyshot.html:
+	@: ttyshot generation disabled by default
+endif
 
 .PHONY: gen docset publish check-rellinks clean
 

website/README.md

@@ -34,6 +34,57 @@ Building the docset requires the following additional dependencies:
 
 -   SQLite3 CLI.
 
+To build the docset, run `make docset`. The generated docset is in
+`Elvish.docset`.
+
+# Ttyshots
+
+Some of the pages include "ttyshots" that show the content of Elvish sessions.
+They are HTML files with terminal attributes converted to CSS classes, generated
+from corresponding instruction files. By convention, the instruction files have
+names ending in `.ttyshot`, and the generated HTML files have names ending in
+`.ttyshot.html`.
+
+The generation process depends on [`tmux`](https://github.com/tmux/tmux) and a
+built `elvish` in `PATH`. Windows is not supported.
+
+## Instruction syntax
+
+Each line in a ttyshot instruction file is one of the following:
+
+-   `#prompt` instructs waiting for a new shell prompt.
+
+-   `#`_`command`_, where `command` is a string that does **not** start with a
+    space and is not `prompt`, is a command sent to `tmux`. The most useful one
+    (and only one being used now) is `send-keys`.
+
+-   Anything else is treated as text that should be sent directly to the Elvish
+    prompt.
+
+For example, the following instructions runs `cd /tmp`, waits for the next
+prompt, and sends Ctrl-N to trigger navigation mode:
+
+```
+cd /tmp
+#prompt
+#send-keys ctrl-L
+```
+
+## Generating ttyshots
+
+Unlike other generated website artifacts, generated ttyshots are committed into
+the repository, and the `Makefile` rule to generate them is disabled by default.
+This is because the process to generate ttyshots is relatively slow and may have
+network dependencies.
+
+To turn on ttyshot generation, pass `TTYSHOT=1` to `make`. For example, to
+generate a single ttyshot, run `make TTYSHOT=1 foo.ttyshot.html`. To build the
+website with ttyshot generation enabled, run `make TTYSHOT=1`.
+
+The first time you generate ttyshots, `make` will build the `ttyshot` tool, and
+regenerate all ttyshots. Subsequent runs will only regenerate ttyshots whose
+instruction files have changed.
+
 # Commit History
 
 These files used to live in a

website/cmd/macros/macros.go

@@ -11,7 +11,6 @@ import (
 	"log"
 	"os"
 	"os/exec"
-	"path"
 	"path/filepath"
 	"strings"
 )
@@ -107,7 +106,7 @@ func callElvdoc(out io.Writer, module, path string) {
 }
 
 func (f *filterer) expandTtyshot(name string) string {
-	content, err := os.ReadFile(path.Join("ttyshot", name+".html"))
+	content, err := os.ReadFile(name + ".ttyshot.html")
 	if err != nil {
 		log.Fatal(err)
 	}

website/home.md

@@ -27,7 +27,7 @@ Windows.
       </p>
     </div>
     <div class="demo-col demo-ttyshot">
-      @ttyshot pipelines
+      @ttyshot home/pipelines
     </div>
   </div> </div>
 
@@ -46,7 +46,7 @@ Windows.
       </p>
     </div>
     <div class="demo-col demo-ttyshot">
-      @ttyshot control-structures
+      @ttyshot home/control-structures
     </div>
   </div> </div>
 
@@ -65,7 +65,7 @@ Windows.
       </p>
     </div>
     <div class="demo-col demo-ttyshot">
-      @ttyshot location-mode
+      @ttyshot home/location-mode
     </div>
   </div> </div>
 
@@ -84,7 +84,7 @@ Windows.
       </p>
     </div>
     <div class="demo-col demo-ttyshot">
-      @ttyshot histlist-mode
+      @ttyshot home/histlist-mode
     </div>
   </div> </div>
 
@@ -103,7 +103,7 @@ Windows.
       </p>
     </div>
     <div class="demo-col demo-ttyshot">
-      @ttyshot navigation-mode
+      @ttyshot home/navigation-mode
     </div>
   </div> </div>
 </div> </div>

website/index.toml

@@ -7,8 +7,8 @@ rootURL = "https://elv.sh"
 
 [index]
 name = "home"
-extraCSS = ["home.css"]
-extraJS = ["home.js"]
+extraCSS = ["home/home.css"]
+extraJS = ["home/home.js"]
 
 [[categories]]
 name = "get"

website/learn/fundamentals.md

@@ -132,7 +132,7 @@ The command is short, but still, it can become a chore if you want to run it
 repeatedly. Fortunately, Elvish remembers all the commands you have typed; you
 can just ask Elvish to recall it by pressing <kbd>Up</kbd>:
 
-@ttyshot fundamentals/history-1
+@ttyshot learn/fundamentals/history-1
 
 This will give you the last command you have run. However, it may have been a
 while when you have last run the `randint` command, and this will not give you
@@ -140,7 +140,7 @@ what you need. You can either continue pressing <kbd>Up</kbd> until you find the
 command, or you can give Elvish a hint by typing some characters from the
 command line you want, e.g. `ra`, before pressing <kbd>Up</kbd>:
 
-@ttyshot fundamentals/history-2
+@ttyshot learn/fundamentals/history-2
 
 Another way to rerun commands is saving them in a **script**, which is simply a
 text file containing the commands you want to run. Using your favorite text

website/learn/tour.md

@@ -855,7 +855,7 @@ UI customization options.
 Press <kbd>Tab</kbd> to start completion. For example, after typing `vim` and
 <kbd>Space</kbd>, press <kbd>Tab</kbd> to complete filenames:
 
-@ttyshot tour/completion
+@ttyshot learn/tour/completion
 
 Basic operations should be quite intuitive:
 
@@ -873,7 +873,7 @@ You may have noticed that the cursor has moved to the right of "COMPLETING
 argument". This indicates that you can continue typing to filter candidates. For
 example, after typing `.md`, the UI looks like this:
 
-@ttyshot tour/completion-filter
+@ttyshot learn/tour/completion-filter
 
 Read the reference on [completion API](../ref/edit.html#completion-api) to learn
 how to program and customize tab completion.
@@ -887,7 +887,7 @@ Elvish has several UI features for working with command history.
 Press <kbd>▲</kbd> to fetch the last command. This is called **history walking**
 mode:
 
-@ttyshot tour/history-walk
+@ttyshot learn/tour/history-walk
 
 Press <kbd>▲</kbd> to go further back, <kbd>▼</kbd> to go forward, or
 <kbd>Escape</kbd> to cancel.
@@ -896,13 +896,13 @@ To restrict to commands that start with a prefix, simply type the prefix before
 pressing <kbd>▲</kbd>. For example, to walk through commands starting with
 `echo`, type `echo` before pressing <kbd>▲</kbd>:
 
-@ttyshot tour/history-walk-prefix
+@ttyshot learn/tour/history-walk-prefix
 
 ### History listing
 
 Press <kbd>Ctrl-R</kbd> to list the full command history:
 
-@ttyshot tour/history-list
+@ttyshot learn/tour/history-list
 
 Like in completion mode, type to filter the list, press <kbd>▲</kbd> and
 <kbd>▼</kbd> to navigate the list, <kbd>Enter</kbd> to insert the selected
@@ -913,7 +913,7 @@ entry, or <kbd>Escape</kbd> to cancel.
 Finally, Elvish has a **last command** mode dedicated to inserting parts of the
 last command. Press <kbd>Alt-,</kbd> to trigger it:
 
-@ttyshot tour/lastcmd
+@ttyshot learn/tour/lastcmd
 
 ## Directory history
 
@@ -922,17 +922,17 @@ list visited directories. Use <kbd>▲</kbd> and <kbd>▼</kbd> to navigate the
 list, <kbd>Enter</kbd> to change to that directory, or <kbd>Escape</kbd> to
 cancel.
 
-@ttyshot tour/location
+@ttyshot learn/tour/location
 
 Type to filter:
 
-@ttyshot tour/location-filter
+@ttyshot learn/tour/location-filter
 
 ## Navigation mode
 
 Press <kbd>Ctrl-N</kbd> to start the builtin filesystem navigator.
 
-@ttyshot tour/navigation
+@ttyshot learn/tour/navigation
 
 Unlike other modes, the cursor stays in the main buffer in navigation mode. This
 allows you to continue typing commands; while doing that, you can press
@@ -964,7 +964,7 @@ The left and right prompts can be customized by assigning functions to
 [`edit:rprompt`](../ref/edit.html#edit:rprompt). The following example defines
 prompts similar to the default, but uses fancy Unicode.
 
-@ttyshot tour/unicode-prompts
+@ttyshot learn/tour/unicode-prompts
 
 The [`tilde-abbr`](../ref/builtin.html#tilde-abbr) command abbreviates home
 directory to a tilde. The [`constantly`](../ref/builtin.html#constantly) command

website/tools/extra-deps

@@ -12,4 +12,4 @@ cat ${1%.html}.md |
   done
 
 cat ${1%.html}.md |
-  awk '$1 == "@ttyshot" { print "ttyshot/" $2 ".html" }'
+  awk '$1 == "@ttyshot" { print $2 ".ttyshot.html" }'

website/ttyshot/Makefile

@@ -1,14 +0,0 @@
-SPECS := $(shell find . -name '*.spec')
-HTMLS := $(SPECS:.spec=.html)
-
-all: $(HTMLS)
-
-%.html: %.spec ../tools/ttyshot.bin
-	../tools/ttyshot.bin -o $@ $<
-
-.PHONY: all
-
-.SECONDEXPANSION:
-
-../tools/ttyshot.bin: $$(wildcard ../cmd/ttyshot/*)
-	make -C .. tools/ttyshot.bin

website/ttyshot/README.md

@@ -1,94 +0,0 @@
-# What this directory contains
-
-This directory contains "ttyshots" that represent the final state of a set of
-Elvish interactive shell interactions. You will need to have the
-[`tmux`](https://github.com/tmux/tmux) command installed to create these images.
-The process for generating a ttyshot does not require a real terminal unless you
-want to examine the "raw" image. This means ttyshots can be generated in a CI/CD
-workflow using nothing more than the "spec" files.
-
-# How to create a ttyshot
-
-To create a ttyshot use the following procedure from the project root dir:
-
-1.  Create the ttyshot program: `make -C website tools/ttyshot.bin`
-
-1.  Create or modify a ttyshot specification (a ".spec" file) in the
-    `website/ttyshot` directory or subdirectory. See below for what can appear
-    in a ".spec" file.
-
-1.  Create the ttyshot; e.g.,
-    `website/tools/ttyshot.bin website/ttyshot/pipelines.spec`.
-
-1.  Review the results; e.g., `cat website/ttyshot/pipelines.raw`.
-
-1.  Add a `@ttyshot` directive to the appropriate document (e.g.,
-    `website/home.md` or `website/learn/fundamentals.md`) if adding a new
-    ttyshot.
-
-You can easily refresh all the ttyshots by running this:
-
-```
-for f [website/ttyshot/**.spec] { put $f; website/tools/ttyshot.bin $f }
-```
-
-# Content of a ttyshot specification
-
-A ttyshot specification consists of two types of lines: plain text to be sent to
-the Elvish shell as if a human had typed the text, and directives that begin
-with `//`. Empty lines are ignored. The available directives are:
-
--   `//prompt`: Wait for a new shell prompt. The process of converting a
-    sequence of commands to a ttyshot implicitly waits for the first prompt to
-    appear so don't begin your specification with this directive.
-
--   `//no-enter`: Disable the implicit Enter normally sent after each line of
-    plain text.
-
--   `//enter`: Enable an implicit Enter after each line of plain text and send
-    an Enter.
-
--   `//sleep d`: Pause for the specified duration in seconds. For example:
-    `//sleep 1`. No unit suffix should be present since only (fractional)
-    seconds are allowed. The use of this directive shouldn't be necessary. There
-    is an implicit sleep at the end of a ttyshot specification before capturing
-    the ttyshot image to give the Elvish shell time to stabilize its output;
-    e.g., when displaying a navigation view.
-
--   `//alt x`: Simulate an Alt sequence. That is, send an Escape followed by the
-    specified text.
-
--   `//ctrl n`: Send a Ctrl char version of `n`; e.g., `//ctrl L`.
-
--   `//tab`: Send a Tab; i.e., `//ctrl I`.
-
--   `//up`: Send an Up-arrow key sequence.
-
--   `//down`: Send an Down-arrow key sequence.
-
--   `//left`: Send an Left-arrow key sequence.
-
--   `//right`: Send an Right-arrow key sequence.
-
--   `//wait-for-str string`: Wait for the literal string `string` to appear in
-    the output.
-
--   `//wait-for-re regexp`: Wait for text matching the regexp to appear in the
-    output.
-
-## Example ttyshot specification
-
-The following specification simulates a user pressing Ctrl-N to enter navigation
-mode. Followed by Ctrl-F and the text `pkg` to select that directory. Followed
-by navigating into and out of that directory.
-
-```
-//no-enter
-//ctrl N
-//down
-//ctrl F
-pkg
-//right
-sys
-//right
-```