forked from Telodendria/Telodendria
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