Move man pages into a proper man directory

TODO.txt

@@ -75,7 +75,6 @@ Phase 4:
 [ ] Create an OpenBSD package and get it submitted to ports
 [ ] Add relayd examples to contrib/
 [ ] Create a command line tool to manage Telodendria
-	[ ] Configuration file generation
 	[ ] User management
 	[ ] Room management
 [ ] Migrate from Synapse or Dendrite, whichever is more mainstream by the time we get here
@@ -100,7 +99,24 @@ Documentation
 [x] Convert documentation to man pages
 	[x] Clean up dark mode in man page CSS (links)
 	[x] Synopsis table should not be styled
-	[ ] Internal API docs
+	[x] Make available on MANPATH in tools/env.sh
+	[~] Internal API docs
+		[x] Array
+		[x] Base64
+		[ ] CanonicalJson
+		[ ] Config
+		[ ] Constants
+		[ ] HashMap
+		[ ] Http
+		[ ] HttpServer
+		[ ] Json
+		[ ] Log
+		[ ] Matrix
+		[ ] NonPosix
+		[ ] Queue
+		[ ] Routes
+		[ ] TelodendriaConfig
+		[ ] Util
 
 [ ] Add onboarding documentation
 	[ ] Building from source

man/.cvsignore

@@ -0,0 +1 @@
+mandoc.db

man/man3/Array.3

@@ -0,0 +1,114 @@
+.Dd $Mdocdate: September 30 2022 $
+.Dt ARRAY 3
+.Os Telodendria Project
+.Sh NAME
+.Nm Array
+.Nd A simple dynamic array data structure.
+.Sh SYNOPSIS
+.In Array.h
+.Ft Array *
+.Fn ArrayCreate "void"
+.Ft void
+.Fn ArrayFree "Array *"
+.Ft int
+.Fn ArrayTrim "Array *"
+.Ft size_t
+.Fn ArraySize "Array *"
+.Ft void *
+.Fn ArrayGet "Array *" "size_t"
+.Ft int
+.Fn ArrayInsert "Array *" "void *" "size_t"
+.Ft int
+.Fn ArrayAdd "Array *" "void *"
+.Ft void *
+.Fn ArrayDelete "Array *" "size_t"
+.Ft void
+.Fn ArraySort "Array *" "int (*) (void *, void *)"
+.Sh DESCRIPTION
+These functions implement a simple array data structure that
+is automatically resized as necessary when new values are added.
+This implementation does not actually store the values of the
+items in it; it only stores pointers to the data. As such, you will
+still have to manually maintain all your data. The advantage of this
+is that these functions don't have to copy data, and thus don't care
+how big the data is. Furthermore, arbitrary data can be stored in the
+array.
+.Pp
+This array implementation is optimized for storage space and appending.
+Deletions are expensive in that all the items of the list above a deletion
+are moved down to fill the hole where the deletion occurred. Insertions are
+also expensive in that all the elements above the given index must be shifted
+up to make room for the new element.
+.Pp
+Due to these design choices, this array implementation is best suited to
+linear writing, and then linear or random reading.
+.Pp
+These functions operate on an array structure which is opaque to the
+caller.
+.Pp
+.Fn ArrayCreate
+and
+.Fn ArrayFree
+allocate and deallocate an array, respectively.
+Note that
+.Fn ArrayFree
+does not free any of the values stored in the array; it is the caller's
+job to manage the memory for each item. Typically, the caller would
+iterate over all the items in the array and free them before freeing
+the array.
+.Fn ArrayTrim
+reduces the amount of unused memory by calling
+.Xr realloc 3
+on the internal structure to perfectly fit the elements in the array. It
+is intended to be used by functions that return relatively read-only arrays
+that will be long-lived.
+.Pp
+.Fn ArrayInsert
+and
+.Fn ArrayDelete
+are the main functions used to modify the array.
+.Fn ArrayAdd
+is a convenience method that simply appends a value to the end of the
+array. It uses
+.Fn ArrayInsert .
+The array can also be sorted by using
+.Fn ArraySort ,
+which takes a pointer to a function that compares elements. The function
+should take two
+.Dv void
+pointers as parameters, and return an integer. The return value indicates
+to the algorithm how the elements relate to each other. A return value of
+0 indicates the elements are identical. A return value greater than 0
+indicates that the first item is "bigger" than the second item and should
+thus appear after it in the array, and a value less than zero indicates
+the opposite: the second element should appear after the first in the array.
+.Pp
+.Fn ArrayGet
+is used to get the element at the specified index.
+.Sh RETURN VALUES
+.Fn ArrayCreate
+returns a pointer on the heap to a newly allocated array structure, or
+.Dv NULL
+if the allocation fails.
+.Pp
+.Fn ArrayGet
+and
+.Fn ArrayDelete
+return pointers to values that were put into the array, or
+.Dv NULL
+if the provided array is
+.Dv NULL
+or the provided index was out of bounds.
+.Fn ArrayDelete
+returns the element at the specified index after removing it so that
+it can be properly handled by the caller.
+.Pp
+.Fn ArrayTrim ,
+.Fn ArrayInsert ,
+and
+.Fn ArrayAdd
+return a boolean value indicating their status. They return a value of zero
+on failure, and a non-zero value on success.
+.Sh SEE ALSO
+.Xr HashMap 3 ,
+.Xr Queue 3

man/man3/Base64.3

