sequences protocol links (#240)

keiravillekode · web-flow · commit 048d18556ce7 · 2026-06-05T13:25:33.000+10:00
[no important files changed]
diff --git a/concepts/arrays/about.md b/concepts/arrays/about.md
@@ -13,7 +13,7 @@ the stack:
 | `<array>`| `( n elt -- array )` — `n` copies of `elt` |
 | `array?` | `( obj   -- ? )` — type predicate   |
 
-A few protocol words from `sequences` come up so often with
+A few [protocol][sequence-protocol] words from `sequences` come up so often with
 arrays that they are worth knowing as a unit:
 
 | word      | effect                                                |
@@ -39,3 +39,4 @@ sequence — handy when an array's elements should be deduplicated
 or checked for duplicates without first converting to a hash-set.
 
 [sets]: https://docs.factorcode.org/content/vocab-sets.html
+[sequence-protocol]: https://docs.factorcode.org/content/article-sequence-protocol.html
diff --git a/concepts/assocs/about.md b/concepts/assocs/about.md
@@ -1,6 +1,6 @@
 # About
 
-`assocs` is a protocol, not a single data type. Hashtables (`H{ }`),
+`assocs` is a [protocol][assoc-protocol], not a single data type. Hashtables (`H{ }`),
 association lists (sequences of `{ key value }` pairs), and tree
 maps all implement it, and most words on assocs are interchangeable
 between them.
@@ -29,3 +29,5 @@ but most exercise-level work involves a small set:
 
 `sort-keys` and `sort-values` (in `sorting`) sort an alist by the
 chosen field.
+
+[assoc-protocol]: https://docs.factorcode.org/content/article-assocs-protocol.html
diff --git a/concepts/assocs/introduction.md b/concepts/assocs/introduction.md
@@ -1,7 +1,7 @@
 # Introduction
 
 Factor's associative arrays — hashtables and friends — share a
-common protocol from [`assocs`][assocs]. The hashtable literal is
+common [protocol][assoc-protocol] from [`assocs`][assocs]. The hashtable literal is
 `H{ }`:
 
 ```factor
@@ -29,3 +29,4 @@ Hashtables are *mutable* — `clone` an `H{ }` literal before
 modifying so the literal isn't shared between calls.
 
 [assocs]: https://docs.factorcode.org/content/vocab-assocs.html
+[assoc-protocol]: https://docs.factorcode.org/content/article-assocs-protocol.html
diff --git a/concepts/concurrency/about.md b/concepts/concurrency/about.md
@@ -14,13 +14,13 @@ The standard concurrency primitives are layered:
 
 | Vocab                       | Provides                               |
 |-----------------------------|----------------------------------------|
-| `threads`                   | `spawn`, `yield`, thread identity      |
-| `concurrency.promises`      | `<promise>`, `fulfill`, `?promise`     |
-| `concurrency.locks`         | `<lock>`, `with-lock`                  |
-| `concurrency.combinators`   | `parallel-map`, `parallel-each`        |
-| `concurrency.semaphores`    | `<semaphore>`, `acquire`, `release`    |
-| `concurrency.mailboxes`     | per-thread inboxes, `send`, `receive`  |
-| `concurrency.channels`      | rendezvous handles, `to`, `from`       |
+| [`threads`][threads]                   | `spawn`, `yield`, thread identity      |
+| [`concurrency.promises`][concurrency.promises]      | `<promise>`, `fulfill`, `?promise`     |
+| [`concurrency.locks`][concurrency.locks]         | `<lock>`, `with-lock`                  |
+| [`concurrency.combinators`][concurrency.combinators]   | `parallel-map`, `parallel-each`        |
+| [`concurrency.semaphores`][concurrency.semaphores]    | `<semaphore>`, `acquire`, `release`    |
+| [`concurrency.mailboxes`][concurrency.mailboxes]     | per-thread inboxes, `send`, `receive`  |
+| [`concurrency.channels`][concurrency.channels]      | rendezvous handles, `to`, `from`       |
 
 ```factor
 USING: concurrency.combinators concurrency.locks
@@ -50,3 +50,11 @@ hashtable that more than one thread reads or writes. Treat both reads
 and writes as needing the lock if there's any non-atomic compound
 update; missing a lock on either side is the classic recipe for a
 torn read.
+
+[concurrency.channels]: https://docs.factorcode.org/content/vocab-concurrency.channels.html
+[concurrency.combinators]: https://docs.factorcode.org/content/vocab-concurrency.combinators.html
+[concurrency.locks]: https://docs.factorcode.org/content/vocab-concurrency.locks.html
+[concurrency.mailboxes]: https://docs.factorcode.org/content/vocab-concurrency.mailboxes.html
+[concurrency.promises]: https://docs.factorcode.org/content/vocab-concurrency.promises.html
+[concurrency.semaphores]: https://docs.factorcode.org/content/vocab-concurrency.semaphores.html
+[threads]: https://docs.factorcode.org/content/vocab-threads.html
diff --git a/concepts/deques/about.md b/concepts/deques/about.md
@@ -2,7 +2,7 @@
 
 `<dlist>` (in [`dlists`][dlists]) constructs a fresh doubly-linked
 list. The operations live in [`deques`][deques] and dispatch on
-the deque protocol, so other containers — chiefly `<dlist>` —
+the [deque protocol][deque-protocol], so other containers — chiefly `<dlist>` —
 can implement them.
 
 | word            | effect                              |
@@ -83,3 +83,4 @@ finite, manageable set.
 [dlists]: https://docs.factorcode.org/content/vocab-dlists.html
 [memoize]: https://docs.factorcode.org/content/vocab-memoize.html
 [memo-decl]: https://docs.factorcode.org/content/word-MEMO__colon__%2Csyntax.html
+[deque-protocol]: https://docs.factorcode.org/content/article-deques.html
diff --git a/concepts/hash-sets/about.md b/concepts/hash-sets/about.md
@@ -1,6 +1,6 @@
 # About
 
-Hash-sets implement the [`sets`][sets] protocol with hashing
+Hash-sets implement the [`sets`][sets] [protocol][set-protocol] with hashing
 under the hood, giving O(1) average insert, lookup, and delete.
 They're mutable in place, which makes them ideal for the
 *visited set* pattern in graph traversals.
@@ -64,3 +64,4 @@ reachability question, which is why a vector-as-stack is enough
 [dlist]: https://docs.factorcode.org/content/word-__lt__dlist__gt__%2Cdlists.html
 
 [sets]: https://docs.factorcode.org/content/vocab-sets.html
+[set-protocol]: https://docs.factorcode.org/content/article-sets.html
diff --git a/concepts/higher-order-sequences/about.md b/concepts/higher-order-sequences/about.md
@@ -48,10 +48,15 @@ Beyond the core sequence ops:
 
 | vocab              | provides                                      |
 |--------------------|-----------------------------------------------|
-| `sorting`          | `sort`, `sort-by`                             |
-| `math.statistics`  | `cum-sum`, `cum-product`, `cum-min`, `cum-max` |
-| `grouping`         | `group`, `clump`, `monotonic-split`           |
-| `sets`             | `members`, `all-unique?`                      |
+| [`sorting`][sorting]          | `sort`, `sort-by`                             |
+| [`math.statistics`][math.statistics]  | `cum-sum`, `cum-product`, `cum-min`, `cum-max` |
+| [`grouping`][grouping]         | `group`, `clump`, `monotonic-split`           |
+| [`sets`][sets]             | `members`, `all-unique?`                      |
 
 Pairs (`bi`, `tri`) and "n-ary" combinators (`2map`, `2each`, `zip`)
 extend the same pattern when the quotation needs more than one input.
+
+[grouping]: https://docs.factorcode.org/content/vocab-grouping.html
+[math.statistics]: https://docs.factorcode.org/content/vocab-math.statistics.html
+[sets]: https://docs.factorcode.org/content/vocab-sets.html
+[sorting]: https://docs.factorcode.org/content/vocab-sorting.html
diff --git a/concepts/io-streams/about.md b/concepts/io-streams/about.md
@@ -4,7 +4,7 @@ Factor splits stream I/O into two layers. The lower layer is the
 *explicit-stream* API: every word takes the stream as an
 argument. The upper layer is the *ambient-stream* API: short,
 one-line words that act on whichever stream is currently bound.
-Both layers sit on the same protocol — the upper-layer words
+Both layers sit on the same [protocol][stream-protocol] — the upper-layer words
 just look up the ambient stream and forward the call.
 
 ## Explicit-stream words
@@ -47,10 +47,10 @@ redirecting `print` to a string is just a matter of binding
 
 | word              | vocab                | what it builds                  |
 |-------------------|----------------------|---------------------------------|
-| `<string-reader>` | `io.streams.string`  | reads a literal string          |
-| `<string-writer>` | `io.streams.string`  | collects writes into a string   |
-| `<file-reader>`   | `io.files`           | reads a file with an encoding   |
-| `<file-writer>`   | `io.files`           | writes a file with an encoding  |
+| `<string-reader>` | [`io.streams.string`][io.streams.string]  | reads a literal string          |
+| `<string-writer>` | [`io.streams.string`][io.streams.string]  | collects writes into a string   |
+| `<file-reader>`   | [`io.files`][io.files]           | reads a file with an encoding   |
+| `<file-writer>`   | [`io.files`][io.files]           | writes a file with an encoding  |
 
 All four produce disposables — they extend `disposable` from
 `destructors`, so the `with-…` combinators below release them
@@ -98,6 +98,6 @@ For *implementing* a stream — defining your own class that
 plugs into the protocol — see the `streams` concept (taught in
 `telegraphers-tape`).
 
-[io]: https://docs.factorcode.org/content/vocab-io.html
 [io.streams.string]: https://docs.factorcode.org/content/vocab-io.streams.string.html
 [io.files]: https://docs.factorcode.org/content/vocab-io.files.html
+[stream-protocol]: https://docs.factorcode.org/content/article-stream-protocol.html
diff --git a/concepts/sequences/about.md b/concepts/sequences/about.md
@@ -1,7 +1,7 @@
 # About
 
-The [`sequences`][sequences] vocabulary defines a single protocol
-that arrays (`{ … }`), vectors (`V{ … }`), strings, ranges, and
+The [`sequences`][sequences] vocabulary defines a single
+[protocol][sequence-protocol] that arrays (`{ … }`), vectors (`V{ … }`), strings, ranges, and
 slices all implement. Anything you can do with one, you can do
 with the others.
 
@@ -63,3 +63,4 @@ V{ 1 2 3 } >array  .   ! => { 1 2 3 }
 ```
 
 [sequences]: https://docs.factorcode.org/content/vocab-sequences.html
+[sequence-protocol]: https://docs.factorcode.org/content/article-sequence-protocol.html
diff --git a/concepts/sequences/introduction.md b/concepts/sequences/introduction.md
@@ -1,8 +1,8 @@
 # Introduction
 
 Most data in Factor lives in *sequences*. Arrays (`{ … }`), vectors
-(`V{ … }`), and strings all share the same protocol from
-[`sequences`][sequences].
+(`V{ … }`), and strings all share the same [protocol][sequence-protocol]
+from [`sequences`][sequences].
 
 ```factor
 { 1 2 3 } length .    ! => 3
@@ -24,3 +24,4 @@ back from a generic operation.
 [arrays]: https://docs.factorcode.org/content/vocab-arrays.html
 
 [sequences]: https://docs.factorcode.org/content/vocab-sequences.html
+[sequence-protocol]: https://docs.factorcode.org/content/article-sequence-protocol.html
diff --git a/concepts/streams/about.md b/concepts/streams/about.md
@@ -1,6 +1,6 @@
 # About
 
-Factor's I/O is built on a single protocol that any data source
+Factor's I/O is built on a single [protocol][stream-protocol] that any data source
 or sink can implement. The bundled streams — `<file-reader>`,
 `<file-writer>`, `<string-reader>`, `<string-writer>`,
 network sockets, byte arrays, ttys — are all classes that
@@ -88,3 +88,4 @@ threading it through every call.
 
 [io]: https://docs.factorcode.org/content/vocab-io.html
 [destructors]: https://docs.factorcode.org/content/vocab-destructors.html
+[stream-protocol]: https://docs.factorcode.org/content/article-stream-protocol.html
diff --git a/concepts/streams/introduction.md b/concepts/streams/introduction.md
@@ -2,7 +2,7 @@
 
 A *stream* in Factor is anything you can read bytes from or write
 bytes to. Files, sockets, in-memory buffers, and your own custom
-wrappers all participate in the same small protocol from
+wrappers all participate in the same small [protocol][stream-protocol] from
 [`io`][io].
 
 The protocol's two halves are mixins: `input-stream` for things
@@ -65,3 +65,4 @@ USING: io io.streams.string ;
 
 [io]: https://docs.factorcode.org/content/vocab-io.html
 [destructors]: https://docs.factorcode.org/content/vocab-destructors.html
+[stream-protocol]: https://docs.factorcode.org/content/article-stream-protocol.html
diff --git a/concepts/strings/about.md b/concepts/strings/about.md
@@ -1,42 +1,49 @@
 # About
 
 A string in Factor is a sequence of characters and shares the full
-`sequences` protocol — `length`, `nth`, `head`, `tail`, `map`,
-`filter`, and so on — alongside its dedicated vocabularies.
+[`sequences` protocol][sequence-protocol] — `length`, `nth`, `head`,
+`tail`, `map`, `filter`, and so on — alongside its dedicated
+vocabularies.
 
 ```factor
 "hello"  length .       ! => 5
 "hello"  reverse .      ! => "olleh"
 "abcdef" 3 head .       ! => "abc"
 ```
 
-The string-specific words live mostly in `splitting`, `ascii`, and
-`unicode`:
+The string-specific words live mostly in [`splitting`][splitting],
+[`ascii`][ascii], and [`unicode`][unicode]:
 
 | word         | vocab         | what it does                          |
 |--------------|---------------|---------------------------------------|
-| `split1`     | `splitting`   | cut on the first occurrence           |
-| `split`      | `splitting`   | cut on any character in a set         |
-| `harvest`    | `sequences`   | drop empty pieces from a split result |
-| `replace`    | `sequences`   | substitute a substring                |
-| `surround`   | `sequences`   | wrap with a prefix and suffix         |
-| `glue`       | `sequences`   | join two strings with a separator     |
-| `join`       | `sequences`   | join an array of strings with a separator |
-| `>lower`     | `ascii`       | lowercase (ASCII)                     |
-| `>upper`     | `ascii`       | uppercase (ASCII)                     |
-| `[ blank? ] trim` | `sequences` | strip leading/trailing whitespace |
-| `first`, `second`, `third`, `fourth` | `sequences` | the leading slot |
-| `first2`, `first3`         | `sequences`   | unpack two or three leading slots |
-| `>string`    | `strings`     | turn a sequence of chars into a string |
-| `1string`    | `strings`     | wrap a single character into a one-character string |
+| `split1`     | [`splitting`][splitting]   | cut on the first occurrence           |
+| `split`      | [`splitting`][splitting]   | cut on any character in a set         |
+| `harvest`    | [`sequences`][sequences]   | drop empty pieces from a split result |
+| `replace`    | [`sequences`][sequences]   | substitute a substring                |
+| `surround`   | [`sequences`][sequences]   | wrap with a prefix and suffix         |
+| `glue`       | [`sequences`][sequences]   | join two strings with a separator     |
+| `join`       | [`sequences`][sequences]   | join an array of strings with a separator |
+| `>lower`     | [`ascii`][ascii]       | lowercase (ASCII)                     |
+| `>upper`     | [`ascii`][ascii]       | uppercase (ASCII)                     |
+| `[ blank? ] trim` | [`sequences`][sequences] | strip leading/trailing whitespace |
+| `first`, `second`, `third`, `fourth` | [`sequences`][sequences] | the leading slot |
+| `first2`, `first3`         | [`sequences`][sequences]   | unpack two or three leading slots |
+| `>string`    | [`strings`][strings]     | turn a sequence of chars into a string |
+| `1string`    | [`strings`][strings]     | wrap a single character into a one-character string |
 | `CHAR: x`    | parser        | a single-character literal (e.g. `CHAR: A` → `65`) |
 
 For numeric ↔ string round-tripping, [`math.parser`][math.parser]
 provides `number>string` and `string>number`. For format-string
 output, [`formatting`][formatting] provides `sprintf` and friends.
 
 For Unicode-aware case conversion or character classification, use
-the corresponding words in `unicode`.
+the corresponding words in [`unicode`][unicode].
 
 [math.parser]: https://docs.factorcode.org/content/vocab-math.parser.html
 [formatting]: https://docs.factorcode.org/content/vocab-formatting.html
+[sequence-protocol]: https://docs.factorcode.org/content/article-sequence-protocol.html
+[splitting]: https://docs.factorcode.org/content/vocab-splitting.html
+[sequences]: https://docs.factorcode.org/content/vocab-sequences.html
+[ascii]: https://docs.factorcode.org/content/vocab-ascii.html
+[strings]: https://docs.factorcode.org/content/vocab-strings.html
+[unicode]: https://docs.factorcode.org/content/vocab-unicode.html
diff --git a/concepts/wire-format/about.md b/concepts/wire-format/about.md
@@ -39,7 +39,7 @@ the text back, and the wrong tool for human-readable output.
 | `tail-slice*` | `( seq n -- slice )` — view of last n           |
 
 A `slice` is a tuple holding a from-index, to-index, and the
-underlying sequence — it implements the sequence protocol so any
+underlying sequence — it implements the [sequence protocol][sequence-protocol] so any
 sequence operation works on it. Reach for the slice variants when
 you'd otherwise allocate just to read; reach for the copying ones
 when you need to keep the data after the underlying sequence
@@ -76,3 +76,4 @@ For *one* quotation applied to each input separately, reach for
 different shape.
 
 [unparse]: https://docs.factorcode.org/content/word-unparse%2Cprettyprint.html
+[sequence-protocol]: https://docs.factorcode.org/content/article-sequence-protocol.html
diff --git a/exercises/concept/channel-chatter/.docs/introduction.md b/exercises/concept/channel-chatter/.docs/introduction.md
@@ -2,7 +2,7 @@
 
 Factor's I/O is built on *streams* — objects you read bytes or
 characters from, or write them to. The [`io`][io] vocabulary
-gives you two views of the same protocol.
+gives you two views of the same [protocol][stream-protocol].
 
 ## The two views
 
@@ -78,3 +78,4 @@ disposed on exit even if the quotation throws.
 
 [io]: https://docs.factorcode.org/content/vocab-io.html
 [boatswains-bilge]: https://exercism.org/tracks/factor/exercises/boatswains-bilge
+[stream-protocol]: https://docs.factorcode.org/content/article-stream-protocol.html
diff --git a/exercises/concept/lighthouse-logbook/.docs/introduction.md b/exercises/concept/lighthouse-logbook/.docs/introduction.md
@@ -3,7 +3,7 @@
 Hash-sets are mutable, unordered collections that store each
 value at most once. Lookup, insert, and delete are all O(1)
 average. They live in [`hash-sets`][hash-sets] and implement the
-[`sets`][sets] protocol.
+[`sets`][sets] [protocol][set-protocol].
 
 ## Hash-set literals
 
@@ -86,3 +86,4 @@ outwards.
 
 [hash-sets]: https://docs.factorcode.org/content/vocab-hash-sets.html
 [sets]: https://docs.factorcode.org/content/vocab-sets.html
+[set-protocol]: https://docs.factorcode.org/content/article-sets.html
diff --git a/exercises/concept/signalers-satchel/.docs/introduction.md b/exercises/concept/signalers-satchel/.docs/introduction.md
@@ -29,7 +29,7 @@ quotes, vectors keep their `V{ ... }`, etc.).
 `head` and `tail` from `sequences` *copy* the part you keep into
 a fresh sequence. Their `-slice` counterparts return a `slice`
 object — a tuple holding from-index, to-index, and the
