Webmentions
===========

Webmentions (https://www.w3.org/TR/webmention/) are a mechanism by which
references between websites can be automatically maintained.

SSC's webmention processing is deeply experimental, and not ready for use.

A website somewhere may mention your site. It can notify your site using
webmentions. The webmention will say which page there mentions your site,
which page on your site gets the mention, when the mention was last changed,
and provide some contextual information. Although the mention may be in any
kind of online document, SSC can only manage mentions that are embedded in
HTML.

The idea is that if you use SSC to prepare your static website for your static
web server (as I do), it can also apply webmentions. However, SSC does not
offer a surrogate webserver to collect webmentions; it requires an external
mechanism to do so, such as a CGI script on your website's server. The headers
collected should be passed to SSC.

SSC then uses a series of templates to collect and format the reference and add
it to your site. The templates cover each type of change that may arrive with
a webmention notification: add, change, delete, plus unchanged. SSC uses these
templates to make the appropriate alternation to the appropriate webpage.

Webmentions can also be directly specified using switches.

As you might guess, there are a good number of switches needed to control SSC's
webmention processing. These deal with incoming mentions:

--wmin.accept           Process incoming webmentions.

--wmin.no-accept        Ignore incoming webmentions.

--wmin.datapath XXX     Path for incoming webmention headers files. SSC will
                        consume files found here.

--wmin.mention XXX      Specify a webmention. XXX must be in decoded HTML
                        parameter format, containing source and target. For
                        example:
                        source=http://a.lan/s.htm&target=http://b.lan/t.htm

--wmin.stub XXX         When generating pages using templates containing
                        webmentions, add this text to the file stub (default:
                        "_ssc")

--wmin.template XXX     HTML snippets for using when adding templates. These
                        templates must be specified in the following order:
                            new, changed, deleted, unchanged
                        The default values are, respectively
                            new.tpl, changed.tpl, deleted.tpl, static.tpl
                        The snippets may contain the following pieces of text,
                        which will be substituted with the corresponding
                        webmention content:
                            {{source}}  URL of page with the mention
                            {{target}}  URL of page mentioned
                            {{content}} The HTML content of the mention
                            {{when}}    The date/time of the mention

--wmin.write XXX        When adding webmentions to your site, put them in this
                        path (default: --site.root).

Similarly, your site may mention other sites. SSC can notify these other sites
of the mentions. It keeps a cache of the notifications it has issued, to avoid
reissuing notifications.

--wmout.clear           SSC keeps a cache of webmention data already applied.
                        Delete it. This may mean external sites are renotified
                        of webmentions referencing them.

--wmout.no-clear        Retain the webmention cache.

--wmout.notify          Notify external sites of webmentions in your site.

--wmout.no-notify       Keep mum about webmentions in your site.

--wmout.secret XXX      Set the webmention secret. Be aware that this is not
                        the world's most secure mechanism for secret
                        management.
