Commita0d75771Recorded19 Nov 2026Repositoryshale
Link the site to Shale's public repository
Message
Add the clone command and Source links now that the repository is public, and say that the build needs Sigil 0.24.11, which isn't released yet. The invocation check now requires JSON to end in exactly one newline. The manual is more precise about leading whitespace and about when a command cut off by a closed pipe counts as a failure.
Changed
packages/shale-site/README.md | 9 +++++----
packages/shale-site/manual/guides/commands.sgd | 4 ++--
packages/shale-site/manual/guides/jobs.sgd | 9 ++++++---
packages/shale-site/manual/guides/outside-the-prompt.sgd | 4 ++--
packages/shale-site/manual/start/getting-started.sgd | 16 +++++++++++-----
packages/shale-site/src/shale/site/checks.sgl | 8 ++++++--
packages/shale-site/src/shale/site/pages.sgl | 39 ++++++++++++++++++++++++---------------
7 files changed, 56 insertions(+), 33 deletions(-)Diff
packages/shale-site/README.mdmodified
@@ -49,10 +49,11 @@ when one disagrees. Each kind of example is checked to a different depth:
49
that each setting has the effect the page describes. 50
- `@invocation` listings run each `shale` command line shown, in a fresh 51
example home, and compare its whole output with the page. JSON must be−52
exactly one value on one line and is compared as data, ignoring only−53
`duration`. The `cwd` field is compared after the example home is mapped−54
to the page's `/home/ada`. A command must exit 0 unless the listing−55
shows its status with an `echo $?` line, which must match.+52
exactly one value on one line, followed by exactly one newline, and is+53
compared as data, ignoring only `duration`. The `cwd` field is compared+54
after the example home is mapped to the page's `/home/ada`. A command+55
must exit 0 unless the listing shows its status with an `echo $?` line,+56
which must match. 57
- `@prompt-example` headings are drawn by Shale's own prompt code from 58
the values the page gives. A heading passed in as text, for a custom 59
prompt, is drawn but not computed by Shale.packages/shale-site/manual/guides/commands.sgdmodified
@@ -11,8 +11,8 @@
11
@section["How Shale reads a line" id: "commands"] 12
13
@p{−14
Shale decides what a line is from its first character that isn't a−15
space:+14
Shale decides what a line is from its first character that isn't+15
whitespace, such as a space or a tab: 16
} 17
18
@itemspackages/shale-site/manual/guides/jobs.sgdmodified
@@ -89,9 +89,12 @@ grep: exited 1 (0.004s)
89
A pipeline fails when any of its commands fails, and it reports the status 90
of the first command that failed, counting from the left. That's close to 91
Bash with @code{pipefail} set, which reports the last failure instead.−92
One exception: a command that stops because a later command closed the−93
pipe early, like @code{yes} in @code{yes | head -n 1}, doesn't count as a−94
failure when the commands after it succeed.+92
One exception: a command that stops because the command reading its+93
output finished first, like @code{yes} in @code{yes | head -n 1}, doesn't+94
count as a failure when that reader succeeded. Only the reader decides+95
this: in @code{yes | head -n 1 | sh -c 'cat >/dev/null; exit 7'}, @code{yes}+96
doesn't count, and the pipeline fails with status 7, from the last+97
command. 98
} 99
100
@session[cwd: "~/project"]{packages/shale-site/manual/guides/outside-the-prompt.sgdmodified
@@ -100,8 +100,8 @@ $ shale --json -e 'grep milk notes.txt | wc -l'
100
is @code{exited} for a command that ran to the end; others 101
include @code{signaled}, @code{spawn-failed} when a program couldn't 102
start, and @code{refused} when Shale wouldn't run the line. In a−103
stage, @code{closed-early} marks a command that stopped because a−104
later command closed the pipe.}+103
stage, @code{closed-early} marks a command that stopped because the+104
command reading its output finished first and succeeded.} 105
@end row 106
@row 107
@cell{@code{stdout}, @code{stderr}}packages/shale-site/manual/start/getting-started.sgdmodified
@@ -2,8 +2,8 @@
2
3
@(import (shale site author) 4
;; SPDX-License-Identifier: GPL-3.0-or-later−5
;; TODO(release): add a clone command to "Build Shale" when the−6
;; repository has a public remote.+5
;; TODO(release): drop the note that Sigil 0.24.11 isn't released once+6
;; it is, the same as required-sigil in (shale site pages). 7
;; TODO(try-it 3): ls gains color on a terminal. Transcripts run without 8
;; one, so they stay plain; check the prose under the ls example. 9
)@@ -13,12 +13,18 @@
13
@section["Build Shale" id: "install"] 14
15
@p{−16
Shale builds from source with Sigil. You need Sigil, a C compiler and a−17
checkout of Shale's source. Change to the checkout's top directory, then−18
install the dependencies and build:+16
Shale builds from source with Sigil. You need Sigil 0.24.11 and a C+17
compiler. Sigil 0.24.11 isn't released yet, so these steps won't work until+18
it is. Until then, @url["https://git.usesigil.org/shale/repos/shale/"]{the+19
source} is there to read and follow along.+20
}+21
+22
@p{+23
Get the source, then install the dependencies and build: 24
} 25
26
@code["console"]{+27
$ git clone https://git.usesigil.org/sigil/shale.git 28
$ cd shale 29
$ sigil deps install 30
$ sigil build --config releasepackages/shale-site/src/shale/site/checks.sglmodified
@@ -359,9 +359,13 @@
359
(fail id "an invocation must run shale" command)) 360
(let* ((result (run-shale fixture (path-join home "project") (cdr words) "")) 361
(status (car result))−362
(actual (trim-trailing-newlines (page-path (cdr result) home))))+362
(output (page-path (cdr result) home))+363
(actual (trim-trailing-newlines output)))+364
;; JSON is one line ending in exactly one newline, so it's+365
;; compared before trailing newlines are trimmed. 366
(unless (if (string-starts-with? expected "{")−364
(same-json? expected actual)+367
(and (string=? output (str actual "\n"))+368
(same-json? expected actual)) 369
(string=? (stable expected) (stable actual))) 370
(fail id "an invocation prints something else" 371
(str "\n$ " command "\n--- page ---\n" expected "\n--- shale ---\n" actual "\n")))packages/shale-site/src/shale/site/pages.sglmodified
@@ -9,14 +9,18 @@
9
(shale site policy) 10
(shale site source) 11
(shale site terminal))−12
(export site-pages site-url site-head site-header site-footer+12
(export site-pages site-url source-url clone-url site-head site-header site-footer 13
site-transcripts) 14
(begin 15
(define site-url "https://shaleshell.org/")−16
;; TODO(release): Shale's repository has no public remote yet. When it−17
;; has one, add a Source link to the header and footer, a clone command−18
;; to both install sections, and point license-url at its COPYING.−19
(define license-url "https://www.gnu.org/licenses/gpl-3.0.html")+16
(define source-url "https://git.usesigil.org/shale/repos/shale/")+17
(define clone-url "https://git.usesigil.org/sigil/shale.git")+18
(define license-url (string-append source-url "blob/COPYING/"))+19
+20
;; The Sigil release Shale's build needs. It isn't published yet, so the+21
;; install text says so. TODO(release): once Shale's package requires+22
;; this version, read it from the package again and drop the warning.+23
(define required-sigil "0.24.11") 24
25
(define description 26
"Shale is an interactive shell written in Sigil. Command lines work the way they do in Bash and fish, and a line that starts with a parenthesis is Sigil.")@@ -60,7 +64,8 @@
64
(a (@ (class "home") (href ,home)) ,(lockup prefix)) 65
(nav (@ (class "site-nav") (aria-label "Site")) 66
,(item "manual" (if (string=? prefix "") "/manual/" "/manual/") 'manual)−63
,(item "install" (str home "#install") 'install)))))+67
,(item "install" (str home "#install") 'install)+68
,(item "source" source-url 'source))))) 69
70
(define (badge prefix) 71
`(a (@ (class "badge") (href "https://usesigil.org/"))@@ -75,7 +80,8 @@
80
(div (@ (class "wrap")) 81
(div (h2 "Shale") 82
(ul (li (a (@ (href ,(str home "manual/"))) "Manual"))−78
(li (a (@ (href ,(str home "#install"))) "Install"))))+83
(li (a (@ (href ,(str home "#install"))) "Install"))+84
(li (a (@ (href ,source-url)) "Source")))) 85
(div (h2 "Sigil") 86
(ul (li (a (@ (href "https://usesigil.org/")) "usesigil.org")) 87
(li (a (@ (href "https://orielbrowser.com/")) "Oriel"))@@ -137,8 +143,7 @@ util.sgl
143
(p ,@body))) 144
145
(define (landing)−140
(let ((version (shale-package-field "version"))−141
(sigil (shale-package-field "sigil")))+146
(let ((version (shale-package-field "version"))) 147
`((a (@ (class "skip") (href "#main")) "Skip to content") 148
,(site-header "" "/" 'home) 149
(main (@ (id "main"))@@ -192,16 +197,20 @@ util.sgl
197
(h2 (@ (class "rule") (id "install-title")) "Install") 198
(div (@ (class "split")) 199
(div−195
(p (@ (class "slab-title")) "build from a checkout")+200
(p (@ (class "slab-title")) "build from source") 201
(pre (@ (class "slab") (tabindex "0"))−197
(code (span (@ (class "pm")) "$") " cd shale\n"+202
(code (span (@ (class "pm")) "$") " git clone " ,clone-url "\n"+203
(span (@ (class "pm")) "$") " cd shale\n" 204
(span (@ (class "pm")) "$") " sigil deps install\n" 205
(span (@ (class "pm")) "$") " sigil build --config release\n" 206
(span (@ (class "pm")) "$") " build/release/bin/shale"))−201
(p "Run these from a checkout of Shale's source, with "+207
(p "Shale needs " 208
(a (@ (href "https://usesigil.org/")) "Sigil")−203
,(str " " sigil " installed. ")−204
"Try Shale in a terminal you already have open; "+209
,(str " " required-sigil ", which isn't released yet, so these steps "+210
"won't work until it is. Until then, ")+211
(a (@ (href ,source-url)) "the source")+212
" is there to read and follow along.")+213
(p "Once it's built, try Shale in a terminal you already have open; " 214
(a (@ (href "/manual/")) "the manual") " starts from there.")) 215
(div (@ (class "table-scroll") (tabindex "0") (role "region") 216
(aria-labelledby "platforms-caption"))@@ -210,7 +219,7 @@ util.sgl
219
(thead (tr (th (@ (scope "col")) "System") (th (@ (scope "col")) "Architecture") 220
(th (@ (scope "col")) "Status"))) 221
(tbody−213
(tr (td "Linux") (td "x86_64") (td (@ (class "ok")) "builds and runs"))+222
(tr (td "Linux") (td "x86_64") (td (@ (class "ok")) "supported")) 223
(tr (td "Linux") (td "aarch64") (td (@ (class "dim")) "not yet tested")) 224
(tr (td "macOS") (td "arm64") (td (@ (class "dim")) "not yet supported"))))))))) 225
,(site-footer "" "/"))))