Merge branch 'rdme'

CONTRIBUTING

@@ -1,26 +1,29 @@
 Make sure to read our code of conduct in the CONDUCT file.
 
-When contributing a pull request to the main branch, please sign your commits
+
-with a PGP key and add your name and the year to the bottom of the list of
+Copyright Information
-copyright holders for the file. For example, an existing copyright header might
+=====================
-read:
+
+When editing a file, create a copyright statement correlated to your
+identity so that it is easier to keep track of who has touched what file.
+Pseudonymous contributions are welcome (and encouraged). Place new copyright
+information below existing copyright information. If there is an existing
+copyright statement:
 
  * Copyright (c) 2022–2023 Emma Tebibyte <emma@tebibyte.media>
 
-You would add your name below it like this:
+you would add your name below it like this:
 
  * Copyright (c) 2022–2023 Emma Tebibyte <emma@tebibyte.media>
  * Copyright (c) 20XX Your Name <your e-mail address or website>
 
-We accept contributions from people using aliases.
-
 Only list years in which you modified the source file. For example:
 
  * Copyright (c) 2020–2021, 2023 Your Name <your-address@example.com>
 
 This header shows that “Your Name” worked on this source file in 2020, 2021, and
-2023. Please use the en dash (“–”) to separate the years in the copyright
+2023. Please use the en dash (“–”, U+2013) to separate consecutive years in the
-notice.
+copyright notice.
 
 If you are contributing a new file, please prepend the following license header
 text to it, replacing the proper text on the copyright line:
@@ -92,6 +95,10 @@ notice:
  *     USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+
+Style
+=====
+
 Make sure lines never exceed 80 columns in width when using four-character
 indentation steps. This helps contributors with smaller screens, those using
 side-by-side editor windows or panes, and those who have no text wrapping in
@@ -104,8 +111,13 @@ style guide for the usage text’s output format [0].
 If committing a new utility, please include tests and documentation (see
 tests/ and docs/) for the new tool.
 
-If committing a new source file, format the commit message following these
+Committing
-guidelines:
+==========
+
+When contributing to Bonsai, please sign your commit with a PGP key and create
+the commit with an identity which can be easily contacted.
+
+Format commit messages following these guidelines:
 
 $ git commit -m 'tool(1): add feature x'
 
@@ -131,7 +143,13 @@ $ git commit -m 'tool(1): fix #42 & add feature x'
 
 Commit messages should be written in the present tense.
 
+
+References
+==========
+
 [0] <http://cvsweb.netbsd.org/bsdweb.cgi/~checkout~/src/share/misc/style>
+
+
 --
 This work © 2023–2024 by Emma Tebibyte is licensed under CC BY-SA 4.0. To view a
 copy of this license, visit <http://creativecommons.org/licenses/by-sa/4.0/>

README

@@ -1,24 +1,28 @@
 “Seek not to walk the path of the masters; seek what they sought.”
 – Matsuo Basho
 
-The Bonsai harakit utilities are a replacement for standard POSIX utilities
+Bonsai’s Harakit is an alternative to the standard POSIX utilities that aims to
-which aim to fill its niche while expanding on their capabilities. These new
+be simpler, easier, and more powerful. These tools are the result of careful
-tools are the result of the careful examination of the current state of POSIX
+examination of the current state common Unix utilities, POSIX-compliant and
-and Unix utilies. The Unix Philosophy of “do one thing and do it well” are their
+otherwise, following frustrations with design decisions and implementation
-core but they avoid clinging to the past.
+details. They represent a vision of accomplishing everyday use cases with tools
+that follow the Unix philosophy of “do one thing and do it well” without
+clinging to the past.
 
-The era of the original Unix tools has been long and fruitful, but they have
+The intent of Harakit is not to conform to or extend POSIX, like the GNU or BSD
-their flaws. This project originated from frustrations with the way certain
+utilities do, but to invent new utilities to perform the same tasks in more
-tools work and how other projects that extend POSIX don’t make anything better.
+intuitive ways. GNU and BSD extensions are convenient but often unhealthy,
-
+forgetting the purposes of the tools they extend, or building into existing
-This project will not follow in the footsteps of GNU; extensions of POSIX will
+utilities features that would be more useful as their own tools to be used
-not be found here. GNU extensions are a gateway to the misuse of the shell. The
+anywhere. Other utility sets aim to provide a number of fully-featured
-harakit utilities will intentionally discourage use of the shell for purposes
+programs to be used individually, Harakit utilities are meant to be easily
-beyond its scope.
+composable and work together in pipelines.
 
 See docs/ for more on the specific utilities currently implemented.
 
+
 Building
+========
 
 Harakit utilities require a POSIX-compliant environment to compile, including a
 C compiler and preprocessor (cc(1) and cpp(1) by default), an edition 2023 Rust
@@ -43,7 +47,22 @@ To remove all build and distributable files:
 
 $ make clean
 
+
+Contributing
+============
+
+See the CONTRIBUTING file for contribution guidelines.
+
+
+Community
+=========
+
+xmpp://bonsai@covenant.murderu.us
+irc://feeling.murderu.us/#bonsai
+
+
 Read More
+=========
 
 An Introduction to the Unix Shell
 <https://porkmail.org/era/unix/shell>
@@ -57,6 +76,10 @@ Master Foo Discourses on the Unix-Nature
 Shell Programming!
 <https://tldp.org/LDP/abs/html/why-shell.html>
 
+UNIX Style, or cat -v Considered Harmful
+<http://harmful.cat-v.org/cat-v/>
+
+
 --
 Copyright © 2023–2024 Emma Tebibyte <emma@tebibyte.media>
 Copyright © 2024 DTB <trinity@trinity.moe>