diff --git a/.gitignore b/.gitignore index 422a0f1..7f1e762 100644 --- a/.gitignore +++ b/.gitignore @@ -15,3 +15,6 @@ ayaya #ctags tags + +# Whitelists +!etc/* diff --git a/etc/man/man1/parsee-adminify.1 b/etc/man/man1/parsee-adminify.1 new file mode 100644 index 0000000..cc29132 --- /dev/null +++ b/etc/man/man1/parsee-adminify.1 @@ -0,0 +1,39 @@ +." The last field is the codename, by the way. +." ALL MANPAGES FOR PARSEE ARE UNDER PUBLIC DOMAIN +.TH parsee-adminify 1 "Parsee Utility" "phantasmagoria" + +.SH NAME +parsee-adminify - bootstrap an admin to a new Parsee server + +.SH SYNOPSIS +parsee-adminify +.B [DB path] +.B [user] + +.SH DESCRIPTION +.I parsee-adminify +is a tool to add/list the Parsee administrator list. It currently only +allows you to see/add admins to it, using simplified globrules. + +.SH OPTIONS +.TP +.B [DB path] +The DB directory this tool will use to manage administrators. +.TP +.B [user] +If set, adds the glob +.I [user] +as a Parsee administrator. Otherwise, lists all administrators in +the Parsee instance. + +.SH BUGS +.PP +Currently not available with flat-based backends. + +.SH LICENSE +Unlike Parsee, +.B parsee-adminify +is under the CC0/PD. + +.SH SEE ALSO +.B parsee-config(1), parsee-aya(1), parsee(1) diff --git a/etc/man/man1/parsee-aya.1 b/etc/man/man1/parsee-aya.1 new file mode 100644 index 0000000..c688102 --- /dev/null +++ b/etc/man/man1/parsee-aya.1 @@ -0,0 +1,40 @@ +." The last field is the codename, by the way. +." ALL MANPAGES FOR PARSEE ARE UNDER PUBLIC DOMAIN +.TH parsee-aya 1 "Parsee Utility" "phantasmagoria" + +.SH NAME +parsee-aya - generate some nice Ayaya! documentation + +.SH SYNOPSIS +parsee-aya +.B [-i HEADER] +.B [-o HTML] +.B [-C STYLESHEET] +.B [-p NAME] + +.SH DESCRIPTION +.I parsee-aya +is a tool to generate Ayadocs(HTML documentation) from a formatted +header file. See a Parsee header file for an example of the inner usage. + +.SH OPTIONS +.TP +.BR -i HEADER +The input header file to process out. +.TP +.BR -o HTML +The HTML file to write out the Ayadoc. +.TP +.BR -C STYLESHEET +A stylesheet file to use for Ayadocs. +.TP +.BR -p NAME +The project's name. If unavailable, defaults to Ayaya! + +.SH LICENSE +Unlike Parsee, +.B parsee-aya +is under the CC0/PD. + +.SH SEE ALSO +.B parsee-config(1), parsee-adminify(1), parsee(1) diff --git a/etc/man/man1/parsee-config.1 b/etc/man/man1/parsee-config.1 new file mode 100644 index 0000000..d21fca6 --- /dev/null +++ b/etc/man/man1/parsee-config.1 @@ -0,0 +1,90 @@ +." The last field is the codename, by the way. +." ALL MANPAGES FOR PARSEE ARE UNDER PUBLIC DOMAIN +.TH parsee-config 1 "Parsee Utility" "phantasmagoria" + +.SH NAME +parsee-config - generate a basic configuration file + +.SH SYNOPSIS +parsee-config +.B [-H HOMESERVER_NAME] +.B [-s SHARED_SECRET] +.B [-m MEDIA_URL] +.B [-J JABBER_HOST] +.B [-p JABBER_PORT] +.B [-d DATABASE] +.B [-S DATABASE size] + +.SH DESCRIPTION +.I parsee-config +creates a basic configuration file to initialise a Parsee instance with the +given input flags, and makes a basic database. A basic example of +.I parsee-config +would be this(for a blow.hole server, with a xmpp.blow.hole JCP on Prosody, +and a 128MB LMDB backend) +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ parsee-config \\ + -d '/var/lib/parsee' \\ + -m 'https://pmedia.blow.hole' \\ + -H 'blow.hole' \\ + -s 'The Dark Shared Secret' \\ + -J 'xmpp.blow.hole' \\ + -S 128 +.fi +.if n \{\ +.RE +.\} +.sp + +.SH OPTIONS +.TP +.BR -H HOMESERVER_NAME +.I HOMESERVER_NAME +points to the homeserver name, without delegation (which is autosensed). +For example, if you except Parsee users to be on +.IR @something:blow.hole +, then it should be set to +.IR blow.hole . +.TP +.BR -s SHARED_SECRET +.I SHARED_SECRET +is a shared secret known by Parsee and the XMPP component to authenticate. +.TP +.BR -m MEDIA_URL +.I MEDIA_URL +is an optional field used by Parsee as an address that points to Matrix +media. It must be publicly accessible (behind a reverse proxy to HTTP:7642) +.TP +.BR -J JABBER_HOST +.I JABBER_HOST +is used as the component host for Parsee. +.TP +.BR -p JABBER_PORT +.I JABBER_PORT +is used as the component post for Parsee. Parsee uses it alongside +.I JABBER_HOST +to connect to +.I JABBER_HOST:JABBER_PORT +over TCP. +.TP +.BR -d DATABASE +The directory inwhich Parsee stores its database(LMDB/flat-file). Whenever the +database is flat or LMDB is dictated by the presence of the -S flag, and +whenever Cytoplasm has LMDB enabled. +.TP +.BR -S SIZE +If set, enables LMDB in Parsee, and sets its max DB size to +.BR SIZE MiB . + + +.SH LICENSE +Unlike Parsee, +.B parsee-config +is under the CC0/PD. + +.SH SEE ALSO +.B parsee-aya(1), parsee-adminify(1), parsee(1) diff --git a/etc/man/man1/parsee.1 b/etc/man/man1/parsee.1 new file mode 100644 index 0000000..bad9ff6 --- /dev/null +++ b/etc/man/man1/parsee.1 @@ -0,0 +1,118 @@ +." The last field is the codename, by the way. +." ALL MANPAGES FOR PARSEE ARE UNDER PUBLIC DOMAIN +.TH parsee 1 "Parsee Utility" "phantasmagoria" + +.SH NAME +parsee - the jealous XMPP-Matrix bridge + +.SH SYNOPSIS +parsee +.B [-J num] +.B [-H num] +.B [-C file] +.B [-g] +.B [-v] +.B [-h] + +.SH DESCRIPTION +Parsee is a +.B bridging program +, that is, it connects two chat protocols together (here, XMPP/Jabber, +and Matrix). +.PP +As such, a user on XMPP can communicate with Matrix users, and +vice-versa with it. +.PP +Currently, Parsee is under +.BI beta . +This means that it is still subject to bugs, flaws, and may change in a +backwards-incompatible manner at any time. + +.SH FIRST RUN +To start with a new install of Parsee(assuming you have a homeserver +with AS support and a XMPP server with JCP support, and that you know +the shared secret/domain for that component. Guides for that are +outside the scope of this manpage.), start by running +.B parsee-config(1) +with the flags provided in it, according to your configuration. +.PP +This should generate a +.I parsee.json +file, which is the configuration files for Parsee, and a directory where +the Parsee database may reside. You can then run +.I parsee -g +in that directory, which should generate a +.I parsee.yaml +file, this time with the generated AS configuration file, which you can +apply to your homeserver(how is implementation-dependent, but it is +generally a matter of modifying a configuration file to add the path +to such file). + +.SH OPTIONS +.TP +.BR -J num +Set the number of threads used for XMPP stanza processing to +.I num\[char46] +.TP +.BR -H num +Set the number of threads used for HTTP request processing to +.I num\[char46] +.TP +.BR -C file +Sets the configuration JSON path to +.I file\[char46] +.PP +Defaults to +.I parsee.json +if none can be found. +.TP +.BR -g +Generates a +.I parsee.yaml +file to be used as an Application-Service entry within Matrix, and +exits. +.TP +.BR -v +Verbose logging of Parsee's behaviour. Recommended when testing Parsee +for bugs/hints. +.TP +.BR -h +Prints the command list with descriptions. + +.SH BUGS +.PP +Sometimes Parsee will not respond to ^C requests properly, which +causes a system administrator to have to invoke SIGKILL. +.PP +Parsee seems to grow slowly in memory usage when messages are bridged +which, in the long run, could cause a memory error. All of the memory is +tracked, however, which means that this isn't exactly a leak. +.PP +Some important features still aren't implemented yet(e.g being able to join +a MUC from XMPP) + +.SH CHATROOMS +You may talk about Parsee on these rooms(on Matrix and XMPP): +.RE +.IP xmpp:parsee@conference.monocles.eu?join +for XMPP, which is bridged along Matrix +.IP #parsee:tedomum.net +for Matrix, which is bridged along Parsee +.RS + +.SH AUTHORS +." Contributors, feel free to put your names here in a PR, as long as +." it is acceptable +. PP +.BR LDA: +main maintainer of Parsee, accessible over XMPP at lda@freetards.xyz +and over Matrix as @fourier:ari.lt. + +.SH LICENSE +Parsee is available under the AGPL3, but has some code under CC0/PD, and +some from Cytoplasm itself. Please see +.I https://git.kappach.at/lda/Parsee +for more information. + +.SH SEE ALSO +.B parsee-config(1), parsee-adminify(1), parsee-aya(1)