Move Rationale and Project Goals to man page.

2022-09-22 17:29:03 -04:00 · 2022-09-22 17:29:03 -04:00 · c9963d36b1
commit c9963d36b1
parent bbf8f26889
2 changed files with 92 additions and 106 deletions
--- a/docs/telodendria.7
+++ b/docs/telodendria.7
@ -68,6 +68,94 @@ Room;Description
 #telodendria-issues:bancino.net;Report bugs and issues.
 #telodendria-patches:bancino.net;Submit code patches to the project.
 .TE
 .Sh RATIONALE
 I want a lightweight Matrix homeserver designed specifically for OpenBSD,
 and other Unix-like operating systems. I want a homeserver that can be
 developed and compiled with built-in tools. I want it to function entirely
 on a base OS install without having to install any packages whatsoever. I've
 found that as far as these goals are concerned, the existing homeserver
 implementations fall short. This project aims to prove that Matrix homeservers
 can be lightweight and written in such a way that very few, if any, third-party
 libraries need to be pulled in.
 .sp
 I also want to learn how Matrix works, and I want to understand the code I'm
 running on my server, which is why I'm writing every component from scratch,
 even the HTTP server and router.
 .sp
 The advantage of using a flat-file database instead of a real database is that
 your data remains in a format that is incredibly easy to digest. Backups are
 incredibly easy as well\(emjust
 .Xr tar 1
 up the data directory and you're good to go.
 .Sh PROJECT GOALS
 The goals of this project are generally divided into user goals and developer
 goals, depending on who they impact the most. This isn't an exaustive list
 of
 .Nm 's
 goals, but it is a list of things that I want to prioritize, because other
 server implementations lack them.
 .sp
 The user goals are as follows:
 .Bl -bullet
 .It
 To implement the latest Matrix specification as fully and completely as possible.
 All features defined by the specification should eventually be present in
 .Nm .
 .It
 To be a production-ready Matrix server capable of handling a lot of users.
 .Nm
 should have good performance in many diverse environments. It should scale up
 well for large instances, such as the
 .Pa matrix.org
 instance, and yet also be able to scale down to an embedded or peer-to-peer
 device.
 .It
 To be easier to get up and running, and yet also be more configurable than other
 Matrix homeserver implementations. The configuration file should be flexible,
 well-documented, and easy to understand and modify. An intuitive command-line
 tool for administrative tasks should also be available.
 .El
 .sp
 The developer goals are as follows:
 .Bl -bullet
 .It
 To have as few build and runtime dependencies as possible. It should be possible
 to compile and run
 .Nm
 on any POSIX operating system right out of the box. 
 .Nm
 should be fully statically-linked, so it can run under a
 .Xr chroot 3 .
 Furthermore, it should be possible to read all the documentation offline, and
 without any overly complicated tools. You'll notice that this documentation is
 a collection of
 .Xr man 1
 pages, not HTML or Markdown, to remove the dependency on a browser or Markdown
 parser. Any Unix-like system has a manual page viewer, which makes the
 documentation more accessible, even on remote systems that have no graphical
 interface to read the documentation. This ensures that you can read the
 documentation for the installed version of
 .Nm
 without having to go online.
 .It
 To have a simple yet elegant workflow, and not depend on any large or complex
 development tools such as code forges. The entire development workflow should
 be able to be successfully and efficiently completed on a base OpenBSD install.
 Of course, you don't have to use OpenBSD for development, but the point is that
 the workflow should require fairly standardized and simple tools.
 .It
 To write clean, elegant, well-tested, and well-documented code. The goal is to build
 a Matrix homeserver from the ground up, not just because I don't like the way existing
 homeservers are implemented, but also because I want to learn how Matrix works,
 make it more accessible, and potentially teach others a little bit along the way.
 .It
 To foster a welcoming community. Many big communities such as Linux and OpenBSD
 have hostile leaders.
 .Nm
 shouldn't have a hostile leader. I want to be as understanding as I can, and talk
 through issues politely and in a civil manner. If I'm failing in this way, don't
 be afraid to call me out!
 .El
 .Sh SEE ALSO
 .Xr telodendria 8 ,
 .Xr telodendria.conf 5 ,
--- a/site/index.html
+++ b/site/index.html
@ -171,14 +171,14 @@ You can check out the change log <a href="#change-log">here</a>.
 <p>
 <b>Telodendria</b>'s documentation is distributed with the source
 code as <code>man</code> pages, which contain all of the information
-on how to build the source, configure it, as well as contribute to
+on what <b>Telodendria</b> is, what its goals are, how to build the source,
-the project. The <code>man</code> pages are also available online
+configure it, as well as contribute to the project. The <code>man</code>
-for convenience:
+pages are also available online for convenience:
 </p>
 <ul>
 <li><a href="telodendria.7.html">telodendria(7)</a> - Introduction</li>
 <li><a href="telodendria.8.html">telodendria(8)</a> - Command line</li>
-<li><a href="telodendria.conf.5.html">telodendria.conf(5)</a> - Configuration</li>
+<li><a href="telodendria.conf.5.html">telodendria.conf(5)</a> - Configuration file</li>
 <li><a href="td.8.html">td(8)</a> - Build script and patch instructions</li>
 </ul>
 <h2 id="project-status">Project Status</h2>
@ -358,108 +358,6 @@ on my list for that:
 </li>
 <li>Add other message <code>div</code>s for notes and warnings.</li>
 </ul>
 <h2 id="rationale">Rationale</h2>
 <p>
 I want a lightweight Matrix homeserver designed specifically for
 OpenBSD and other Unix-like operating systems. I want a homeserver
 that can be developed and compiled with built-in tools. I want it
 to function entirely on a base OS
 install without having to install any extra packages whatsoever.
 I've found that as far as these goals are concerned, the
 existing homeserver implementations fall short. This
 project aims to prove that Matrix homeservers can be lightweight and
 written in such a way that very few, if any, third-party libraries
 need to be pulled in.
 </p>
 <p>
 I also want to learn how Matrix works, and I want to understand the
 code I'm running on my server, which is why I'm writing every
 component from scratch, even the HTTP server.
 </p>
 Telodendria is written entirely in portable ANSI C. It depends on
 no third-party C libraries other than the standard POSIX C library.
 The only thing you need to run it is a reverse proxy with HTTPS support,
 such as <code>relayd(8)</code>, and a directory that data can be
 written to. Everything Telodendria needs to run itself is compiled
 into a single static binary, and the source code can be built
 anywhere, right out of the box. This makes it suitable for running
 in a <code>chroot(8)</code> environment.
 </p>
 <p>
 Telodendria doesn't use a database like all the other homeservers.
 Instead, it operates more like email: it uses a flat-file data
 structure similar to Maildir to store data. The advantage of this is
 that it saves server maintainers from also having to maintain a
 database.  It greatly simplifies the process of getting a Matrix
 homeserver up and running, and it makes it highly portable. It also is
 extremely easy to back up and restore with base tools; just
 <code>tar(1)</code> up the directory, and you're good to go.
 </p>
 <p>
 Telodendria is developed and tested on OpenBSD, but you'll find that it
 should just run on any POSIX operating system without modification.
 </p>
 <h2 id="project-goals">Project Goals</h2>
 <p>
 The goals of this project are generally divided into <i>user goals</i>,
 and <i>developer goals</i>, depending on who they impact the most. This
 isn't an exhaustive list, but it is a list of things that I want to
 prioritize, <i>because other server implementations lack them</i>.
 </p>
 <p>
 The user goals are as follows:
 </p>
 <ul>
 <li>
 To implement the latest Matrix specification as fully and completely as
 possible. All features should eventually be present in <b>Telodendria</b>.
 <li>
 To be a production-ready Matrix server capable of handling a lot of
 users. Telodendria should have good performance in many diverse
 environments. It should scale up well for large instances, and yet also
 be able to scale down to a peer-to-peer device.
 </li>
 <li>
 To be easier to configure than any of the other Matrix homeserver
 implementations. The configuration file should be flexible,
 well-documented, and easy to understand and modify. An intuitive
 command-line tool for administrative tasks should also be available.
 </li>
 </ul>
 <p>
 The developer goals are as follows:
 </p>
 <ul>
 <li>
 To have as few external build and run dependencies as possible. It
 should be possible to compile Telodendria on any POSIX operating
 system right out of the box, and have it be totally statically linked,
 ready to run under a <code>chroot(8)</code>. You'll even notice that
 the documentation is written in HTML directly, not Markdown, to remove
 the dependency on a Markdown parser and renderer.
 </li>
 <li>
 To have a simple yet elegant workflow, and not depend on any large
 or complex development tools, such as code forges. The entire
 development workflow should be able to be successfully and efficiently
 completed on a base OpenBSD install. Of course you don't have to use
 OpenBSD for development by any means, but the point is, the workflow
 should not require a lot of tools.
 <li>
 To be written in clean, elegant, well-tested, and well-documented
 code. The goal is to build a Matrix homeserver from the ground up, not
 just because I don't like the way existing homeservers are implemented,
 but also so I can learn how Matrix really works, and maybe even teach
 others along the way.
 </li>
 <li>
 To foster a welcoming community environment. Many of the big communities
 such as Linux and OpenBSD have fairly hostile leaders. <b>Telodendria</b>
 shouldn't have a hostile leader. I want to be as understanding as I can,
 and talk through issues politely and in a civil manner. If I'm failing
 in this way, don't be afraid to call me out!
 </li>
 </ul>
 <h2 id="getting-support">Getting Support</h2>
 <p>
 <b>Telodendria</b> is designed to be fairly straightforward, but that