@@ -0,0 +1,81 @@
+.Dd $Mdocdate: September 30 2022 $
+.Dt BASE64 3
+.Os Telodendria Project
+.Sh NAME
+.Nm Base64
+.Nd A simple base64 encoder/decoder with "unpadded base64" support.
+.Sh SYNOPSIS
+.In Base64.h
+.Ft size_t
+.Fn Base64EncodedSize "size_t"
+.Ft size_t
+.Fn Base64DecodedSize "const char *" "size_t"
+.Ft char *
+.Fn Base64Encode "const char *" "size_t"
+.Ft char *
+.Fn Base64Decode "const char *" "size_t"
+.Ft void
+.Fn Base64Unpad "char *" "size_t"
+.Ft int
+.Fn Base64Pad "char **" "size_t"
+.Sh DESCRIPTION
+This is an efficient yet simple base64 encoding and decoding
+library that supports regular base64, as well as the Matrix
+specification's extension to base64, called "unpadded base64."
+.Nm provides the ability to convert between the two, instead of
+just implementing "unpadded base64."
+.Pp
+.Fn Base64EncodedSize
+and
+.Fn Base64DecodedSize
+compute the amount of characters needed to store an encoded or
+decoded message, respectively. Both functions take the size of
+the message being encoded or decoded, but
+.Fn Base64DecodedSize
+also takes a pointer to an encoded string, because a few bytes of
+the string need to be read in order to compute the size.
+.Pp
+.Fn Base64Encode
+and
+.Fn Base64Decode
+do the actual work of encoding and decoding base64 data. They both
+take a string and its length.
+.Pp
+.Fn Base64Unpad
+and
+.Fn Base64Pad
+are used to implement Matrix unpadded base64.
+.Fn Base64Unpad
+takes a valid base64 string and strips off the trailing equal signs,
+as per the specification.
+.Fn Base64Pad
+does the opposite; it takes an unpadded base64 input string, and pads
+it with equal signs as necessary, so that it can be properly decoded
+with
+.Fn Base64Decode
+if necessary. However, the Matrix specification envisons unpadded base64
+as opaque; that is, once it's encoded, it never needs to be decoded.
+In practice, a homeserver might need to decode an unpadded base64 string.
+.Sh RETURN VALUES
+.Fn Base64EncodedSize
+and
+.Fn Base64DecodedSize
+simply return unsigned integers representing a number of bytes generated
+from a simple computation.
+.Pp
+.Fn Base64Encode
+and
+.Fn Base64Decode
+return pointers to new strings, allocated on the heap, or
+.Dv NULL
+if a heap allocation fails. These pointers must be
+.Xr free 3 -ed
+at some point when they are no longer needed.
+.Pp
+.Fn Base64Unpad
+modifies the passed string in-place. It thus has no return value, because
+it cannot fail. If the passed pointer is invalid, the behavior is undefined.
+.Fn Base64Pad
+returns a boolean value indicating whether the pad operation was successful.
+In practice, this function will only fail if a bigger string is necessary, but
+could not be automatically allocated on the heap.

man/man5/telodendria.conf.5

