diff --git a/.gitignore b/.gitignore index 7d63ee8..c0d6bc5 100644 --- a/.gitignore +++ b/.gitignore @@ -12,3 +12,4 @@ contrib/.vagrant src/Schema src/include/Schema man/mandoc.db +man/* diff --git a/man/man1/http-debug-server.1 b/man/man1/http-debug-server.1 deleted file mode 100644 index f8c02da..0000000 --- a/man/man1/http-debug-server.1 +++ /dev/null @@ -1,18 +0,0 @@ -.Dd $Mdocdate: May 6 2023 $ -.Dt HTTP-DEBUG-SERVER 1 -.Os Telodendria Project -.Sh NAME -.Nm http-debug-server -.Nd A simple HTTP server that logs requests to the standard output. -.Sh DESCRIPTION -.Pp -.Nm -spins up an HTTP server, listening on port 8008, in the exact same -manner as Telodendria itself. Any request it receives is written to -the standard output, and an empty JSON object is returned to the -client. -.Pp -This command exists just to test the HTTP server API during -development. It probably serves no other practical purpose. -.Sh SEE ALSO -.Xr HttpServer 3 diff --git a/man/man1/http.1 b/man/man1/http.1 deleted file mode 100644 index 3a108e9..0000000 --- a/man/man1/http.1 +++ /dev/null @@ -1,70 +0,0 @@ -.Dd $Mdocdate: March 12 2023 $ -.Dt HTTP 1 -.Os Telodendria Project -.Sh NAME -.Nm http -.Nd A simple command line utility for making HTTP requests. -.Sh SYNOPSIS -.Nm -.Op Fl i -.Op Fl X Ar method -.Op Fl H Ar header -.Op Fl d Ar data -.Op URL -.Sh DESCRIPTION -.Nm -Is a command line HTTP client. It is very heavily inspired by -.Xr curl 1 , -and even uses the same flag names when possible. However, -.Nm -is designed to be much simpler than -.Xr curl 1 , -and is built on Telodendria's own -.Xr HttpClient 3 -API. It primarily exists to test -.Xr HttpClient 3 -and -.Xr HttpServer 3 , -and make development of Telodendria possible without having -to install any external tools. -.sp -The options are as follows: -.Bl -tag -width Ds -.It Fl i -Display the response headers before writing the body. -.It Fl X Ar method -Set the request method. This can be any of the options -allowed by the -.Xr Http 3 -API; unlike -.Xr curl 1 , -it cannot be any arbitrary string. -.It Fl H Ar header -Set a request header, in the form of ``Header: value''. This option -can be set multiple times to add multiple request headers. -.It Fl d Ar data -Send data to the server in the request body. If -.Ar data -starts with ``@'', then the file specified after is opened -and read in. If it is ``@-'', then standard input is used. -Otherwise, the string is passed to the server as-is. -.El -.Pp -.Nm -also requires a -.Ar URL -to make the request to. The URL is parsed by the -.Xr Uri 3 -API, so consult that page for the syntax of URLs. -.Sh EXIT STATUS -.Nm -exits with -.Va EXIT_SUCCESS -if all command line options were valid, the request was -made successfully, and the server returns an HTTP code -that indicates success. It exits with -.Va EXIT_FAILURE -in all other scenarios. -.Sh SEE ALSO -.Xr HttpClient 3 , -.Xr Uri 3 diff --git a/man/man1/json.1 b/man/man1/json.1 deleted file mode 100644 index 7ed18c3..0000000 --- a/man/man1/json.1 +++ /dev/null @@ -1,111 +0,0 @@ -.Dd $Mdocdate: March 12 2023 $ -.Dt JSON 1 -.Os Telodendria Project -.Sh NAME -.Nm json -.Nd A simple command line utility for parsing and generating JSON. -.Sh SYNOPSIS -.Nm -.Op Fl s Ar query -.Op Fl e Ar str -.Sh DESCRIPTION -.Nm -is a simple command line utility for dealing with JSON. It is -somewhat inspired by -.Xr jq 1 , -but is not compatible in any way with it. -.Nm -is designed to be much simpler than -.Xr jq 1 , -and is built on Telodendria's own -.Xr Json 3 -API. It primarily exists to ease development of Telodendria, and -to make development possible without having to install any external -tools. -.Pp -The options are as follows. Unless stated otherwise, these options -are mutually exclusive, and the last one specified takes precedence. -All positional parameters are ignored. -.Bl -tag -width Ds -.It Fl s Ar query -Use -.Va query -to query a field from a JSON object given on the standard input. -The query syntax very vaguely resembles C code, but it is much -more primitive. Multiple queries are separated by an arrow -(``->''). This makes it trivial to drill down into nested -objects and arrays. -.Pp -To select a value from an object, just specify the key. To select -an element from an array specify the key whose value is the array, -and then use the C square bracket syntax to select an element. -.Pp -A number of ``functions'' exist to make -.Nm -more versatile. Functions are called by prefacing the key with -a ``@'' symbol. Functions can appear anywhere in the query, provided -they make sense within the context of the JSON object being processed. -The available functions are as follows: -.Bl -tag -width Ds -.It keys -When applied to an object, outputs an array of keys. -.It length -When applied to an array, outputs the number of elements in the -array. When applied to a string, returns the number of bytes -needed to store the decoded version of the string. -.It decode -When applied to a string, outputs the decoded version of the -string. -.El -.Pp -When a key is prefaced with the ``^'' symbol, then instead of getting -the value at that key, it is removed from the object, and the new -object is passed along. -.It Fl e Ar str -Encode -.Va str -as a JSON string and print it to standard output. This is useful for -generating JSON with shell scripts. -.El -.Pp -If no options are specified, then the default behavior of -.Nm -is to read a JSON object given on the standard input and pretty-print -it to the standard output, or print an error to standard error if -the given input is invalid. -.Sh EXAMPLES -.Pp -Get the error string of an error returned by a Matrix API endpoint: -.Bd -literal -offset indent -json -s 'error->@decode' -.Ed -.Pp -Get the number of stages in the first flow listed in a list -of user-interactive authentication flows: -.Bd -literal -offset indent -json -s 'flows[0]->stages->@length' -.Ed -.Pp -Get the first stage of the first flow listed in a list -of user-interactive authentication flows: -.Bd -literal -offset indent -json -s 'flows[0]->stages[0]->@decode' -.Ed -.Pp -List the keys in a JSON object: -.Bd -literal -offset indent -json -s '@keys' -.Ed -.Pp -Get the number of keys in a JSON object: -.Bd -literal -offset indent -json -s '@keys->@length' -.Ed -.Sh EXIT STATUS -.Nm -exits with -.Va EXIT_SUCCESS -if all command line options were valid and the given JSON object -parses successfully. It exits with -.Va EXIT_FAILURE -in all other scenarios. diff --git a/man/man1/td.1 b/man/man1/td.1 deleted file mode 100644 index 15bb994..0000000 --- a/man/man1/td.1 +++ /dev/null @@ -1,267 +0,0 @@ -.Dd $Mdocdate: April 29 2023 $ -.Dt TD 1 -.Os Telodendria Project -.Sh NAME -.Nm td -.Nd Telodendria build script and patch generation instructions. -.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 docs -Build the code documentation files. While a good portion of the documentation -is written by hand and maintained in the -.Pa man/ -directory, a substantial amount of documentation is stored in the C header -files that define Telodendria's APIs. -This recipe runs -.Xr hdoc 1 -on each header to generate man pages for them. The man pages are place in -a directory that's already in your man path. -.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 built binary with the data directory of -.Pa data/ -in the current 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. 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 license -Update the copyright comments in every C source and header file using the -contents of the -.Pa LICENSE.txt -file. This recipe will also add the license header to new headers and C -sources that show up. -.It format -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 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 PREFIX -When installing/uninstalling Telodendria, the systeme prefix to use. This -defaults to -.Pa /usr/local . -.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. -.It Ev LD_EXTRA -The common, well-known compilers support a number of extra flags that -smaller, niche compilers probably will not. This variable holds those -flags, so if you are compiling with a small, lesser known compiler, you -can set this to an empty string to disable the extra flags. -.Pp -.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 TLS_IMPL -Set the TLS implementation library to use for Telodendria's TLS -support. Consult -.Xr Tls 3 -for a list of supported implementations. Implementations should be -specified by name in all uppercase. -.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 BUGS -.Nm -unconditionally exits with code 0, even if errors occurred. Furthermore, -recipes are run unconditionally, regardless of whether or not any recipes -before have failed. diff --git a/man/man1/tt.1 b/man/man1/tt.1 deleted file mode 100644 index 3b83bf5..0000000 --- a/man/man1/tt.1 +++ /dev/null @@ -1,34 +0,0 @@ -.Dd $Mdocdate: April 29 2023 $ -.Dt TT 1 -.Os Telodendria Project -.Sh NAME -.Nm tt -.Nd Make authenticated Matrix requests. -.Sh SYNPOSIS -.Nm -.Op request-path -.Sh DESCRIPTION -.Nm -is an extremely simple wrapper over -.Xr http 1 -and -.Xr json 1 -that automatically registers a user and continues to log in as that -user. It obtains an access token that it uses to authenticate the -given request, and then logs out when the request has completed. It -also doesn't require the whole URL to be typed; only the path name -is needed. -.Sh ENVIRONMENT -.Bl -tag -.It Ev METH -The request method to use for the user-specified request. -.It Ev DATA -The data to pass to -.Xr http 1 . -This can either be a string, or a file. Consult the -.Xr http 1 -page for details. -.El -.Sh SEE ALSO -.Xr http 1 , -.Xr json 1