honk/docs/honk.1

.\"
.\" 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 HONK 1
.Os
.Sh NAME
.Nm honk
.Nd federated status conveyance
.Sh DESCRIPTION
The
.Nm
utility processes federated status updates and other microblog activities.
This is the user manual.
For administration, see
.Xr honk 8 .
For other documentation, refer to the
.Xr intro 1 .
.Pp
This manual is still incomplete.
It'll get there eventually.
.Ss Honkers
Initially, there won't be much to see after logging in.
In order to receive regular updates from other users, they must first
be added to one's honker collection.
Begin at the
.Pa honkers
tab.
The
.Ar url
field is required.
Either of two forms are accepted, the user's handle (or webfinger) or their
ActivityPub actor URL.
.Pp
.Dl @user@example.social
.Dl https://example.social/users/user
.Pp
The
.Ar name
field is optional and will be automatically inferred.
The
.Ar notes
field is reserved for user remarks.
Fellow honkers may be added to one or more
.Ar combos
to suit one's organizational preferences.
These are accessed via the
.Pa combos
tab and allow easy access to particular groupings.
The special combo name of one hyphen
.Sq -
will exclude a honker's posts from the primary feed.
.Pp
It is also possible to skip subscribing.
In this case, regular posts are not received, but replies and posts fetched
via other means will appear in the relevant combos.
.Pp
In addition to honkers, it is possible to subscribe to a hashtag collection.
(Where supported.)
Enter the collection URL for
.Ar url .
.Pp
Separately, hashtags may be added to a combo by creating a honker with a
.Ar url
of the desired hashtag (including #).
Several hashtags may thus be collected in a single combo.
.Ss Viewing
The primary feed is accessed via the
.Pa home
tab.
It will contain posts from all honkers except those specifically excluded.
Posts mentioning the user, both followed and not, are collected under the
.Pa @me
tab.
Other feeds include
.Pa first
which excludes replies, the user defined options under the
.Pa combos
subheading, and the
.Pa events
page which lists only events.
.Pp
Individual honks contain a visual representation of the honker's ID,
their name, the activity (with a link back to origin), a link to the
parent post if applicable, and the convoy (thread) identifier.
A red border indicates the honk is not public.
Screenshot below.
.Pp
.Lk screenshot-honk.png screenshot of one honk
.Pp
Available actions are:
.Bl -tag -width tenletters
.It Ic bonk
Share with followers.
Not available for nonpublic honks.
.It Ic honk back
Reply.
.It Ic mute
Mute this entire thread.
Existing posts are hidden, and future posts will not appear in any feed.
.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 Ic ack
Acknowledge reading this post.
Typically if it's a reply to one's own post.
.It Ic save
Save this honk to the
.Pa saved
tab to find later.
.It Ic untag me
Sometimes a thread goes on entirely too long.
Untag will hide further replies to the selected post, but without muting the
entire thread.
Replies higher in the tree are still received.
.It Ic edit
Change it up.
Alas, Update activities do not federate reliably.
.Ss Refresh
Clicking the refresh button will load new honks, if any.
New honks will be subtly highlighted.
.El
.Ss Honking
Refer to the
.Xr honk 5
section of the manual for details of honk composition.
.Ss Search
Find old honks.
It's basic substring match with a few extensions.
The following keywords are supported:
.Bl -tag -width honker
.It site
Substring match on the post domain name.
.It honker
Exact match, either AP actor or honker nickname.
.It -
Negate term.
.El
.Pp
Example:
.Dl honker:goose big moose -footloose
This query will find honks by the goose about the big moose, but excluding
those about footloose.
.Ss Filtering
Sometimes other users of the federation can get unruly.
The honk filtering and censorship system,
.Xr hfcs 1 ,
can be of great use to restore order to one's timeline.
Accessed via the
.Pa filters
menu item.
.Ss Xzone
The
.Pa xzone
page lists recently seen honkers that are not otherwise tracked.
It also allows the import of external objects via URL, either individual
posts or actor URLs, in which case their recent outbox is imported.
.Ss Account
It's all about you.
An avatar may be selected from the
.Pa funzone
by adding
.Dq avatar: filename.png
to one's profile info.
If truly necessary.
.Pp
Some options to customize the site appearance:
.Bl -tag -width skinny
.It skinny
Use a narrower column for the main display.
.It apple
Prefer Apple links for maps.
The default is OpenStreetMap.
.El
.Sh ENVIRONMENT
.Nm
is designed to work with most browsers, but for optimal results it is
recommended to use a
2015 or later Thinkpad X1 Carbon with 2560x1440 screen running
.Ox
and chromium at 150% scaling with the dwm window manager.
This will enable the main menu to line up just right.
.Sh SEE ALSO
.Xr intro 1 ,
.Xr honk 8
.Sh STANDARDS
.Pp
.Lk https://www.w3.org/TR/activitypub/ "ActivityPub"
.Pp
.Lk https://www.w3.org/TR/activitystreams-vocabulary/ "Activity Vocabulary"
.Sh HISTORY
Started March 2019.
.Sh AUTHORS
.An Ted Unangst Lk https://honk.tedunangst.com/u/tedu @tedu@honk.tedunangst.com
.Sh CAVEATS
Completing some operations, such as subscribing to new honkers, requires an
aptitude for clipboard use and tab switching along with a steady hand.
For the most part, these are infrequent operations, but they are also the
first operations new users encounter.
This is not ideal.
.Pp
The ActivityPub standard is subject to interpretation, and not all
implementations are as enlightened as
.Nm .
.Sh BUGS
It's a feature.