@@ -0,0 +1,190 @@
+.Dd $Mdocdate: September 30 2022 $
+.Dt TELODENDRIA.CONF 5
+.Os Telodendria Project
+.Sh NAME
+.Nm telodendria.conf
+.Nd Configuration file for Telodendria
+.Sh DESCRIPTION
+.Nm
+is the configuration file for the Telodendria homeserver,
+.Xr telodendria 8 .
+Telodendria is designed to be extremely configurable. As such,
+it has a fairly extensive configuration file. The configuration
+file can be passed to the Telodendria binary with the
+.Sy -f
+option, and is typically located at
+.Pa /etc/telodendria.conf
+.sp
+.Nm
+uses OpenBSD-style syntax, though it is a little more rigid in its
+parser. All values must be surrounded by quotes, and each directive
+must be ended with a semicolon.
+.Sh MACROS
+Macros can be defined that will later be expanded in context.
+Macro names must start with a letter, digit, or underscore, and may
+contain only those characters. Macros are not expanded inside quotes.
+.sp
+For example:
+.Bd -literal -offset indent
+macro1 = "value1";
+directive $macro1;
+.Ed
+.Sh GLOBAL OPTIONS
+Here are the settings that can be set globally:
+.Bl -tag -width Ds
+.It Ic listen Ar port
+The port to listen on. Telodendria will bind to all interfaces, but it
+is recommended to configure your firewall so that it only listens on
+localhost, and then configure a reverse proxy such as
+.Xr relayd 8
+in front of it, because Telodendria does not implement TLS. Note that
+Telodendria doesn't provide multiple ports for the various services it
+offers. ALl APIs are made available over the same port, so care should
+be taken in
+.Xr relayd.conf 5
+to ensure that only the public Matrix API paths are made available over
+the internet.
+.Ar port
+should be a decimal port number. This directive is entirely optional. If
+it is omitted, then Telodendria will listen on port 8008 by default.
+.It Ic server-name Ar name
+Configure the domain name of your homeserver. Note that Matrix servers
+cannot be migrated to other domains, so once this is set, it should never
+change unless you want unexpected things to happen, or you want to start
+over.
+.Ar name
+should be a DNS name that can be publically resolved. This directive
+is required.
+.It Ic base-url Ar url
+Set the server's base URL.
+.Ar url
+should be a valid URL, complete with the protocol. It does not need to
+be the same as the server name; in fact, it is common for a subdomain of
+the server name to be the base URL for the Matrix homeserver.
+.Pp
+This URL is the URL at which Matrix clients will connect to the server,
+and is thus served as a part of the
+.Pa .well-known
+manifest.
+.Pp
+This directive is optional. If it is not specified, it is automatically
+deduced from the server name.
+.It Ic identity-server Ar url
+The identity server that clients should use to perform identity lookups.
+.Pp
+.Ar url
+follows the same rules as
+.Ic base-url .
+.Pp
+This directive is optional. If it is not specified, it is automatically
+set to be the same as the base URL.
+.It Ic chroot Ar directory
+Change the root directory to the specified directory as soon as possible.
+Note that all other paths and files specified in
+.Nm
+must be accessible relative from this directory. This directive only
+takes effect if Telodendria is running as root. If it isn't, then a
+warning is printed to the log, and no
+.Xr chroot 2
+call is made. In that case, Telodendria will still change into the
+specified directory, so that the other paths referenced can be made
+relative to this one. This directive is required. It is expected that
+the homeserver data and logs will be stored in a subdirectory of this one.
+.It Ic id Ar uid Ar gid
+The effective UNIX user and group to drop to after binding to the socket
+and changing the filesystem root. This only works if Telodendria is
+running as the root user, and is used as a security mechanism. If Telodendria
+is started as a non-priviledged user, then a warning is printed to the log
+if that user does not match what's specified here. This directive is
+required, even if Telodendria is unable to switch to the given user and
+group. It should be used as a sanity check to make sure the permissions are
+working properly.
+.It Ic data-dir Ar directory
+The data directory into which Telodendria will write all user and event
+information. Telodendria doesn't use a database like other Matrix homeserver
+implementations; it uses a flat-file directory structure, similar to how an
+SMTP server uses Maildirs to deliver email. This directive is required.
+.Ar directory
+should be a path relative to the
+.Ic chroot
+directory. Don't depend on the
+.Ic chroot
+option working, because there may be legitimate cases when Telodendria will
+not be started as root, thus causing the chroot to fail.
+.It Ic federation Ar true|false
+Whether to enable federation with other Matrix homeservers or not. Matrix is
+by its very nature a federated protocol,  but if you just want to run your
+own internal chat server with no contact with the outside, then you can use
+this option to disable federation. It is highly recommended to set this to
+.Ar true ,
+however, if you wish to be able to communicate with users on other Matrix
+servers. This directive is required.
+.It Ic registration Ar true|false
+Whether or not to enable new user registration or not. For security and anti-spam
+reasons, you can set this to
+.Ar false .
+If you do, you can still add users via the administrator API. In an ideal world,
+everyone would run their own homeserver, so no public registration would ever
+be required. Unfortunately, not everyone has the means to run their own homeserver,
+especially because of the fact that public IPv4 addresses are becoming increasingly
+harder to come by. If you would like to provide a service to those that are unable
+to run their own homeserver, you can aset this to
+.Ar true ,
+which will allow anyone to create an account. Telodendria should be capable of handling
+a large amount of users without difficulty or security issues. This directive is
+required.
+.It Ic log Ar file|stdout
+The log configuration. Telodendria uses its own logging facility, which can output to
+either standard output or a file. A number of child directives can be added to this
+directive to customize the log output:
+.Bl -tag -width Ds
+.It Ic level Ar error|warning|task|message|debug
+The level of messages to log at. Each level shows all the levels above it. For
+example, setting the level to
+.Ar error
+will show only errors, while setting the level to
+.Ar warning
+will show warnings and errors.
+.Ar task
+shows tasks, warnings, and errors, and so on. The
+.Ar debug
+level shows all messages.
+.It Ic timestampFormat Ar format|none|default
+If you want to customize the timestamp format shown in the log, or disable it
+altogether, you can do so via this option. Acceptable values are
+.Ar none ,
+.Ar default ,
+or a formatter string as described by your system's
+.Xr strftime 3 .
+.It Ic color Ar true|false
+Whether or not to enable colored output on TTYs. Note that ANSI color sequences
+will not be written to a log file, only a real terminal, so this option only
+applies if the log is being written to a standard output which is connected to
+a terminal.
+.El
+.It Ic threads Ar count
+How many worker threads to spin up to handle requests. This should generally be
+less than the total CPU core count, to prevent overloading the system. The most
+efficient number of threads ultimately depends on the configuration of the
+machine running Telodendria, so you may just have to play around with different
+values here to see which gives the best performance.
+.El
+.Sh FILES
+.Bl -tag -width Ds
+.It Pa /etc/telodendria.conf
+The default
+.Xr telodendria 8
+configuration file.
+.It Pa /var/telodendria
+The recommended chroot directory.
+.El
+.Sh EXAMPLES
+Please consult the default
+.Nm
+that ships with Telodendria for a complete example. If you installed Telodendria
+as a package, then the example should be located at the default location. If you
+are building from source, you can find the default config in the
+.Pa contrib/
+directory.
+.Sh SEE ALSO
+.Xr telodendria 8

man/man7/contributing.7

