From cf18fc2d786c572c64a9eb24934131ca5b6460d7 Mon Sep 17 00:00:00 2001 From: Ted Unangst Date: Wed, 9 Oct 2019 14:30:55 -0400 Subject: [PATCH] add some more manual stuff --- docs/activitypub.7 | 144 +++++++++++++++++++++++++++++++++++++++++++++ docs/hfcs.1 | 78 ++++++++++++++++++++++++ docs/honk.1 | 78 +++++------------------- docs/honk.8 | 2 - docs/intro.1 | 43 ++++++++++++++ 5 files changed, 280 insertions(+), 65 deletions(-) create mode 100644 docs/activitypub.7 create mode 100644 docs/hfcs.1 create mode 100644 docs/intro.1 diff --git a/docs/activitypub.7 b/docs/activitypub.7 new file mode 100644 index 0000000..a509136 --- /dev/null +++ b/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" diff --git a/docs/hfcs.1 b/docs/hfcs.1 new file mode 100644 index 0000000..6f3a42d --- /dev/null +++ b/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. diff --git a/docs/honk.1 b/docs/honk.1 index 621054a..e8da447 100644 --- a/docs/honk.1 +++ b/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 -.Dq it's honking time -to activate the honk form. -.Pp -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 +Refer to the +.Xr honk 5 +section of the manual. +.Ss HFCS 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 diff --git a/docs/honk.8 b/docs/honk.8 index 3f42195..bb2030f 100644 --- a/docs/honk.8 +++ b/docs/honk.8 @@ -19,8 +19,6 @@ .Sh NAME .Nm honk .Nd honk administration -.Sh SYNOPSIS -.Nm honk .Sh DESCRIPTION The .Nm diff --git a/docs/intro.1 b/docs/intro.1 new file mode 100644 index 0000000..cf44974 --- /dev/null +++ b/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.