Merge pull request #25 from noncombatant/fix-typos
Fix some typos in the documentation.
diff --git a/README.md b/README.md
index 51cff6f..298cbf6 100644
--- a/README.md
+++ b/README.md
@@ -46,7 +46,7 @@
Wuffs is not a general purpose programming language. **It is for writing
libraries, not programs**. The idea isn't to write your whole program in Wuffs,
-only the **parts that are both performance-concious and security-concious**.
+only the **parts that are both performance-conscious and security-conscious**.
For example, while technically possible, it is unlikely that a Wuffs compiler
would be worth writing entirely in Wuffs.
@@ -221,4 +221,4 @@
---
-Updated on December 2019.
+Updated on December 2020.
diff --git a/doc/background.md b/doc/background.md
index 133c2bf..d4e341c 100644
--- a/doc/background.md
+++ b/doc/background.md
@@ -1,6 +1,6 @@
# Background
-Decoding untrusted data, such as images downloaded from across the web, have a
+Decoding untrusted data, such as images downloaded from across the web, has a
long history of security vulnerabilities. As of 2019, libpng is over 20 years
old, and the [PNG specification is dated 2003](https://www.w3.org/TR/PNG/), but
that well examined C library is still getting [CVE's published in
diff --git a/doc/getting-started.md b/doc/getting-started.md
index 857cf06..6e1e482 100644
--- a/doc/getting-started.md
+++ b/doc/getting-started.md
@@ -71,7 +71,7 @@
If your library change is an optimization, run `wuffs bench` or `wuffs bench
-mimic` both before and after your change to quantify the improvement. The
-mimic benchmark numbers should't change if you're only changing `.wuffs` code,
-but seeing zero change in those numbers is a sanity check on any unrelated
-system variance, such as software updates or virus checkers running in the
-background.
+mimic benchmark numbers shouldn't change if you're only changing `.wuffs`
+code, but seeing zero change in those numbers is a sanity check on any
+unrelated system variance, such as software updates or virus checkers running
+in the background.
diff --git a/doc/glossary.md b/doc/glossary.md
index 72355f9..33b9f3b 100644
--- a/doc/glossary.md
+++ b/doc/glossary.md
@@ -81,7 +81,7 @@
more conventionally, `a + (b * c)`. While good for brevity, Wuffs does not have
operator precedence: the bare `a + b * c` is an invalid Wuffs expression and
the parentheses must be explicit. The ambiguity (for the human) can be a source
-of bugs in other [security-concious file format
+of bugs in other [security-conscious file format
parsers](https://github.com/jbangert/nail/issues/7).
Some binary operators (`+`, `*`, `&`, `|`, `^`, `and`, `or`) are also
diff --git a/doc/note/bounds-checking.md b/doc/note/bounds-checking.md
index f4f9413..f086058 100644
--- a/doc/note/bounds-checking.md
+++ b/doc/note/bounds-checking.md
@@ -10,7 +10,7 @@
proof that `i` is in-bounds: that `((0 <= i) and (i < x.length()))`. Proofs can
involve natural bounds (e.g. if `i` has type `base.u8` then `(0 <= i)` is
trivially true since a `base.u8` is unsigned),
-[refinements](/doc/glossary.md#refinement-type) (e.g. if `i`has type
+[refinements](/doc/glossary.md#refinement-type) (e.g. if `i` has type
`base.u32[..= 100]` then 100 is an inclusive upper bound for `i`),
[facts](/doc/note/facts.md) (e.g. an explicit prior check `if i < x.length()`)
and [interval arithmetic](/doc/note/interval-arithmetic.md) (e.g. for an
diff --git a/doc/note/effects.md b/doc/note/effects.md
index 408ea53..ad9f623 100644
--- a/doc/note/effects.md
+++ b/doc/note/effects.md
@@ -11,7 +11,7 @@
Coroutines are similarly marked, with a `?`. Pure functions have no mark.
For those used to C/C++ syntax, in Wuffs, the unary not operator is spelled
-`not` instead of `!`, and Wuffs has no ternary operator like C/C++'s `?`.
+`not` instead of `!`, and Wuffs has no ternary operator like C/C++'s `?:`.
Sub-expressions in Wuffs must be pure. Only the outermost function call can
have a `!` or `?` mark. You can't write:
diff --git a/doc/note/facts.md b/doc/note/facts.md
index 65d8e9a..57fd2be 100644
--- a/doc/note/facts.md
+++ b/doc/note/facts.md
@@ -105,7 +105,7 @@
arms (e.g. those that end with a `break`, `continue` or `return` statement)
are not considered during reconciliation.
- The start of a while loop can come from not just its preceding line of code,
- but also from any explicit `continue`'s inside that loop, and the implicit
+ but also from any explicit `continue`s inside that loop, and the implicit
`continue` at the closing `}` curly brace.
- Similarly, the line of code immediately after the entire while loop can come
from an explicit `break` or if the while condition fails.
@@ -138,9 +138,9 @@
The `pre`, `post` and `inv` keywords introduce loop pre-conditions,
post-conditions and invariants (things that are both). The snippet above means
that the Wuffs compiler has to verify all three conditions at every place this
-loop exits: at the implicit `break` if the `n_Bits < n_extra_bits` evaluates
-false (which in this case trivially proves the third condition), but also at
-every explicit `break` for that loop within its body.
+loop exits: at the implicit `break` if the expression `n_bits < n_extra_bits`
+evaluates to false (which in this case trivially proves the third condition),
+but also at every explicit `break` for that loop within its body.
Similarly, it has to verify only the first two conditions at every place this
loop repeats (at its initial execution, at every explicit `continue` and at the
diff --git a/doc/note/initialization.md b/doc/note/initialization.md
index a2388f1..b126dde 100644
--- a/doc/note/initialization.md
+++ b/doc/note/initialization.md
@@ -5,7 +5,7 @@
Wuffs' C language form, the `initialize` function for the `foo` package's `bar`
struct is called `wuffs_foo__bar__initialize`. The function takes four
arguments (or, in C++, the `initialize` method takes three arguments, with the
-implicit `this` pointer argument);
+implicit `this` pointer argument):
- A pointer to the `wuffs_foo__bar` object: the `this` pointer.
- The size (in bytes) of that object. Conceptually, this is
diff --git a/doc/note/interval-arithmetic.md b/doc/note/interval-arithmetic.md
index 2eabe76..e6dbac8 100644
--- a/doc/note/interval-arithmetic.md
+++ b/doc/note/interval-arithmetic.md
@@ -48,11 +48,10 @@
i = i + 1
```
-fails the compile-time bounds / overflow checker, because the assignment's
-RHS's (Right Hand Side's) range, `[1 ..= 11]`, is not wholly contained by the
-LHS (Left Hand Side) variable's range: `i` has range `[0 ..= 10]`. If `i` had
-an unrefined type, such as `base.u32`, then this is essentially an overflow
-check.
+fails the compile-time bounds/overflow checker, because the assignment's RHS's
+(Right Hand Side's) range, `[1 ..= 11]`, is not wholly contained by the LHS
+(Left Hand Side) variable's range: `i` has range `[0 ..= 10]`. If `i` had an
+unrefined type, such as `base.u32`, then this is essentially an overflow check.
## Masking Array Indexes
diff --git a/doc/note/io-input-output.md b/doc/note/io-input-output.md
index 4bb711c..14eefb3 100644
--- a/doc/note/io-input-output.md
+++ b/doc/note/io-input-output.md
@@ -8,7 +8,7 @@
Instead, the code that calls into Wuffs libraries is responsible for
interfacing with e.g. the file system or the network system. An `io_buffer` is
the mechanism for transferring data into and out of Wuffs libraries. For
-example, when decompressing gzip, there are two `io_buffer`'s: the caller fills
+example, when decompressing gzip, there are two `io_buffer`s: the caller fills
a source buffer with e.g. the compressed file's contents and the callee (the
Wuffs library) reads compressed bytes from that source buffer and writes
decompressed bytes to a destination buffer.
@@ -35,19 +35,18 @@
An invariant condition is that `((0 <= ri) and (ri <= wi) and (wi <= len))`.
Having separate read and write indexes simplifies connecting a sequence of
-filters or processors with `io_buffer`'s, similar to connecting Unix processes
+filters or processors with `io_buffer`s, similar to connecting Unix processes
with pipes. Each filter reads from the previous buffer and writes to the next
buffer. Each buffer is written to by the previous filter and is read from by
the next filter. There's no need to flip a buffer between reading and writing
-modes. Nonetheless, `io_buffer`'s are generally not thread-safe.
+modes. Nonetheless, `io_buffer`s are generally not thread-safe.
-Continuing the "decompressing gzip" example, the application would write to the
-source buffer by copying from e.g. `/dev/stdin`. The Wuffs library would read
+Continuing the "decompressing gzip" example, the application would write to
+the source buffer by copying from e.g. `stdin`. The Wuffs library would read
from the source buffer and write to the destination buffer. The application
would read from the destination buffer by copying to e.g. `stdout`. Buffer
space can be re-used, via compaction (see below), so that neither the source
-(`/dev/stdin`) or destination (`/dev/stdout`) data needs to be entirely in
-memory at any point.
+or destination data needs to be entirely in memory at any point.
For example, an `io_buffer` of length 8 could have 4 bytes available to read
and 1 byte available to write. If 1 byte was written, there would then be 5
@@ -100,9 +99,9 @@
indexes can only travel forward, and it is up to the application code (not
Wuffs library) code to rewind the indexes (e.g. by compaction).
-Even though `ri` can not drop below its initial value, Wuffs code can still
+Even though `ri` cannot drop below its initial value, Wuffs code can still
read the contents of the slice before `ri` (in sub-slice notation,
-`data[0 .. ri]`) and it should still contain the `(pos + 0)`th, `(pos + 1)`th,
+`data[0 .. ri]`) and it should still contain the `(pos + 0)`th, `(pos + 1)`th,
etc. byte of the stream.
The contents of the slice after `wi` (in sub-slice notation, `data[wi .. len]`)
diff --git a/doc/note/iterate-loops.md b/doc/note/iterate-loops.md
index 1b62a97..a13d772 100644
--- a/doc/note/iterate-loops.md
+++ b/doc/note/iterate-loops.md
@@ -1,7 +1,7 @@
# Iterate Loops
-Iterate loops are syntactic sugar for partitioning a variable sized input slice
-into fixed sized chunk slices (with possible smaller-sized remainders).
+Iterate loops are syntactic sugar for partitioning a variable-sized input slice
+into fixed-sized chunk slices (with possible smaller-sized remainders).
Individual chunks' fixed sizes are typically easier for
[bounds-checking](/doc/note/bounds-checking.md).
diff --git a/doc/note/pixel-formats.md b/doc/note/pixel-formats.md
index 79e0051..bc6f26a 100644
--- a/doc/note/pixel-formats.md
+++ b/doc/note/pixel-formats.md
@@ -118,6 +118,6 @@
## API Stability
The `wuffs_base__pixel_format` bit packing is documented for explanation and to
-assist in debugging (e.g. `printf`'ing the bits in `%x` format). However, do
+assist in debugging (e.g. `printf`ing the bits in `%x` format). However, do
not manipulate its bits directly; they are private implementation details. Use
functions such as `wuffs_base__pixel_format__num_planes` instead.
diff --git a/doc/note/pixel-subsampling.md b/doc/note/pixel-subsampling.md
index 08f8ea2..18102e5 100644
--- a/doc/note/pixel-subsampling.md
+++ b/doc/note/pixel-subsampling.md
@@ -124,6 +124,6 @@
## API Stability
The `wuffs_base__pixel_subsampling` bit packing is documented for explanation
-and to assist in debugging (e.g. `printf`'ing the bits in `%x` format).
+and to assist in debugging (e.g. `printf`ing the bits in `%x` format).
However, do not manipulate its bits directly; they are private implementation
details. Use functions such as `wuffs_base__pixel_subsampling__bias_x` instead.
diff --git a/doc/note/quirks.md b/doc/note/quirks.md
index 6d08243..b18e486 100644
--- a/doc/note/quirks.md
+++ b/doc/note/quirks.md
@@ -15,7 +15,7 @@
for the outside pixels: opaque black, transparent black, or something else.
Wuffs, out of the box, makes particular choices (typically mimicking the de
-facto canonical implementation), but enabling various quirks result in
+facto canonical implementation), but enabling various quirks results in
different choices. In particular, quirks are useful in regression testing that
Wuffs and another implementation produce the same output for the same input,
even for malformed input.
diff --git a/doc/note/ranges-and-rects.md b/doc/note/ranges-and-rects.md
index faee45b..a506da3 100644
--- a/doc/note/ranges-and-rects.md
+++ b/doc/note/ranges-and-rects.md
@@ -1,7 +1,7 @@
# Ranges and Rects
Ranges are finite numerical intervals, e.g. "all integers `i` such that `(m <=
-i)` and `(i < n)`. The high end bound is sometimes exclusive, `(i < n)`, and
+i)` and `(i < n)`". The high end bound is sometimes exclusive, `(i < n)`, and
sometimes inclusive, `(i <= n)`.
In Wuffs syntax, similar to Rust syntax, the exclusive range is `m .. n` and
diff --git a/doc/note/slices-arrays-and-tables.md b/doc/note/slices-arrays-and-tables.md
index 0b5d92b..d66f07a 100644
--- a/doc/note/slices-arrays-and-tables.md
+++ b/doc/note/slices-arrays-and-tables.md
@@ -17,8 +17,8 @@
array-typed variable copies the elements. It has O(length) algorithmic
complexity.
-Both `s[i .. j]` and `a[i .. j]` refer to slices, ranging from the `i`'th
-element (inclusive) to the `j`'th element (exclusive). `i` can be omitted,
+Both `s[i .. j]` and `a[i .. j]` refer to slices, ranging from the `i`th
+element (inclusive) to the `j`th element (exclusive). `i` can be omitted,
implicitly equalling zero. `j` can be omitted, implicitly equalling the length.
For example, `s[.. 5]` contains the first five elements of `s`.
diff --git a/doc/note/statuses.md b/doc/note/statuses.md
index 252c787..cc20bcd 100644
--- a/doc/note/statuses.md
+++ b/doc/note/statuses.md
@@ -69,7 +69,7 @@
In terms of C implementation, a status' `repr` (representation) is just its
string message: a `const char *`, with `ok` being the null pointer. That C
-string is statically allocated and should never be `free`'d. Status `repr`s can
+string is statically allocated and should never be `free`d. Status `repr`s can
be compared by the `==` operator and not just by `strcmp`.
The C string's contents has the Wuffs package name inserted by the Wuffs
diff --git a/doc/related-work.md b/doc/related-work.md
index efe0797..b9727ad 100644
--- a/doc/related-work.md
+++ b/doc/related-work.md
@@ -47,7 +47,7 @@
Extended Static Checker for Java (ESC/Java) and its successor
[OpenJML](http://www.openjml.org/), which obviously target the Java programming
-language, similarly has to analyze a language that is more complicated that
+language, similarly has to analyze a language that is more complicated than
Wuffs. Java is also not commonly used for writing e.g. low level image codecs,
as the language lacks unsigned integer types, it is garbage collected and
idiomatic code often allocates.
@@ -211,7 +211,7 @@
grammar. In particular, it also handles entropy encodings such as LZW (for
GIF), ZLIB (for PNG) and Huffman (for JPEG, TODO). Wuffs differs from nom
combined with other Rust code (e.g. a Rust LZW implementation) in that bounds
-and overflow checks not just ubiquitous but also completely eliminated at
+and overflow checks are not just ubiquitous but also completely eliminated at
compile time.
[Kaitai Struct](http://kaitai.io/) is in a similar space, generating safe
diff --git a/doc/wuffs-the-library.md b/doc/wuffs-the-library.md
index b1b0514..8887f86 100644
--- a/doc/wuffs-the-library.md
+++ b/doc/wuffs-the-library.md
@@ -19,7 +19,7 @@
like using any other third party C library. It's just not hand-written C.
To do so, you need to download only one file, from the
-[`/release/c`](/release/c) directory. Wuffs the Library' C form ships as a
+[`/release/c`](/release/c) directory. Wuffs the Library's C form ships as a
[single file C
library](https://github.com/nothings/stb/blob/master/docs/stb_howto.txt),
targeting the C99 standard. That file acts as either a traditional `.c` or `.h`
