Imported documentation from snac 1.x.

1 files changed, 131 insertions, 0 deletions

diff --git a/doc/snac.5 b/doc/snac.5
new file mode 100644
index 0000000..a5311e4
--- /dev/null
+++ b/doc/snac.5
@@ -0,0 +1,131 @@
+.Dd $Mdocdate$
+.Dt SNAC 5
+.Os
+.Sh NAME
+.Nm snac
+.Nd message formatting and file format documentation
+.Sh DESCRIPTION
+The
+.Nm
+daemon processes messages from other servers in the Fediverse
+using the ActivityPub protocol.
+.Pp
+This manual describes the allowed formatting of note messages
+and the disk storage layout of
+.Nm
+server and user data. For the operation manual, see
+.Xr snac 1 .
+For the administration manual, see
+.Xr snac 8 .
+.Ss Message Formatting
+Message notes respect the entered new line breaks rigurously.
+A special subset of Markdown is allowed, including:
+.Bl -tag -width tenletters
+.It bold
+**text between two pairs of asterisks**
+.It italic
+*text between a pair of asterisks*
+.It code
+Text `between backticks` is formatted as code.
+.Bd -literal
+```
+/* text between lines with only three backticks is preformatted */
+int main(int argc, char *argv[])
+{
+    return 0;
+}
+
+```
+.Ed
+.It links
+Standalone URLs.
+.It quoted text
+Lines starting with >.
+.It User Mentions
+Strings in the format @user@host are requested using the Webfinger
+protocol and converted to links and mentions if something reasonable
+is found.
+.El
+.Pp
+HTML tags are left untouched. This is probably a bad idea that may
+change in future versions.
+.Pp
+.Ss Disk Layout
+This section documents version 1 of the disk storage layout. It's still
+subject to change.
+.Pp
+The base directory contains the following files and folders:
+.Bl -tag -width tenletters
+.It Pa server.json
+Server configuration.
+.It Pa user/
+Directory holding user subdirectories.
+.El
+.Pp
+Each user directory is a subdirectory of 
+.Pa BASEDIR/user/ ,
+has the user id as name and contains the following subdirectories and files:
+.Bl -tag -width tenletters
+.It Pa user.json
+User configuration file.
+.It Pa key.json
+SHA-1 secret/public key PEM data.
+.It Pa actors/
+This subdirectory stores cached 'Person' ActivityPub messages as JSON files. Each
+file name is an MD5 hash of the actor URL.
+.It Pa timeline/
+This subdirectory stores the user's timeline. Everytime a valid message arrives,
+it's stored in this directory as a JSON object. The file name spec is: a Unix
+timestamp followed by a hyphen followed by an MD5 of the message Id. Additionally,
+metadata for each message parent and children is stored under the '_snac' field;
+parent messages with new children are renamed with an updated timestamp so that
+the more recently updated thread is shown at the top. This directory is presented
+in the web interface in reverse file name order up to a maximum, hardcoded limit.
+These files are purged when they are considered old (this time can be changed by
+tweaking the server configuration).
+.It Pa local/
+This subdirectory stores all activities generated by this user as hardlinks to
+their analogue entries in the
+.Pa timeline/
+subdirectory. These files are never deleted.
+.It Pa followers/
+This subdirectory stores the 'Follow' ActivityPub message from each
+Fediverse user that is following this user as a JSON file. Each file name is
+an MD5 hash of the actor that is a follower of this user.
+.It Pa following/
+This subdirectory stores the 'Follow' (not yet confirmed) or the 'Accept'
+(confirmed) ActivityPub message for each actor that is being followed. Each file
+name is an MD5 hash of the actor.
+.It Pa muted/
+This directory contains files which names are MD5 hashes of muted actors. The
+content is a line containing the actor URL.
+Messages from these actors will be ignored on input and not shown in any timeline.
+.It Pa queue/
+This directory contains the output queue of messages generated by the user as
+JSON files. File names contain timestamps that indicate when the message will
+be sent. Messages not accepted by their respective servers will be re-enqueued
+for later retransmission until a maximum number of retries is reached,
+then discarded.
+.It Pa static/
+Files in this directory are served as-is when requested from the
+.Pa https://HOST/s/...
+URL path. A special file named
+.Pa style.css
+can contain user-specific CSS code to be inserted into the HTML of the
+web interface.
+.It Pa history/
+This directory contains generated HTML files. They may be snapshots of the
+local timeline in previous months or other cached data.
+.It Pa archive/
+This directory stores all input/output traffic of ActivityPub messages. There
+is a different file for each day. This information is only stored if
+.Nm
+is run with a debug level >= 1.
+.El
+.Sh SEE ALSO
+.Xr snac 1 ,
+.Xr snac 8
+.Sh AUTHORS
+.An grunfink
+.Sh LICENSE
+See the LICENSE file for details.