9 files changed, 62 insertions(+), 29 deletions(-)

M extlib.rst
M faq.rst
M install/bootstrap.rst
M install/editors.rst
M usage/assembly-sources.rst
M usage/debugging.rst
M usage/documentation.rst
M usage/modules.rst
M usage/style.rst

@@ 2,7 2,7 @@ Hare extended libraries
 =======================
 
 The Hare extended libraries are a set of libraries which supplement the
-standard library. These are:
+standard library. Extended libraries...
 
 * Are considered important to the Hare ecosystem
 * Are subject to upstream policies and processes

@@ 32,8 32,8 @@ directly call C functions from Hare and vice-versa. C programmers should find
 Hare a simple, intuitive upgrade from using C.
 
 **Go**: Hare shares some features with Go, such as defer and a similar standard
-library design. However, the language design is much different: Hare does not
-use a garbage collector, lacks support for generics, and has a more
+library design. However, the language design differs in many respects: Hare
+does not use a garbage collector, lacks support for generics, and has a more
 comprehensive type system and error handling support compared to Go. Hare also
 lacks Go's concurrency features and userspace scheduler, which, depending on
 your perspective, is either a drawback or an advantage. Many Go users who are


@@ 55,10 55,10 @@ they share some features and design, such as defer and built-in tests. Hare
 lacks comptime, generics, or other forms of metaprogramming. Hare's approach to
 error handling and tagged unions are more generalized and flexible than Zig's
 approach, allowing you to add more context to errors as necessary. Hare's
-standard library is more comprehensive than Zig, and has comparatively better
-support for string operations, date/time arithmetic, regular expressions, and
-so on. Subjectively, Hare's syntax is also somewhat easier on the eyes and more
-approachable for C programmers.
+standard library more comprehensively supports features a C user may expect,
+such as regex, comparatively improved string operations, date/time arithmetic,
+and so on; whereas Zig's standard library has more support for higher-level or
+novel features like HTTP and TLS.
 
 Why qbe instead of LLVM?
 ------------------------

@@ 17,7 17,7 @@ Hare depends on the following:
 
 * A POSIX-compatible environment with a C11 compiler
 * `QBE <https://c9x.me/compile/>`_ (compiler backend)
-* `scdoc <https://sr.ht/~sircmpwn/scdoc>`_ (man pages)
+* `scdoc <https://sr.ht/~sircmpwn/scdoc>`_ (man pages -- optional)
 
 Consult the upstream documentation for details regarding the installation of
 dependencies.