-underlying sequence — that implements the sequence protocol
+underlying sequence — that implements the [sequence protocol][sequence-protocol]
 without copying:
 
 | word          | effect                                          |
@@ -149,3 +149,4 @@ USING: combinators math ;
 [unparse]: https://docs.factorcode.org/content/word-unparse%2Cprettyprint.html
 [repetition]: https://docs.factorcode.org/content/word-__lt__repetition__gt__%2Csequences.html
 [clumps]: https://docs.factorcode.org/content/word-__lt__clumps__gt__%2Cgrouping.html
+[sequence-protocol]: https://docs.factorcode.org/content/article-sequence-protocol.html
diff --git a/exercises/concept/telegraphers-tape/.docs/introduction.md b/exercises/concept/telegraphers-tape/.docs/introduction.md
@@ -2,7 +2,7 @@
 
 You've already *used* streams in `channel-chatter` and disposed
 of them in `boatswains-bilge`. This exercise is your first
-custom stream — a class that implements the protocol so the
+custom stream — a class that implements the [protocol][stream-protocol] so the
 same `with-input-stream` / `read1` / `stream-read1` code that
 worked on a `<string-reader>` works on yours.
 
@@ -77,3 +77,4 @@ Once that's in place, all the `with-…` combinators from
 `channel-chatter` work on your stream automatically.
 
 [io]: https://docs.factorcode.org/content/vocab-io.html
+[stream-protocol]: https://docs.factorcode.org/content/article-stream-protocol.html
