plate/telodendria
1
0
Fork 0
forked from lda/telodendria
Code Pull requests Activity Actions

Begin work on converting most of the site to man pages.

Browse source 
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:
Jordan Bancino 2022-09-21 20:12:21 -04:00
parent 1eca0579bc
commit f250e66c79
3 changed files with 421 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

237
docs/td.8 Normal file
View 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
View 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
View 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