@@ 11,7 11,6 @@ Editor plugins
 * Sublime: `hare-highlight <https://github.com/artursartamonovs/hare-highlight>`_
 * VS Code (TmLanguage): `hare-highlighing-vscode <https://github.com/aDotInTheVoid/hare-highlighing-vscode>`_
 * Vim: `hare.vim <https://git.sr.ht/~sircmpwn/hare.vim>`_ [#upstream]_; see also `vim-haredoc <https://git.sr.ht/~torresjrjr/vim-haredoc>`_
-* Vis: `hare.lua <https://git.d2evs.net/~ecs/hare.lua>`_ [#upstream]_
 
 .. note::
    For those writing a plugin for their own text editor, please note that Hare's


@@ 22,7 21,7 @@ Tree sitter
 -----------
 
 A tree sitter grammar for Hare is `available here
-<https://git.d2evs.net/~ecs/tree-sitter-hare>`_.
+<https://git.sr.ht/~ecs/tree-sitter-hare>`_.
 
 Language server
 ---------------

@@ 46,11 46,20 @@ Assembled as one unit
 ---------------------
 
 Assembly sources are passed to the assembler in one go, such that a module with
-``a.s`` and ``b.s`` will be compiled with a single ``as a.s b.s`` command. With
-many assemblers (including the GNU binutils assembler), the input files are
-essentially concatenated, preserving some state between files. As such, you
-will generally want to begin each file with the segment it belongs in, using
-directives like ``.text`` or ``.bss``.
+``a.s`` and ``b.s`` will be compiled with a single ``as a.s b.s`` command. The
+same assembler invocation will also include all of the compiled Hare sources.
+With many assemblers (including the GNU binutils assembler), the input files
+are essentially concatenated, preserving some state between files. As such, you
+should begin each file with the segment it belongs in, using directives like
+``.text`` or ``.bss``.
+
+Unused symbol pruning
+~~~~~~~~~~~~~~~~~~~~~
+
+Hare instructs the linker to prune unused symbols to reduce binary sizes. In
+order to do this, each symbol must be in its own ELF section. If you want your
+assembly code to be pruned when unused in practice, add ``.section
+.text.$symname`` or similar rather than using ``.text`` et al as shorthand.
 
 Application binary interface
 ----------------------------

@@ 22,16 22,18 @@ Getting information about type details and locals is not supported.
 Runtime errors
 --------------
 
-The following error cases are detected by the Hare runtime. If debug builds are
-enabled, a stack trace is shown when an error is detected.
+The following error cases are detected by the Hare runtime. For programs built
+in debug mode, a stack trace is shown when an error is detected.
 
 * Buffer overflows/out-of-bounds read or write
-* Double free
-* Heap corruption [#besteffort]_
-* Out of memory errors
+* Heap corruption
+
+  * Invalid/double free
+  * Use-after free [#besteffort]_
+
+* Out of memory errors [#overcommit]_
 * Type assertion failures
 * Unhandled errors
-* Use-after free [#besteffort]_
 * Errors reported by signals, such as: [#debugonly]_
 
   * Arithmetic errors (e.g. divide by zero)


@@ 50,6 52,8 @@ enabled, a stack trace is shown when an error is detected.
 
 .. [#besteffort] Handled on a best-effort basis. It is not always possible for
    the runtime to detect these errors.
+.. [#overcommit] On systems with overcommit (such as Linux), this may not work
+   as you expect.
 .. [#debugonly] Only detected by the runtime in debug mode. In release mode
    these errors are handled by the operating system's default signal handler.
 


@@ 220,6 224,13 @@ Recommended solutions
 * If better suited to your use-case, switch to dynamically allocated slices
   (i.e. drop the **static** keyword).
 
+.. warning::
+   Hare will not automatically move stack- or statically-allocated slices to
+   the heap when they are passed to **append** et al; attempting to do so will
+   crash your program with a memory error. You must either heap-allocate the
+   slice from the start, or allocate a copy of the original slice, if you want
+   to change to heap-allocated slices.
+
 .. raw:: html
 
    <a id="fa-3"></a>

@@ 26,6 26,7 @@ write a comment directly above the declaration, like so:
    // This is an example function.
    export fn example() void = {
            // ...
+   };
 
 Hare documentation uses a very simple markup format, with the following
 features:


@@ 42,6 43,10 @@ To reference other Hare symbols, wrap them in two square brackets, like so:
    // See also [[os::exit]]
    export fn example() void = {
            // ...
+   };
+
+You can reference entire modules with ``[[module::]]``, using a trailing
+namespace separator (``::``).
 
 Bulleted lists
 ~~~~~~~~~~~~~~


@@ 60,6 65,7 @@ line, like so:
    // It has three items.
    export fn example() void = {
            // ...
+   };
 
 Code samples
 ~~~~~~~~~~~~


@@ 77,9 83,11 @@ least two whitespace characters, or at least one tab character:
    // It is simply indented from the body of the comment.
    export fn example() void = {
            // ...
+   };
 
 README
 ~~~~~~
 
-You may include a file at in your module directory named "README" which uses
-the same documentation markup format to provide an introduction to your module.
+You may include a file in your module directory named "README" to provide an
+introduction to your module, using the same markup format as documentation
+comments.

@@ 5,9 5,9 @@ Hare modules are implicitly defined by the directory structure of your projects.
 For instance, when importing ``foo::bar``, this becomes ``foo/bar/``, which is
 appended to each element of the search path to find the source files.
 
-The search path always starts with the current working directory, then consult
-the default search paths built into the build driver. You can list the built-in
-search paths with ``hare version -v``. Conventionally, these include:
+The search path always starts with the current working directory, then checks
+each of the default search paths in order. You can list the default search
+paths with ``hare version -v``. Conventionally, these include:
 
 - ``/usr/src/hare/third-party``
 - ``/usr/src/hare/stdlib``


@@ 17,6 17,12 @@ Your local installation may differ.
 You can override the search paths by exporting the ``HAREPATH`` environment
 variable, set to a list of paths separated by colons (``:``).
 
+.. warning::
+   If the HAREPATH environment variable is set, the default search paths are
+   not used at all. If you want to **add** search paths, rather than replacing
+   the entire search path, make sure your HAREPATH includes the default paths
+   as well as your additions.
+
 Vendoring
 ---------
 

@@ 305,14 305,14 @@ Tuple types
    MUST be used.
 2. A tuple type MUST NOT place a space after ``(`` or before ``)``.
 3. In the single-line style, a tuple type MUST NOT place a space before each
-   ``,``, and MUST place a space after each `,`, except for the last, which
+   ``,``, and MUST place a space after each ``,``, except for the last, which
    MUST be omitted.
 4. In the multi-line style, a tuple type MUST NOT place a space before each
-   ``,``, and MUST place a space after each `,`, except for the last, which
+   ``,``, and MUST place a space after each ``,``, except for the last, which
    MUST NOT be omitted.
 5. (*subjective*) In the multi-line style, the programmer MAY use their
    discretion to distribute the member types to achieve "balance".
-6. When breaking to a new line, place the `,` on the first line. Place the
+6. When breaking to a new line, place the ``,`` on the first line. Place the
    final ``)`` token on the same line as the final members.
 
 .. code-block:: hare