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.
This commit is contained in:
parent
1eca0579bc
commit
f250e66c79
3 changed files with 421 additions and 0 deletions
237
docs/td.8
Normal file
237
docs/td.8
Normal file
|
|
@ -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
|
||||||
131
docs/telodendria.7
Normal file
131
docs/telodendria.7
Normal file
|
|
@ -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.
|
||||||
53
docs/telodendria.8
Normal file
53
docs/telodendria.8
Normal file
|
|
@ -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
|
||||||
Loading…
Reference in a new issue