@@ -0,0 +1,252 @@
+.Dd $Mdocdate: September 30 2022 $
+.Dt CONTRIBUTING 7
+.Os Telodendria Project
+.Sh NAME
+.Nm contributing
+.Nd Guide to contributing to Telodendria
+.Sh DESCRIPTION
+Telodendria is an open source project. As such, it welcomes
+contributions. There are many ways you can contribute, and any
+way you can is greatly appreciated. This page contains some of
+the ways you can help out.
+.Sh REPORTING ISSUES
+Please reach out to the Matrix rooms mentioned at the top of
+.Xr telodendria 7 .
+All issue tracking takes place in those rooms. Start by reaching
+out to the general room, and if you think there's a legitimate
+problem with Telodendria itself, then stick the issue in the
+issues room, where it can be discussed further. Issues usually
+remain in the Matrix rooms, but severe enough issues may be put
+in a
+.Pa TODO
+file in the
+.Xr cvs 1
+repository so that they don't get lost.
+.Sh DEVELOPING
+The primary language used to write Telodendria code is ANSI C.
+Other languages you'll find in the Telodendria repository include
+shell scripts, 
+.Xr mdoc 7 ,
+and a little bit of HTML and CSS. If you have any experience with
+any of these languages, your contributions are valuable! Please follow
+the guidelines on this page to ensure the contribution workflow goes
+as smoothly as possible.
+.Ss Getting the Code
+If you'd like to hack on Telodendria, you'll need the following tools
+in addition to a C compiler and POSIX shell:
+.Bl -tag
+.It Xr cvs 1
+For checking out and updating your local copy of the source code.
+.It Xr indent 1
+For formatting your code before generating patches.
+.It Xr patch 1
+For applying patches to your local copy of the source code.
+.El
+.sp
+All of these tools are built into OpenBSD. While you don't have to
+use OpenBSD to develop Telodendria, it may make the process a bit
+easier. In fact, these tools where chosen precisely because they
+were built into my operating system of choice.
+.sp
+You can download an official release tarball from the website if
+you would really like, but the preferred way to get the source
+code for development is to check it out from CVS. This makes generating
+patches a lot easier.
+.Bd -literal -offset indent
+$ cvs -d anoncvs@bancino.net:/cvs checkout -P Telodendria
+$ cd Telodendria
+.Ed
+.sp
+If you already checked out the code previously, make sure you update
+your local copy before you start developing:
+.Bd -literal -offset indent
+$ cvs -q update -dP
+.Ed
+.sp
+You should now have the latest source code. Follow the
+.Sx CODE STYLE
+as you make your changes. If the
+.Xr cvs 1
+command fails with a "Connection refused" error message, try setting
+the
+.Ev CVS_RSH
+environment variable to "ssh", like this:
+.Bd -literal -offset indent
+$ export CVS_RSH=ssh
+.Ed
+.sp
+Then run the checkout command again. Some versions of CVS on some
+systems don't use SSH to checkout by default, so if yours doesn't,
+you might want to put the above line into your shell init script.
+.Ss Submitting Patches
+Telodendria aims at remaining as minimal as possible. This doesn't just
+mean minimal code, it also means a minimal development process, which is
+why Telodendria doesn't use GitHub, GitLab, or even SourceHut. Instead,
+the contribution workflow operates on submitting patch files to a public
+Matrix room, sort of like the OpenBSD project operates on patch files
+sent to a public mailing list.
+.sp
+If you're not used to manually creating and submitting patches instead of
+just opening a "pull request," you should be pleased to hear that submitting
+patches is fairly easy to do if you've got the CVS sources checked out. In
+fact, I find it easier than having to make a GitHub account, forking a
+project's repository, and then making a pull request for it. Once you have
+made your changes in your local copy of the code, and you've configured your
+environment properly as noted in the manual for
+.Xr td 8 ,
+just run the patch recipe:
+.Bd -literal -offset indent
+$ td patch
+.Ed
+.sp
+This will automatically generate a patch file for all your changes, and then
+open it in your preferred editor. You can also generate a patch file for only
+certain files and directories. To do that, set
+.Ev PATCHSET ,
+like this:
+.Bd -literal -offset indent
+# Only write a patch for README.txt and the files in docs/
+$ PATCHSET="README.txt docs/" td patch
+.Ed
+.sp
+As you'll notice, the top of the patch file should have some email-style
+headers that look like this:
+.Bd -literal -offset indent
+From: Jordan Bancino <@jordan:bancino.net>
+Date: Fri Jul 29 03:21:21 PM EDT 2022
+Subject: Document Patch Procedure
+.Ed
+.sp
+As much information should be filled out for you, such as the date. An
+attempt to fill out the From header was also made by
+.Xr td 8 ,
+but the information there can be modifed as necessary. Consult the manual
+for
+.Xr td 8
+for more details. The Subject should very briefly describe what the patch
+is about.
+.sp
+You'll also notice these lines in the patch:
+.Bd -literal -offset indent
+[ ] I have read the Telodendria Project development certificate of
+    origin, and certify that I have permission to submit this patch
+    under the conditions specified in it.
+.Ed
+.sp
+This is a checkbox that tells me whether or not you actually have the
+rights to submit your patch, and that once you submit your patch, your
+code is bound by the Telodendria project license, which you can and
+should view in
+.Xr telodendria 7 .
+The full text of the developer certificate of origin is as follows:
+.Bl -enum
+.It
+The contribution was created in whole or in part by me, and I have the right
+to submit it under the open source licenses of the Telodendria project; or
+.It
+The contribution is based upon a previous work that, to the best of my knowledge,
+is covered under an appropriate open source license and I have the right under
+that license to submit that work with modifications, whether created in whole
+or in part by me, under the Telodendria project license; or
+.It
+The contribution whas provided directly to me by some other person who certified
+(1), (2), or (3), and I have not modifed it.
+.It
+I understand and agree that this project and the contribution are made public
+and that a record of the contribution\(emincluding all personal information
+I submit with it\(emis maintained indefinitely and may be redistributed
+consistent with this project or the open source licenses involved.
+.El
+.sp
+If you agree to the above, fill in the square brackets with an 'x', and then after
+the headers, but before the checkbox, write a more thorough description of the
+patch and why it was created. Then, send the resulting patch file to the public
+Matrix room, as noted in
+.Xr telodendria 7 ,
+so it can be discussed and reviewed by the community.
+.sp
+Try to keep your patches on topic\(emmake one patch file per feature or bug fix
+being implemented. It is okay if your patches depend on previous patches, just
+indicate that in the patch description. Note that it may take a while for
+patches to be committed, and some patches may not be comitted at all. In either
+case, all sent patches are queued from the Matrix room into the public patch
+directory, so they can be referenced easier in the future. If you want to
+reference a submitted patch in a Matrix message, email, or other digital medium,
+it might be a good idea to link to it in the public patch directory.
+.sp
+The public patch directory works as follows: when you send your patch to the
+Matrix room, it is downloaded by Telodendria Bot and placed in the
+.Pa ingress/
+directory, named as the message ID. Then, it is assigned a patch ID and
+copied to the
+.Pa p/
+directory as just "%d.patch", where "%d" is obviously the patch ID. This is
+a permanent link that will always reference your patch. Then, your patch will
+be symlinked into the 
+.Pa queue/
+directory. I have a script that automatically ingresses patches and queues them
+for me, and I use this to review patches. If your patch is accepted, the queue
+symlink will be moved to
+.Pa accepted/
+and the submitted patch will be committed to the official CVS repository.
+If your patch is rejected for some reason, its symlink will be moved to the
+.Pa rejected/
+directory. Regardless of the state of your patch, it will always remain
+permalinked in the
+.Pa p/
+directory, and when it is accepted or rejected, Telodendria Bot will send a
+message to the Matrix room.
+.sp
+You're always welcome to inquire about rejected patches, and request that they
+be reviewed again, or you can use them as a starting point for future patches.
+.sp
+The public patch directory is located at
+.Lk https://telodendria.io/patches/
+.Sh CODE STYLE
+In general, these are the conventions used by the code base. This guide
+may be slightly outdated or subject to change, but it should be a good
+start. The source code itself is always the absolute source of truth, so
+as long as you make your code look like the code surrounding it, you should
+be fine.
+.Bl -bullet
+.It
+All function, enumeration, structure, and header names are CamelCase. This
+is preferred to snake_case because it is more compact.
+.It
+All variable names are lowerCamelCase. This is preferred to snake_case
+because it is more compact.
+.It
+enumerations and structures are always typedef-ed to their same name. The
+typedef should occur in the public API header, and the actual declaration
+should live in the implementation file.
+.It
+A feature of the code base lives in a single C source file that has a
+matching header. The header file should only export public symbols;
+everything else in the C source should be static.
+.It
+Except where absolutely necessary, global variables are forbidden to
+prevent problems with threads and whatnot. Every variable a function
+needs should be passed to it either through a structure, or as a
+separate argument.
+.It
+Anywhere curly braces are optional, there still must be curly braces. This
+makes it easier to add on to the code later, and just makes things a bit
+less ambiguous.
+.El
+.sp
+As far as actually formatting the code goes, such as where to put brackets,
+and whether or not to use tabs or spaces, use
+.Xr indent 1
+to take care of all of that. The root of the CVS repository has a
+.Pa .indent.pro
+that should automatically be loaded by
+.Xr indent 1
+to set the correct rules. If you don't have a working
+.Xr indent 1 ,
+then just indicate in your patch that I should run my
+.Xr indent 1
+on the code after applying it. Although in reality, I'll likely
+run my own
+.Xr indent 1
+on the code anyway, just to make sure the spacing is consistent, if nothing
+else.

man/man7/telodendria.7

@@ -0,0 +1,248 @@
+.Dd $Mdocdate: September 30 2022 $
+.Dt TELODENDRIA 7
+.Os Telodendria Project
+.Sh NAME
+.Nm Telodendria
+.Nd The terminal branches of an axon.
+.Sh DESCRIPTION
+.Nm
+is an open source Matrix homeserver written entirely from scratch in ANSI C.
+It is designed to be lightweight and simple, yet functional.
+.Pp
+.Sy Note:
+.Nm
+is under
+.Sy heavy
+development. Please see
+.Sx PROJECT STATUS .
+.Pp
+.Nm
+differentiates itself from the other Matrix homeserver
+implementations because it:
+.Bl -bullet
+.It
+Is written in C, a stable, low-level programming language with a
+long history, low build and runtime overhead, and wide compatibility.
+.It
+Is written with minimalism as a primary design goal. Whenever possible
+and practical, no third-party libraries are pulled into the source code.
+Everything
+.Nm
+needs is custom written. As a result,
+.Nm
+depends only on a standard C compiler and a POSIX C library to be built,
+both of which should come with any good Unix-style operating system already,
+which means you shouldn't have to install anything extra.
+.It
+Uses a flat-file directory structure to store data instead of a database.
+This has a number of advantages:
+.Bl -bullet
+.It
+It makes setup and maintenance much easier.
+.It
+It allows
+.Nm
+to run on systems with fewer resources.
+.El
+.It
+Is packaged as a single small, statically-linked and highly-optimized binary
+that can be run just about anywhere. It is designed to be extremely easy to
+set up and consume as few resources as possible.
+.It
+Is permissively licensed.
+.Nm
+is licensed under a modified MIT license, which imposes very few restrictions
+on what you can do with it.
+.El
+.Pp
+.Nm
+is on Matrix! Check out the official Matrix rooms:
+.Pp
+.TS
+box tab(;);
+l l.
+#telodendria:bancino.net;The public "space" room.
+#telodendria-releases:bancino.net;Get notified of new releases.
+#telodendria-general:bancino.net;General discussion and support.
+#telodendria-issues:bancino.net;Report bugs and issues.
+#telodendria-patches:bancino.net;Submit code patches to the project.
+.TE
+.Nm
+is designed to be fairly straightforward, but that doesn't mean there
+won't be hiccups along the way. If you're struggling to get
+.Nm
+up and running, you're more than welcome to reach out for support. Just
+hop into the appropriate Matrix rooms and talk to me!
+.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.
+.Pp
+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.
+.Pp
+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 the project's goals, but it is a list of things that I want to prioritize,
+because other server implementations lack them.
+.Pp
+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 as privacy-friendly as possible.
+.Nm
+should not store any information it does not absolutely need to function as a
+Matrix homeserver. While
+.Nm
+strives to be feature-complete, it should not implement anything not explicitly
+defined in the Matrix specification.
+.It
+To be a production-ready Matrix server capable of working in constrained environments,
+such as embedded devices, cheap VPSs, or a peer-to-peer device.
+.Nm
+should also work on traditional setups as well, and be able to handle a decent
+amount of users. It should work well for personal Matrix homeservers that also
+host a few friends and/or family members.
+.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
+.Pp
+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 PROJECT STATUS
+Telodendria is a very ambitious project. There's a lot that needs to happen yet
+before it is usable. At the moment, there's nothing here that even remotely resembles
+a Matrix homeserver. I'm still getting off the ground and building a foundation.
+.Pp
+But just because there's nothing here yet doesn't mean you should go away! I could
+always use help, so you are more than welcome to help out if you want things to go
+quicker. Please see the
+.Xr contributing 7
+page for details on how you can get involved. The CVS repository has a file called
+.Pa TODO.txt ,
+which contains a checklist of what has been done so far, and what's on the radar
+to be done. You can take a look at it once you've checked out the source code.
+If you'd like to help out, feel free to grab an item on the list that's not done
+yet and start getting patches written. When you're done, enjoy the satisfaction
+of crossing the item off the list yourself.
+.Sh SEE ALSO
+.Xr telodendria 8 ,
+.Xr telodendria.conf 5 ,
+.Xr td 8
+.Sh STANDARDS
+The installed version of
+.Nm
+conforms to the latest Matrix specification available at the time
+of its release.
+.Sh HISTORY
+At this time,
+.Nm
+does not have any tagged releases because it is not yet functional
+as a Matrix homeserver. Please checkout out
+.Sx PROJECT STATUS
+to see where things are currently at. When
+.Nm
+is mature enough to have a change log, it will go in this section.
+.Sh AUTHORS
+.Nm
+was started by Jordan Bancino <@jordan:bancino.net>.
+Contributions to the code, website, documentation, or other
+components of
+.Nm
+were made by the following people:
+.Bl -bullet
+.It
+Jonah Evans <@jonah:bancino.net>
+.El
+.Sh LICENSE
+All of the code and documentation for
+.Nm
+is licensed under a modified MIT license. Please consult the
+.Pa LICENSE.txt
+file for the actual license text. The
+.Nm
+license text differs from the MIT license in the following ways:
+.Bl -bullet
+.It
+Where the MIT license states that the copyright notice and permission
+notice shall be included in all copies or
+.Pa substantial
+portions of the software, the
+.Nm
+license requires the copyright notice and permission notice be included
+with
+.Pa all
+portions, regardless of the size, of the software by omitting the word
+.Pa substantial .
+.El
+.Pp
+The
+.Nm
+logo, however, belongs solely to the
+.Nm
+project. It must only be used to represent the official
+.Nm
+project, and may only appear in official
+.Nm
+media. If
+.Nm
+is forked, the logo must be removed completely from the project, and
+optionally replaced with a different one. The logo may not be modified
+in any way or for any purpose.

man/man8/td.8

@@ -0,0 +1,238 @@
+.Dd $Mdocdate: September 30 2022 $
+.Dt TD 8
+.Os Telodendria Project
+.Sh NAME
+.Nm td
+.Nd Telodendria build script
+.Sh SYNOPSIS
+.Nm
+.Op recipe
+.Sh DESCRIPTION
+Telodendria uses a custom build script called
+.Nm .
+The
+.Nm
+script is not only a build script, however. It does all kinds of
+cool things like format the source code, and generate patch files.
+.Nm
+is the only supported way to develop Telodendria.
+.sp
+I opted to write a custom build script instead of just writing a
+.Pa Makefile
+because I felt that there is really no way to make a truly portable
+.Pa Makefile
+that could do everything I wanted, with the flexibility I wanted. I
+was doing a lot of research on the differences between the GNU and BSD
+versions, and I felt it just wasn't worth trying to reconsile the two
+when I could write a small and relatively robust POSIX shell script that
+would run on both GNU and BSD systems without any problems. I also
+think that shell scripts are a lot easier to read than complex
+.Pa Makefiles.
+They're easier to follow because they're not so cryptic.
+.sp
+The
+.Nm
+script is fairly intuitive. It operates somewhat like
+.Xr make 1
+in that it has recipes that you specify on the command line. To start
+using it, just run the following command in the Telodendria source
+directory:
+.Bd -literal -offset indent
+$ . tools/env.sh
+.Ed
+.sp
+.Sy Note:
+You will have to run the above command every time you start a new
+terminal session, as nothing is persisted to your system. I believe in
+non-invasive, fully self-contained tooling, so it is up to you to hook the
+Telodendria tools into your environment as you see fit if you want them to
+persist.
+.sp
+If you're going to be submitting patches, you should also configure a
+.Pa .env
+file in the project directory root, which
+.Nm
+will include automatically for you. See
+.Em FILES
+and
+.Em ENVIRONMENT .
+.sp
+Telodendria is designed to be light enough that it can be built from source
+on just about any operating system. It only requires an ANSI C compiler and a
+standard POSIX environment. To build the Telodendria binary, run
+.Nm
+with no arguments, or with the
+.Pa build
+recipe. This will produce
+.Pa build/telodendria ,
+which you can then install to your system and run as a daemon.
+.sp
+A complete list of recipes is below. Note that you can run multiple recipes
+with a single invocation of
+.Nm ,
+but recipes are run unconditionally; that is, even if a recipe fails, all the
+following recipes are still executed.
+.Bl -tag
+.It build
+Build the source code and generate the output binary. This is the default recipe,
+which means it runs if no other recipes are specified. This recipe is incremental;
+it only rebuilds sources that have been modifed since the last build, making
+subsequent builds faster.
+.It run
+Run the build binary with the development configuration in the
+.Pa contrib/
+directory. This recipe is used for quick testing during development. It is
+.Sy not
+the recommended way to run Telodendria in a production environment; it should only
+be used for development.
+.It clean
+Remove the
+.Pa build/
+directory and any ephemeral files in the source tree, such as
+.Pa .orig
+files. The build recipe does not place anything outside of
+.Pa build/ ,
+so you can usually just delete that directory and get the same effect.
+.It format
+Make sure the source code copyright headers are up to date, and format the code
+using the system's
+.Xr indent 1 .
+This should be run before generating patch files, to ensure that the code follows
+the project conventions. Note that the provided
+.Pa .indent.pro
+assumes an OpenBSD indent, which may cause the GNU implementation to choke. In
+that case, don't send patch files with totally different formatting; just submit
+the patch as-is and they will get formatted before committing.
+.It test
+Run all of the unit tests and report the results. It is highly recommended to
+ensure that all the tests pass before submitting a patch, because patches that
+break the tests are likely to be rejected.
+.It site
+Deploy the Telodendria website by generating HTML files for the documentation,
+and copying them along with the front page to the specified web root. This is
+used to deploy the official website, but it could be used to deploy a local
+development site as necessary. See
+.Em ENVIRONMENT .
+.It release
+Generate a release tarball, checksum and sign it, and push it to the web root.
+See the relevant environment variables below.
+.It patch
+Generate a formatted patch file. The Telodendria project isn't super picky about
+how patches look as long as they apply cleanly, but this recipe generates patches
+in the format we like them, and is therefore recommended. It makes patches easy
+to read. This recipe will use your configured editor to open your formatted patch
+so you can review and edit it as necessary before sending it off.
+.It diff
+Generate a temporary preview patch that is opened in the system pager. This can
+be used for quickly quickly previewing your changes and the patch file you'll
+be creating.
+.El
+.sp
+.Sh ENVIRONMENT
+Any of the following environment variables are used in the build recipes.
+They can all be specified in your shell when invoking
+.Nm ,
+or they can be placed in a
+.Pa .env
+file. For most of these variables, if you would like to append or prepend
+to the default values, do so in the
+.Pa .env
+file, which is sourced after the defaults are set, allowing you to reference
+the default values in your new value.
+.Bl -tag
+.It Ev CC
+The C compiler to use. This defaults to
+.Pa cc,
+which is usually a symlink to your system's preferred compiler. If for some
+reason you want to use a diferent compiler, do so with this environment
+variable.
+.It Ev CFLAGS
+The compiler flags used to generate object files.
+.Nm
+comes with reasonable defaults that shouldn't need to be changed in most
+scenarios, but if you do need to change the compiler flags, you can do
+so with this environment variable. 
+.It Ev LDFLAGS
+The compiler flags used to link the object files to create an output
+binary.
+.Nm
+comes with reasonable defaults that shouldn't need to be changed in most
+scenarios, but if you need to change the linker flags, you do so with this
+environment variable.
+.It Ev PROG
+The name of the output binary. This defaults to
+.Pa build/telodendria.
+.It Ev DEFINES
+Global preprocessor definitions to append to
+.Ev CFLAGS.
+This is just kept separate to keep things organized.
+.It Ev INCLUDES
+Header directories to make available. This is appended to
+.Ev CFLAGS,
+it is just kept separate to keep things organized.
+.It Ev DEBUG
+If set to "1", append some debug flags to
+.Ev CFLAGS
+and whipe out any
+.Ev LDFLAGS
+that awould cause the output binary to be optimized in any way. This also
+depends "-debug" to
+.Ev PROG .
+.It Ev TELODENDRIA_VERSION
+This variable does make its way into the output binary, but it is primarily
+used for generating and publishing releases. This variable affects the
+.Sy release
+recipe.
+.It Ev TELODENDRIA_PUB
+The web root where the Telodendria website lives. This is where the site
+is pushed to, and where generated releases go.
+.It Ev PATCHSET
+This variable restricts the files that
+.Nm
+operates on when generating patches or diffs. If you only want to generate
+a diff or patch for a certain file, directory, or collection of files and
+directories, set this variable to those files and directories, separated
+by a space. You can mix files and directories as necessary.
+.It Ev MXID
+Your Matrix ID in standard format. This is used when generating patches,
+so that you can be assigned credit for your patches, as well as be contacted
+about your patches.
+.Nm
+will automatically deduce this from your system, but it will most
+likely get it wrong. Please make sure you are reachable at this ID.
+.It Ev DISPLAY_NAME
+The display name you want to appear on your patches. This should probably
+match your Matrix display name, although it doesn't necessarily have to.
+.Nm
+will deduce this from your system, and if you set it up properly, you may
+not even have to set this variable. If
+.Nm
+gets it wrong, this allows you to override your display name.
+.It Ev EDITOR
+Your preferred editor for writing patch file descriptions. This can be a
+GUI or terminal editor. If unset, this defaults to the system's
+.Xr vi 1
+editor.
+.It Ev PAGER
+Your preferred pager for previewing patches. If left unset, this defaults
+to
+.Xr less 1 .
+.Sh FILES
+.Bl -tag
+.It Pa .env
+An environment file that contains lines in the form of
+.Pa VARIABLE=value
+with environment variables to set in the
+.Nm
+script. See
+.Em ENVIRONMENT .
+Note that
+.Nm
+simply sources this file, which means that any shell code in it will be
+executed each time
+.Nm
+is invoked.
+.Sh EXIT STATUS
+.Sh HISTORY
+.Sh CAVEATS
+.Sh BUGS

man/man8/telodendria.8

@@ -0,0 +1,57 @@
+.Dd $Mdocdate: September 30 2022 $
+.Dt TELODENDRIA 8
+.Os Telodendria Project
+.Sh NAME
+.Nm telodendria
+.Nd Matrix homeserver daemon
+.Sh SYNOPSIS
+.Nm
+.Op Fl nVv
+.Op Fl f Ar file
+.Sh DESCRIPTION
+.Nm
+is a Matrix homeserver written entirely from scratch in ANSI C.
+It is designed to be lightweight and simple, yet functional.
+.sp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl f Ar file
+Specify an alternate configuration file. The default is
+.Pa /etc/telodendria.conf .
+.It Fl n
+Configtest mode. Only check the configuration file for validity.
+.It Fl V
+Only print the version information header.
+.It Fl v
+Verbose mode. This overrides the configuration file and sets the
+log level to
+.Em LOG_DEBUG
+.El
+.Sh ENVIRONMENT
+.Nm
+does not read any environment variables. All configuration should
+be done via the configuration file.
+.Sh FILES
+Just the configuration file and the data directory; see
+.Xr telodendria.conf 5
+for more details.
+.El
+.Sh EXIT STATUS
+.Nm
+exits with a non-0 exit code if the configuration file is invalid, or
+one or more required paths is inaccessible.
+.Nm
+will print an error to the log and then terminate abnormally.
+.Pp
+.Nm
+exits with a code of 0 if the configuration file is valid, all
+paths and files required are accessible, and the HTTP listener starts
+as intended. If
+.Nm
+is sent a signal that it catches after it begins servicing requests, it
+will still exit with a code of 0 after it safely shuts down, because
+the bootstrap process completed successfully, and by all accounts,
+it ran normally and exitted normally.
+.Sh SEE ALSO
+.Xr telodendria 7 ,
+.Xr telodendria.conf 5

site/index.html

@@ -16,20 +16,20 @@
 <meta property="og:description"
     content="Telodendria, a Matrix homeserver written in ANSI C.">
 
-<link rel="stylesheet" href="style.css">
+<link rel="stylesheet" href="/style.css">
 <link rel="icon" href="assets/Telodendria-196x196.png">
 
 <title>Telodendria | A Matrix Homeserver written in ANSI C.</title>
 </head>
 <body>
-<img id="logo" src="assets/Telodendria-500x500.png" alt="Telodendria Logo"/>
+<img id="logo" src="/assets/Telodendria-500x500.png" alt="Telodendria Logo"/>
 <h1 id="telodendria">Telodendria</h1>
 <p>
 <b>Telodendria:</b> The terminal branches of an axon.
 </p>
 <div class="msg-error">
 <b><i>Note:</i></b> <b>Telodendria</b> is under <i>heavy</i> development.
-Please see the <a href="telodendria.7.html#PROJECT_STATUS">Project Status</a>.
+Please see the <a href="/man/man7/telodendria.7.html#PROJECT_STATUS">Project Status</a>.
 </div>
 <p>
 <b>Telodendria</b> is an open source Matrix homeserver implementation written from
@@ -159,7 +159,7 @@ Signify
 <tr>
 <td colspan="4" style="text-align: center;">
 No downloads here yet. See the
-<a href="telodendria.7.html#PROJECT_STATUS">Project Status</a> for more
+<a href="/man/man7/telodendria.7.html#PROJECT_STATUS">Project Status</a> for more
 information.
 </td>
 </tr>
@@ -175,23 +175,23 @@ on what <b>Telodendria</b> is, what its goals are, how to build the source,
 configure it, as well as contribute to the project. The <code>man</code>
 pages are also available online for convenience:
 </p>
-<ul>
+<p>
-<li><a href="telodendria.7.html">telodendria(7)</a> - Introduction and project information, including licensing information</li>
+User documentation:
-<li><a href="telodendria.8.html">telodendria(8)</a> - Command line usage</li>
-<li><a href="telodendria.conf.5.html">telodendria.conf(5)</a> - Configuration file</li>
-<li><a href="contributing.7.html">contributing(7)</a> - Contributing guide</li>
-<li><a href="td.8.html">td(8)</a> - Build script and patch instructions</li>
-</ul>
-<h2>Getting Support</h2>
-<b>Telodendria</b> is designed to be fairly straightforward, but that
-doesn't mean there won't be hiccups along the way. If you are struggling
-to get <b>Telodendria</b> up and running, you're more than welcome to
-reach out for support. Just join the
-<code>#telodendria-general:bancino.net</code> Matrix channel. Before
-you do though, make sure you're running the latest version of
-<b>Telodendria</b> and you've thoroughly read through all the
-relevant documentation.
 </p>
+<ul>
+<li><a href="/man/man7/telodendria.7.html">telodendria(7)</a> - Introduction and project information, including project status and licensing information</li>
+<li><a href="/man/man8/telodendria.8.html">telodendria(8)</a> - Command line usage</li>
+<li><a href="/man/man5/telodendria.conf.5.html">telodendria.conf(5)</a> - Configuration file</li>
+<li><a href="/man/man7/contributing.7.html">contributing(7)</a> - Contributing guide</li>
+<li><a href="/man/man8/td.8.html">td(8)</a> - Build script and patch instructions</li>
+</ul>
+<p>
+Developer documentation:
+</p>
+<ul>
+<li><a href="/man/man3/Array.3.html">Array(3)</a> - Dynamic array structure</li>
+<li><a href="/man/man3/Base64.3.html">Base64(3)</a> - Base64 encoder/decoder with unpadded support</li>
+</ul>
 <h2 id="resources">Resources</h2>
 <ul>
 <li><a target="_blank" href="/pub">Old <b>Telodendria</b> Versions</a></li>

tools/bin/td

@@ -164,13 +164,15 @@ recipe_site() {
 		exit 1
 	fi
 
-	# In the future, this might do more.
 	cp -v site/* "$TELODENDRIA_PUB/"
 
-	find docs/ -name '*.[1-9]' | while IFS= read -r man; do
+	find man/ -name '*.[1-9]' | while IFS= read -r man; do
+		dir=$(dirname "$man")
 		html=$(basename "$man")
-		mandoc -Thtml -O style=style.css "$man" > "$TELODENDRIA_PUB/$html.html"
+
-		echo "$man -> $TELODENDRIA_PUB/$html.html"
+		mkdir -p "$TELODENDRIA_PUB/$dir/"
+		mandoc -Thtml -O style=/style.css "$man" > "$TELODENDRIA_PUB/$dir/$html.html"
+		echo "$man -> $TELODENDRIA_PUB/$dir/$html.html"
 	done
 }
 

tools/env.sh

@@ -4,4 +4,9 @@ find tools/bin -type f | while IFS= read -r tool; do
 	chmod +x "$tool"
 done
 
-PATH="$(pwd)/tools/bin:$PATH"
+makewhatis "$(pwd)/man"
+
+export PATH="$(pwd)/tools/bin:$PATH"
+export MANPATH="$(pwd)/man:$MANPATH"
+
+PS1="(td) $PS1"