~callum/gmsfn

7328149f2f59208ae26181a164cebc7791d95604 — Callum Brown 1 year, 3 months ago 2736f54
Add docs
2 files changed, 88 insertions(+), 0 deletions(-)

A doc/gmsfn.1.scd
A doc/gmsfn.5.scd
A doc/gmsfn.1.scd => doc/gmsfn.1.scd +36 -0
@@ 0,0 1,36 @@
gmsfn(1)

# NAME

gmsfn - feed builder for Gemini

# SYNOPSYS

*gmsfn* _path_

# DESCRIPTION

*gmsfn* keeps track of new links in Gemtext files served over the Gemini
protocol, the intended use case being easy access to new gemlog entries.

The result of the program is a Gemtext file that contains all the links present
in a given set of Gemini pages. When an output file already exists *gmsfn*
prepends any links not already present in it, so if run at a regular interval
*gmsfn* can be used to create an up-to-date feed of new links. *gmsfn* does not
care about what is in the output file or about the order of the links it
contains; the user may edit it however they see fit, but they should remember
that new links will always be added to the very top of the file.

The configuration file at the given _path_ specifies the output file and the
pages that should be monitored for new links. See *gmsfn*(5) for the
configuration syntax.

*gmsfn* uses *gmni*(1)'s TOFU system. If a certificate fingerprint is present
in your Gemini known_hosts file (probably at
~/.local/share/gemini/known_hosts) then the host will be trusted. If it is not
then a message will be printed to *stderr* and, provided that the certificate
is valid, the host will be trusted for a single request.

# SEE ALSO

*gmsfn*(5)

A doc/gmsfn.5.scd => doc/gmsfn.5.scd +52 -0
@@ 0,0 1,52 @@
gmsfn(5)

# NAME

gmsfn - configuration file format for *gmsfn*(1)

# SYNTAX

All files dealt with by *gmsfn*(1) use the lightweight markup language Gemtext,
which was designed for use with the Gemini protocol. For an introduction to
Gemtext see:++
gemini://gemini.circumlunar.space/docs/gemtext.gmi

*gmsfn* handles at least two files: a configuration file and at least one
output file. The configuration file specifies the paths to the output files
and gives a list of pages that are to be monitored for new links. The pages to
be monitored must be Gemtext and accessible over Gemini. The output files are
used to determine which links have not been seen before.

Output files are specified by using third-level headings: lines starting
with '###' followed by the path to the output file. The path may be given
relative to the directory the configuration file is in. When an output file
definition is detected, all links before the next definition are associated
with that file. This makes it possible to have separate feeds that are all
configured in the same file.

Gemtext pages to monitor are specified using the Gemtext link syntax: a line
starting with '=>' followed by a Gemini URL and an optional human friendly
label. The link should be accessible over the Gemini protocol (you can not use
*gmsfn* on local files) and redirects will *not* be followed. If provided, the
human friendly label will be prefixed to the labels for all links on the given
page. This could be used, for example, to show authors in the output file.

# EXAMPLE

```
this line will be ignored as it does not start with ### or =>

### /srv/gemini/feed.gmi
=> gemini://gemini.circumlunar.space/software/ Gemini Software
=> gemini://drewdevault.com Drew DeVault
=> gemini://gemini.circumlunar.space/users/gemlog/Amiga/ GemLog's Amiga Tales
=> gemini://gemlog.blue/users/sloum/ Sloum's gemlog

### questions.gmi
=> gemini://multiverse.thruhere.net/5q/index.gmi Bronzie's 5 Questions
=> gemini://gemini.circumlunar.space/users/christina/5Q.gmi Responses to Christina's 5 Questions
```

# SEE ALSO

*gmsfn*(1)