summaryrefslogtreecommitdiff
path: root/gmi2email.1.pod
blob: d5623f9f83de7681d6e40309eb72a02b9af8003d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
=head1 NAME

gmi2email - subscribe to gemlogs and read individual Gemini pages by e-mail

=head1 SYNOPSIS

B<gmi2email> [I<OPTIONS>] [I<URI or FILE>] ...

=head1 DESCRIPTION

B<gmi2email> fetches pages served using the Gemini protocol, converts them to
e-mail messages, and then sends those messages.  It is mainly useful for
subscribing to Gemini logs ("gemlogs") by e-mail, like rss2email(1).
B<gmi2email> fetches, converts and sends all URIs and files containing
text/gemini content specified on the command line.

=head2 TYPICAL USAGE

1. Ensure you have a working MTA: B<gmi2email> will use the sendmail(1)
command to send mail.

2. Create B<~/.config/mailscripts/gmi2email.config> with content like this:

=over 4

    from = rss@example.com
    to = your_email@example.com
    inline_images = 1

=back

3. Create B<~/.config/mailscripts/gmi2email.subscriptions> with some feed
URIs, e.g.

=over 4

    gemini://example.com/my_cool_gemlog/
    gemini://example.com/other_cool_gemlog/feed.xml

=back

4. Just once, execute

=over 4

    % gmi2email --subscriptions --no-send

=back

5. Periodically, execute

=over 4

    % gmi2email --subscriptions

=back

=head1 OPTIONS

=over 4

=item B<--subscriptions>[=I<FILE>]

In addition to mailing any URIs/files specified on the command line, check
subscribed gemlogs for new posts and send those too.  Useful in a crontab.

We support the subscription mechanism described at
<gemini://gemini.circumlunar.space/docs/companion/subscription.gmi> as well as
Atom feeds.

B<gmi2email> looks for a file with a list of gemini:// URIs to check for new
posts, one per line, in I<FILE>, or if that is not set, in
B<$XDG_CONFIG_HOME/mailscripts/gmi2email.subscriptions>, or if XDG_CONFIG_HOME
is not set, it falls back to trying to read
B<~/.config/mailscripts/gmi2email.subscriptions>.  Lines beginning with '#'
are treated as comments and ignored.

=item B<--inline-images>

Download and inline any images included in the post.

=item B<--no-send>

Don't actually send any mail.  Intended when you just added some new
subscriptions and want to avoid receiving all the old posts you've already
read.

=item B<--from=>I<ADDRESS>

Set the From: address, overriding the configuration file.

=item B<--to=>I<ADDRESS>

Set the To: address, overriding the configuration file.

=back

=head1 CONFIGURATION

B<gmi2email> tries to read configuration from the file
B<$XDG_CONFIG_HOME/mailscripts/gmi2email.config>, or if XDG_CONFIG_HOME is not
set, it falls back to trying to read
B<~/.config/mailscripts/gmi2email.config>.

The format is I<key = value>, one per line.  The following
configuration keys are supported:

=over 4

=item B<from>

Set the From: address.

=item B<to>

Set the To: address.

=item inline_images

Set to 1 to implicitly pass B<--inline-images>.

=back

=head1 SEE ALSO

<https://gemini.circumlunar.space/>

=head1 AUTHOR

B<gmi2email> was written by Sean Whitton <spwhitton@spwhitton.name>.