add some more manual stuff

docs/activitypub.7

@@ -0,0 +1,144 @@
+.\"
+.\" Copyright (c) 2019 Ted Unangst
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate$
+.Dt ACTIVITYPUB 7
+.Os
+.Sh NAME
+.Nm activitypub
+.Nd notes about the honk implementation
+.Sh DESCRIPTION
+The
+.Xr honk 1
+utility processes status updates and other microblog activities using the
+.Nm ActivityPub
+protocol to exchange messages with other servers.
+The implementation is subject to interpretation, and not all implemntations
+behave in the same way.
+This document attempts to clarify honk's behavior.
+It is not intended to be a complete description of
+.Nm ActivityPub ,
+but may be useful as a guide to other implementors looking to interoperate.
+.Ss OBJECTS
+The following object or document types are supported.
+.Bl -tag -width tenletters
+.It Vt Note
+Fully supported.
+The default object type for honk.
+.It Vt Article
+Fully supported.
+.It Vt Page
+Supported.
+.It Vt Question
+Read only support.
+Appears similar to a Note.
+.It Vt Event
+Supported.
+Appears similar to a Note.
+Can be both created and received, but
+.Vt Invite
+ativities are ignored.
+.It Vt Video
+Limited support.
+.It Vt Audio
+Limited Support.
+.El
+.Pp
+Honk primarily supports HTML content, not markdown or other formats,
+with a wide range of permitted HTML tags in object
+.Fa content
+fields.
+The following tags are supported.
+.Bd -literal -offset indent
+a, img, span,
+div, h1, h2, h3, h4, h5, h6, hr,
+table, thead, tbody, th, tr, td, colgroup, col,
+p, br, pre, code, blockquote, q,
+samp, mark, ins, dfn, cite, abbr, address,
+strong, em, b, i, s, u, sub, sup, del, tt, small,
+ol, ul, li, dl, dt, dd
+.Ed
+.Pp
+The followin tag attributes are permitted.
+.Bd -literal -offset indent
+href, src, alt, colspan, rowspan
+.Ed
+.Ss ACTIVITIES
+The following activities are supported.
+.Bl -tag -width tenletters
+.It Vt Create
+Fully supported.
+.It Vt Announce
+Supported with share semantics.
+.It Vt Read
+Supported.
+Primarily used to acknowledge replies and complete threads, without
+additional semantics.
+.It Vt Follow
+Supported.
+.Vt Accept
+and
+.Vt Undo
+require that the original request be quoted, not referred to by URI.
+.It Vt Update
+Honk sends and receives
+.Vt Update
+activities.
+.It Vt Delete
+Does what it can.
+.It Vt Like
+Don't be ridiculous.
+.El
+.Ss METADATA
+The following additional object types are supported as
+.Fa tag
+or
+.Fa attachment .
+.Bl -tag -width tenletters
+.It Mention
+.It Emoji
+Inline text :emoji: with image replacement.
+.It Place
+Attached as a
+.Fa tag
+to
+.Vt Note
+and
+.Fa location
+to
+.Vt Event .
+Supports
+.Fa name ,
+.Fa url ,
+.Fa latitude ,
+and
+.Fa longitude .
+.It Document
+Plain text and images in jpeg, gif, png, and webp formats are supported.
+.El
+.Ss SECURITY
+Honk uses http signatures.
+.Ss WEBFINGER
+Honk implements the
+.Vt webfinger
+end point and will use it for @mention resolution.
+It is not required for federation.
+.Sh SEE ALSO
+.Xr honk 1
+.Sh STANDARDS
+.Pp
+.Lk https://www.w3.org/TR/activitypub/ "ActivityPub"
+.Pp
+.Lk https://www.w3.org/TR/activitystreams-vocabulary/ "Activity Vocabulary"

docs/hfcs.1

@@ -0,0 +1,78 @@
+.\"
+.\" Copyright (c) 2019 Ted Unangst
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate$
+.Dt HFCS 1
+.Os
+.Sh NAME
+.Nm hfcs
+.Nd honk filtering and censorship system
+.Sh DESCRIPTION
+The honk filtering and censorship system,
+.Nm hfcs ,
+controls what messages are seen and how they are presented to the user.
+Filter rules are based on series of matches and actions.
+.Pp
+The following match types are possible.
+All criteria must match.
+.Bl -tag -width include-audience
+.It Ar who
+Match an actor or domain name.
+Matches against
+.Fa Ar actor
+property.
+.It include audience
+Previous match is applied against
+.Fa to
+and
+.Fa cc
+fields as well.
+.It Ar text
+Regular expression match against the post
+.Fa content .
+.It Ar is announce
+Is announced (shared).
+.El
+.Pp
+The following actions may be applied.
+Multiple actions may be applied, but some are subsumed by others.
+.Bl -tag -width tenletters
+.It Ar reject
+Reject this message entirely.
+.It Ar skip media
+Don't include images or attachments.
+.It Ar hide
+Remove this message from most feeds.
+.It Ar collapse
+Show only a short summary with click to view content.
+.It Ar rewrite
+Rewrite message content, using
+.Ar replace
+replacement text.
+.El
+.Pp
+The
+.Ar text
+and
+.Ar rewrite
+fields are case insensitive word anchored regular expressions.
+Specifically, an argument
+.Ql re
+will be automatically rewritten as
+.Ql \\\b(?i:re)\\\b .
+.Sh SEE ALSO
+.Xr honk 1
+.Sh CAVEATS
+Not seeing is not erasing.

