view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

You manage your subscriptions using the command-line, with Moku Pona.

You serve the resulting file using a Gemini server.

You read it all using your Gemini client.

**Table of Contents**

- [Limitations](#limitations)
- [License](#license)
- [Installation](#installation)
- [Dependencies](#dependencies)
- [The Data Directory](#the-data-directory)
- [Migration from 1.1](#migration-from-1-1)
- [List your subscriptions](#list-your-subscriptions)
- [Add a subscription](#add-a-subscription)
- [Remove a subscription](#remove-a-subscription)
- [Clean up the data directory](#clean-up-the-data-directory)
- [Update](#update)
- [Subscribing to feeds](#subscribing-to-feeds)
- [Publishing your subscription](#publishing-your-subscription)
- [Serving your subscriptions via Gemini](#serving-your-subscriptions-via-gemini)

## Limitations

When Moku Pona isn't watching a feed it can only detect changes on a page. Thus,
if there is an item that points to a phlog or blog, that's great. Sometimes
people put their phlog in a folder per year. If the Gopher menu lists each
folder and a date with the latest change, then that's great, you can use it.
Without it, you're in trouble: you need to subscribe to the item for the current
year in order to see changes, but when the next year comes around, you're
subscribed to the wrong item. Sometimes you're lucky and there will be a menu
somewhere with a timestamp for the last change. Use that instead. Good luck!

## License

GNU Affero General Public License

## Installation

Using `cpan`:

    cpan App::mokupona

Manual install:

    perl Makefile.PL
    make
    make install

## Dependencies

There are some Perl dependencies you need to satisfy in order to run this
program:

- [Modern::Perl](https://metacpan.org/pod/Modern%3A%3APerl), or `libmodern-perl-perl`
- [Mojo::IOLoop](https://metacpan.org/pod/Mojo%3A%3AIOLoop), or `libmojolicious-perl`
- [XML::LibXML](https://metacpan.org/pod/XML%3A%3ALibXML), or `libxml-libxml-perl`
- [URI::Escape](https://metacpan.org/pod/URI%3A%3AEscape), or `liburi-escape-xs-perl`
- [Encode::Locale](https://metacpan.org/pod/Encode%3A%3ALocale), or c<libencode-locale-perl>

## The Data Directory

Moku Pona keeps the list of URLs you are subscribed to in directory. It's
probably `~/.moku-pona` on your system.

- If you have the `MOKU_PONA` environment variable set, then that's your data
directory.
- If you have the `XDG_DATA_HOME` environment variable set, then your data
directory is `$XDG_DATA_HOME/moku-pona`.
- If you you have the `HOME` environment variable set, and you have a
`$HOME/.local` directory, then your data directory is
`$HOME/.local/moku-pona`.
- If you have the `HOME` environment variable set, then your data directory
is `$HOME/.moku-pona`.
- If you have the `APPDATA` environment variable set (Windows), then your
data directory is `$APPDATA/moku-pona`.
- The last option is to have the `LOGDIR` environment variable set.

The data directory contains a copy of the latest resources. The names of these
cache files are simply the URL with all the slashes replaced by a hyphen.

The `sites.txt` file is a file containing a gemtext list of links, i.e. entries
such as these:

    => gemini://alexschroeder.ch Alex Schroeder

The `updates.txt` file is a file containing a gemtext list of links based on
`sites.txt`, but with a timestamp of their last change, and with new updates
moved to the top. The ISO date is simply inserted after the URL:

    => gemini://alexschroeder.ch 2020-11-07 Alex Schroeder

In order to be at least somewhat backwards compatible with Moku Pona versions
1.1 and earlier, `sites.txt` may contain Gopher menu items. These are converted
to Gemini URLs during processing and thus the `updates.txt` file still contains
regular gemtext.

    1Alex Schroeder â­¾ â­¾ alexschroeder.ch â­¾ 70

As was said above, however, the recommended format is the use of URLs. Moku Pona
supports Gemini, Gopher, and the web (gemini, gopher, gophers, http, and https
schemes).

## Migration from 1.1

The best way to migrate your setup is probably to use the `list` subcommand
explained later, and to recreate your list of subscriptions. Then your
`sites.txt` file will use gemtext format.

    moku-pona list | grep "moku-pona add" > commands
    mv ~/.moku-pona/sites.txt ~/.moku-pona/sites.txt~
    sh commands

## List your subscriptions

    moku-pona list [names...]

This lists all your current subscriptions in a format that is suitable for a
shell script. Optionally, only list a subset of the lines. All lines are matched