From f250e66c793dc65f911468817af27da4eb6e8ee7 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Wed, 21 Sep 2022 20:12:21 -0400 Subject: [PATCH] Begin work on converting most of the site to man pages. I want to do this so that even the documentation can be viewed on a base install, without having to install a browser or converter. --- docs/td.8 | 237 +++++++++++++++++++++++++++++++++++++++++++++ docs/telodendria.7 | 131 +++++++++++++++++++++++++ docs/telodendria.8 | 53 ++++++++++ 3 files changed, 421 insertions(+) create mode 100644 docs/td.8 create mode 100644 docs/telodendria.7 create mode 100644 docs/telodendria.8 diff --git a/docs/td.8 b/docs/td.8 new file mode 100644 index 0000000..c55a150 --- /dev/null +++ b/docs/td.8 @@ -0,0 +1,237 @@ +.Dd September 21, 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: +.sp +.D1 $\ . tools/env.sh +.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 diff --git a/docs/telodendria.7 b/docs/telodendria.7 new file mode 100644 index 0000000..5caea39 --- /dev/null +++ b/docs/telodendria.7 @@ -0,0 +1,131 @@ +.Dd September 21, 2022 +.Dt TELODENDRIA 7 +.Os Telodendria Project +.Sh NAME +.Nm Telodendria +.Nd The terminal branches of an axon. +.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 +.Sy Note: +.Nm +is under +.Sy heavy +development. Please see +.Em PROJECT STATUS . +.sp +.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 +.sp +.Nm +is on Matrix! Check out the official Matrix rooms: +.sp +.TS +tab(;); +l l. +Room;Description +----;----------- +#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 +.Sh SEE ALSO +.Xr telodendria 8 , +.Xr telodendria.conf 5 , +.Xr td 8 +.Sh STANDARDS +.Nm +conforms to the Matrix Specification v1.3. +.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 +.Em 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 +.An Jordan Bancino Aq Mt @jordan:bancino.net . +Contributions to the code, website, documentation, or other +components of +.Nm +were made by the following people: +.sp +.An Jonah Evans Aq Mt @jonah:bancino.net +.Sh LICENSE +All of the code and documentation for +.Nm +is licensed under a modified MIT license. Please consult the +.Pa src/header.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 +.sp +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. diff --git a/docs/telodendria.8 b/docs/telodendria.8 new file mode 100644 index 0000000..541213b --- /dev/null +++ b/docs/telodendria.8 @@ -0,0 +1,53 @@ +.Dd September 21, 2022 +.Dt TELODENDRIA 8 +.Os Telodendria Project +.Sh NAME +.Nm telodendria +.Nd Matrix homeserver daemon +.Sh SYNOPSIS +.Nm +.Op Fl hnVv +.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 h +Show a brief help message. This message will be very short; for +full documentation, consult this manual page. +.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 +.Sh FILES +.Sh EXIT STATUS +.Sh SEE ALSO +.Xr telodendria.conf 5 +.Sh STANDARDS +.Nm +conforms to the Matrix Specification v1.3. +.Sh HISTORY +.Sh AUTHORS +.Nm +was started by +.An Jordan Bancino Aq Mt @jordan:bancino.net . +Contributions to the code, website, documentation, or other +components of +.Nm +were made by the following people: +.sp +.An Jonah Evans Aq Mt @jonah:bancino.net +.Sh CAVEATS +.Sh BUGS