docs/honk.1

@@ -19,8 +19,6 @@
 .Sh NAME
 .Nm honk
 .Nd federated status conveyance
-.Sh SYNOPSIS
-.Nm honk
 .Sh DESCRIPTION
 The
 .Nm
@@ -29,7 +27,7 @@ This is the user manual.
 For administration, see
 .Xr honk 8 .
 .Pp
-This manual is very incomplete.
+This manual is still incomplete.
 It'll get there eventually.
 .Ss Following
 In order to receive regular updates from other users, one must first follow them.
@@ -73,82 +71,36 @@ Screenshot below.
 .Pp
 Available actions are:
 .Bl -tag -width tenletters
-.It bonk
+.It Ic bonk
 Share with followers.
 Not available for nonpublic honks.
-.It honk back
+.It Ic honk back
 Reply.
-.It mute
+.It Ic mute
 Mute this entire thread.
 Existing posts are hidden, and future posts will not appear in any feed.
-.It zonk
+.It Ic zonk
 Delete this post.
 When deleting one's own post, other servers will be requested to remove it,
 but this is unreliable.
-.It ack
+.It Ic ack
 Acknowledge reading this post.
 Typically if it's a reply to one's own post.
-.It edit
+.It Ic edit
 Change it up.
 Alas, Update activities do not federate reliably.
 .El
 .Ss Honking
-Begin by pressing the button marked
+Refer to the
-.Dq it's honking time
+.Xr honk 5
-to activate the honk form.
+section of the manual.
-.Pp
+.Ss HFCS
-One may attach a file to a post.
-Images are automatically rescaled and reduced in size for federation.
-A description, or caption, is encouraged.
-Text files are also supported as attachments.
-.Pp
-One may also check in to a location.
-The available fields, all optional, are
-.Ar name ,
-.Ar url ,
-.Ar latitude ,
-and
-.Ar longitude .
-By default, location data is rounded to approximately 1/500 decimal degree
-accuracy.
-Pressing the check in button a second time will refine this to more a
-precise location.
-.Pp
-A limited subset of markdown is supported, including bold, italics, quotes,
-and code blocks.
-URLs beginning with
-.Sq http
-or
-.Sq https
-will be autolinked.
-Mentioning a specfic user such as
-.Pq @user@example.social
-will send a copy of the message to them.
-When honking back, the author of the parent post is automatically mentioned.
-.Pp
-Threads from the tiny bird site may be included as quotes in a post via the
-.Ar hoot
-operator.
-.Dl hoot: https://twitter.com/tedunangst/status/835172824734175234
-.Pp
-Custom emoji may included via colon wrapping
-.Pq :hellsyeah: .
-A meme (sticker, reaction gif) may be included with the
-.Ar meme
-operator.
-.Dl meme: honk.mp4
-A full list of emoji and memes may be found in the
-.Pa funzone .
-.Pp
-There are no length restrictions, but remember, somebody is going to have
-to read this noise.
-When everything is at last ready to go, press the
-.Dq it's gonna be honked
-button.
-.Ss zonkzone
 Sometimes other users of the federation can get unruly.
-The zonkzone can be of great use to restore order to one's timeline.
+The honk filtering and censorship system,
+.Xr hfcs 1,
+can be of great use to restore order to one's timeline.
 .Sh SEE ALSO
+.Xr intro 1 ,
 .Xr honk 8
 .Sh STANDARDS
 .Pp

docs/honk.8

@@ -19,8 +19,6 @@
 .Sh NAME
 .Nm honk
 .Nd honk administration
-.Sh SYNOPSIS
-.Nm honk
 .Sh DESCRIPTION
 The
 .Nm

docs/intro.1

@@ -0,0 +1,43 @@
+.\"
+.\" Copyright (c) 2019 Ted Unangst
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate$
+.Dt INTRO 1
+.Os
+.Sh NAME
+.Nm intro
+.Nd introduction to honk documentation
+.Sh DESCRIPTION
+The
+.Nm
+utility processes status updates and other microblog activities.
+This is the index.
+.Pp
+.Bl -tag -width activitypubxxr
+.It Xr honk 1
+User manual.
+.It Xr hfcs 1
+Honk Filtering and Censorship System.
+.It Xr honk 5
+Honk composition.
+.It Xr activitypub 7
+ActivityPub implementation notes.
+.It Xr honk 8
+Administration manual.
+.El
+.Sh HISTORY
+Started March 2019.
+.Sh AUTHORS
+Ted Unangst.