Merge branch 'main' of github.com:propensive/escritoire

readme.md

@@ -17,9 +17,17 @@ typically for use in console applications.
 - compact display for tables which don't include multiline contents
 
 
-## Availability
+## Availability Plan
 
-Escritoire has not yet been published as a binary.
+Escritoire has not yet been published. The medium-term plan is to build Escritoire
+with [Fury](/propensive/fury) and to publish it as a source build on
+[Vent](/propensive/vent). This will enable ordinary users to write and build
+software which depends on Escritoire.
+
+Subsequently, Escritoire will also be made available as a binary in the Maven
+Central repository. This will enable users of other build tools to use it.
+
+For the overeager, curious and impatient, see [building](#building).
 
 ## Getting Started
 
@@ -79,6 +87,7 @@ will return and print a sequence of `Text`s as,
 
 
 
+
 ## Status
 
 Escritoire is classified as __maturescent__. For reference, Scala One projects are
@@ -90,26 +99,62 @@ categorized into one of the following five stability levels:
 - _dependable_: production-ready, subject to controlled ongoing maintenance and enhancement; tagged as version `1.0.0` or later
 - _adamantine_: proven, reliable and production-ready, with no further breaking changes ever anticipated
 
-Projects at any stability level, even _embryonic_ projects, are still ready to
-be used, but caution should be taken if there is a mismatch between the
-project's stability level and the importance of your own project.
+Projects at any stability level, even _embryonic_ projects, can still be used,
+as long as caution is taken to avoid a mismatch between the project's stability
+level and the required stability and maintainability of your own project.
 
 Escritoire is designed to be _small_. Its entire source code currently consists
 of 250 lines of code.
 
 ## Building
 
-Escritoire can be built on Linux or Mac OS with [Fury](/propensive/fury), however
-the approach to building is currently in a state of flux, and is likely to
-change.
+Escritoire will ultimately be built by Fury, when it is published. In the
+meantime, two possibilities are offered, however they are acknowledged to be
+fragile, inadequately tested, and unsuitable for anything more than
+experimentation. They are provided only for the necessity of providing _some_
+answer to the question, "how can I try Escritoire?".
+
+1. *Copy the sources into your own project*
+
+   Read the `fury` file in the repository root to understand Escritoire's build
+   structure, dependencies and source location; the file format should be short
+   and quite intuitive. Copy the sources into a source directory in your own
+   project, then repeat (recursively) for each of the dependencies.
+
+   The sources are compiled against the latest nightly release of Scala 3.
+   There should be no problem to compile the project together with all of its
+   dependencies in a single compilation.
+
+2. *Build with [Wrath](https://github.com/propensive/wrath/)*
+
+   Wrath is a bootstrapping script for building Escritoire and other projects in
+   the absence of a fully-featured build tool. It is designed to read the `fury`
+   file in the project directory, and produce a collection of JAR files which can
+   be added to a classpath, by compiling the project and all of its dependencies,
+   including the Scala compiler itself.
+
+   Download the latest version of
+   [`wrath`](https://github.com/propensive/wrath/releases/latest), make it
+   executable, and add it to your path, for example by copying it to
+   `/usr/local/bin/`.
+
+   Clone this repository inside an empty directory, so that the build can
+   safely make clones of repositories it depends on as _peers_ of `escritoire`.
+   Run `wrath -F` in the repository root. This will download and compile the
+   latest version of Scala, as well as all of Escritoire's dependencies.
+
+   If the build was successful, the compiled JAR files can be found in the
+   `.wrath/dist` directory.
 
 ## Contributing
 
-Contributors to Escritoire are welcome and encouraged. New contributors may like to look for issues marked
-<a href="https://github.com/propensive/escritoire/labels/beginner">beginner</a>.
+Contributors to Escritoire are welcome and encouraged. New contributors may like
+to look for issues marked
+[beginner](https://github.com/propensive/escritoire/labels/beginner).
 
-We suggest that all contributors read the [Contributing Guide](/contributing.md) to make the process of
-contributing to Escritoire easier.
+We suggest that all contributors read the [Contributing
+Guide](/contributing.md) to make the process of contributing to Escritoire
+easier.
 
 Please __do not__ contact project maintainers privately with questions unless
 there is a good reason to keep them private. While it can be tempting to
@@ -118,8 +163,9 @@ audience, and it can result in duplication of effort.
 
 ## Author
 
-Escritoire was designed and developed by Jon Pretty, and commercial support and training is available from
-[Propensive O&Uuml;](https://propensive.com/).
+Escritoire was designed and developed by Jon Pretty, and commercial support and
+training on all aspects of Scala 3 is available from [Propensive
+O&Uuml;](https://propensive.com/).
 
 
 
@@ -131,20 +177,23 @@ Escritoire is a pun: it is named after a type of writing table, since its purpos
 
 /ˌɛskɹiˈtwɑː/
 
-In general, Scala One project names are always chosen with some rationale, however it is usually
-frivolous. Each name is chosen for more for its _uniqueness_ and _intrigue_ than its concision or
-catchiness, and there is no bias towards names with positive or "nice" meanings—since many of the
-libraries perform some quite unpleasant tasks.
+In general, Scala One project names are always chosen with some rationale,
+however it is usually frivolous. Each name is chosen for more for its
+_uniqueness_ and _intrigue_ than its concision or catchiness, and there is no
+bias towards names with positive or "nice" meanings—since many of the libraries
+perform some quite unpleasant tasks.
 
-Names should be English words, though many are obscure or archaic, and it should be noted how
-willingly English adopts foreign words. Names are generally of Greek or Latin origin, and have
-often arrived in English via a romance language.
+Names should be English words, though many are obscure or archaic, and it
+should be noted how willingly English adopts foreign words. Names are generally
+of Greek or Latin origin, and have often arrived in English via a romance
+language.
 
 ## Logo
 
 The logo shows some stylized papers laid out on a green writing table, or _escritoire_.
 
 ## License
 
-Escritoire is copyright &copy; 2023 Jon Pretty & Propensive O&Uuml;, and is made available under the
-[Apache 2.0 License](/license.md).
+Escritoire is copyright &copy; 2024 Jon Pretty & Propensive O&Uuml;, and
+is made available under the [Apache 2.0 License](/license.md).
+

src/core/escritoire.scala

@@ -1,5 +1,5 @@
 /*
-    Escritoire, version [unreleased]. Copyright 2023 Jon Pretty, Propensive OÜ.
+    Escritoire, version [unreleased]. Copyright 2024 Jon Pretty, Propensive OÜ.
 
     The primary distribution site is: https://propensive.com/
 

src/test/tests.scala

@@ -1,5 +1,5 @@
 /*
-    Escritoire, version [unreleased]. Copyright 2023 Jon Pretty, Propensive OÜ.
+    Escritoire, version [unreleased]. Copyright 2024 Jon Pretty, Propensive OÜ.
 
     The primary distribution site is: https://propensive.com/