From e9fdc383002a3749c9e69a06b910ccc29b0d83d7 Mon Sep 17 00:00:00 2001 From: Chris Palmer Date: Fri, 3 Jan 2020 11:03:38 -0800 Subject: [PATCH] Fix some typos in the documentation. And some minor clean-ups. There should be no semantic changes to the documentation in this patch. --- README.md | 4 ++-- doc/background.md | 2 +- doc/getting-started.md | 8 ++++---- doc/glossary.md | 2 +- doc/note/bounds-checking.md | 2 +- doc/note/effects.md | 2 +- doc/note/facts.md | 8 ++++---- doc/note/initialization.md | 2 +- doc/note/interval-arithmetic.md | 9 ++++----- doc/note/io-input-output.md | 17 ++++++++--------- doc/note/iterate-loops.md | 4 ++-- doc/note/pixel-formats.md | 2 +- doc/note/pixel-subsampling.md | 2 +- doc/note/quirks.md | 2 +- doc/note/ranges-and-rects.md | 2 +- doc/note/slices-arrays-and-tables.md | 4 ++-- doc/note/statuses.md | 2 +- doc/related-work.md | 4 ++-- doc/wuffs-the-library.md | 2 +- 19 files changed, 39 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 51cff6f2..298cbf67 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,7 @@ prove that `y` is not zero. 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 @@ owned by Google. --- -Updated on December 2019. +Updated on December 2020. diff --git a/doc/background.md b/doc/background.md index 133c2bf2..d4e341c1 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 857cf069..6e1e4829 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -71,7 +71,7 @@ libpng for PNG, etc. 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 72355f9d..33b9f3b7 100644 --- a/doc/glossary.md +++ b/doc/glossary.md @@ -81,7 +81,7 @@ unambiguous (for the computer), equivalent to exactly one of `(a + b) * c` or, 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 f4f94136..f0860589 100644 --- a/doc/note/bounds-checking.md +++ b/doc/note/bounds-checking.md @@ -10,7 +10,7 @@ Similarly, an expression like `x[i]` is invalid unless there is a compile-time 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 408ea539..ad9f6236 100644 --- a/doc/note/effects.md +++ b/doc/note/effects.md @@ -11,7 +11,7 @@ Impure functions are marked with a `!` at their definition and at call sites. 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 65d8e9af..57fd2be2 100644 --- a/doc/note/facts.md +++ b/doc/note/facts.md @@ -105,7 +105,7 @@ line of code: 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 @@ while n_bits < n_extra_bits, 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 a2388f1b..b126dde8 100644 --- a/doc/note/initialization.md +++ b/doc/note/initialization.md @@ -5,7 +5,7 @@ Outside of the Wuffs base package, every Wuffs struct has an implicit 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 2eabe76f..e6dbac85 100644 --- a/doc/note/interval-arithmetic.md +++ b/doc/note/interval-arithmetic.md @@ -48,11 +48,10 @@ etcetera 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 4bb711ce..14eefb30 100644 --- a/doc/note/io-input-output.md +++ b/doc/note/io-input-output.md @@ -8,7 +8,7 @@ prove that you can't misuse a capability, even when given malicious input. 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 @@ Reading from an `io_buffer`, e.g. copying from a buffer to a file, increments 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 @@ at the time of the call. When considering a function as a 'black box', the two 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 1b62a97a..a13d7721 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 79e0051b..bc6f26a7 100644 --- a/doc/note/pixel-formats.md +++ b/doc/note/pixel-formats.md @@ -118,6 +118,6 @@ Guide](https://afrantzis.github.io/pixel-format-guide/). ## 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 08f8ea2f..18102e50 100644 --- a/doc/note/pixel-subsampling.md +++ b/doc/note/pixel-subsampling.md @@ -124,6 +124,6 @@ Cb, Cr) and a `denominator_y` of 1, 1 and 1. The `uint32_t` encoding is ## 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 6d08243f..b18e4865 100644 --- a/doc/note/quirks.md +++ b/doc/note/quirks.md @@ -15,7 +15,7 @@ entire image, and different implementations choose a different default color 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 faee45ba..a506da3f 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 0b5d92bd..d66f07ac 100644 --- a/doc/note/slices-arrays-and-tables.md +++ b/doc/note/slices-arrays-and-tables.md @@ -17,8 +17,8 @@ copy the elements. It has O(1) algorithmic complexity. Assigning to an 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 f7e2b59e..9216aeb8 100644 --- a/doc/note/statuses.md +++ b/doc/note/statuses.md @@ -69,7 +69,7 @@ receiver"` is an error and `"$short read"` is a suspension: In terms of C implementation, a status value 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 values can be compared by the +allocated and should never be `free`d. Status values 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 efe07972..b9727ad7 100644 --- a/doc/related-work.md +++ b/doc/related-work.md @@ -47,7 +47,7 @@ domain-specific programming language. 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 @@ limited to that part of a file format that is easily expressible as a formal 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 b1b0514c..8887f862 100644 --- a/doc/wuffs-the-library.md +++ b/doc/wuffs-the-library.md @@ -19,7 +19,7 @@ also checked into the repository. Using the standard library's C form would be 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`