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.

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 @@
	1	.Dd $Mdocdate$
	2	.Dt SNAC 5
	3	.Os
	4	.Sh NAME
	5	.Nm snac
	6	.Nd message formatting and file format documentation
	7	.Sh DESCRIPTION
	8	The
	9	.Nm
	10	daemon processes messages from other servers in the Fediverse
	11	using the ActivityPub protocol.
	12	.Pp
	13	This manual describes the allowed formatting of note messages
	14	and the disk storage layout of
	15	.Nm
	16	server and user data. For the operation manual, see
	17	.Xr snac 1 .
	18	For the administration manual, see
	19	.Xr snac 8 .
	20	.Ss Message Formatting
	21	Message notes respect the entered new line breaks rigurously.
	22	A special subset of Markdown is allowed, including:
	23	.Bl -tag -width tenletters
	24	.It bold
	25	text between two pairs of asterisks
	26	.It italic
	27	text between a pair of asterisks
	28	.It code
	29	Text `between backticks` is formatted as code.
	30	.Bd -literal
	31	```
	32	/* text between lines with only three backticks is preformatted */
	33	int main(int argc, char *argv[])
	34	{
	35	return 0;
	36	}
	37
	38	```
	39	.Ed
	40	.It links
	41	Standalone URLs.
	42	.It quoted text
	43	Lines starting with >.
	44	.It User Mentions
	45	Strings in the format @user@host are requested using the Webfinger
	46	protocol and converted to links and mentions if something reasonable
	47	is found.
	48	.El
	49	.Pp
	50	HTML tags are left untouched. This is probably a bad idea that may
	51	change in future versions.
	52	.Pp
	53	.Ss Disk Layout
	54	This section documents version 1 of the disk storage layout. It's still
	55	subject to change.
	56	.Pp
	57	The base directory contains the following files and folders:
	58	.Bl -tag -width tenletters
	59	.It Pa server.json
	60	Server configuration.
	61	.It Pa user/
	62	Directory holding user subdirectories.
	63	.El
	64	.Pp
	65	Each user directory is a subdirectory of
	66	.Pa BASEDIR/user/ ,
	67	has the user id as name and contains the following subdirectories and files:
	68	.Bl -tag -width tenletters
	69	.It Pa user.json
	70	User configuration file.
	71	.It Pa key.json
	72	SHA-1 secret/public key PEM data.
	73	.It Pa actors/
	74	This subdirectory stores cached 'Person' ActivityPub messages as JSON files. Each
	75	file name is an MD5 hash of the actor URL.
	76	.It Pa timeline/
	77	This subdirectory stores the user's timeline. Everytime a valid message arrives,
	78	it's stored in this directory as a JSON object. The file name spec is: a Unix
	79	timestamp followed by a hyphen followed by an MD5 of the message Id. Additionally,
	80	metadata for each message parent and children is stored under the '_snac' field;
	81	parent messages with new children are renamed with an updated timestamp so that
	82	the more recently updated thread is shown at the top. This directory is presented
	83	in the web interface in reverse file name order up to a maximum, hardcoded limit.
	84	These files are purged when they are considered old (this time can be changed by
	85	tweaking the server configuration).
	86	.It Pa local/
	87	This subdirectory stores all activities generated by this user as hardlinks to
	88	their analogue entries in the
	89	.Pa timeline/
	90	subdirectory. These files are never deleted.
	91	.It Pa followers/
	92	This subdirectory stores the 'Follow' ActivityPub message from each
	93	Fediverse user that is following this user as a JSON file. Each file name is
	94	an MD5 hash of the actor that is a follower of this user.
	95	.It Pa following/
	96	This subdirectory stores the 'Follow' (not yet confirmed) or the 'Accept'
	97	(confirmed) ActivityPub message for each actor that is being followed. Each file
	98	name is an MD5 hash of the actor.
	99	.It Pa muted/
	100	This directory contains files which names are MD5 hashes of muted actors. The
	101	content is a line containing the actor URL.
	102	Messages from these actors will be ignored on input and not shown in any timeline.
	103	.It Pa queue/
	104	This directory contains the output queue of messages generated by the user as
	105	JSON files. File names contain timestamps that indicate when the message will
	106	be sent. Messages not accepted by their respective servers will be re-enqueued
	107	for later retransmission until a maximum number of retries is reached,
	108	then discarded.
	109	.It Pa static/
	110	Files in this directory are served as-is when requested from the
	111	.Pa https://HOST/s/...
	112	URL path. A special file named
	113	.Pa style.css
	114	can contain user-specific CSS code to be inserted into the HTML of the
	115	web interface.
	116	.It Pa history/
	117	This directory contains generated HTML files. They may be snapshots of the
	118	local timeline in previous months or other cached data.
	119	.It Pa archive/
	120	This directory stores all input/output traffic of ActivityPub messages. There
	121	is a different file for each day. This information is only stored if
	122	.Nm
	123	is run with a debug level >= 1.
	124	.El
	125	.Sh SEE ALSO
	126	.Xr snac 1 ,
	127	.Xr snac 8
	128	.Sh AUTHORS
	129	.An grunfink
	130	.Sh LICENSE
	131	See the LICENSE file for details.