Atom RSS on gopher made easy
----------------------------

First how to do an atom feed by hand, the easy way.

Skippable intro to those who know----------
An Atom Feed is a file that contains data about some files,
posts, videos, music or whatever that you want to share
around.  That data is in a format called XML.  And XML is
like the german cousin of HTML; meaning it's much more
strict. Much more strict, let me reiterate, so you have
to be very careful with it, using all the required tags,
closing them properly, etc.

An RSS file is about the same thing, but older, more
popular for that reason, but uses different tags.

To edit an Atom (or RSS) file you need a plain text
editor sucha as 'ed' :) vi/vim, notepad, nano.  I use
ed, but that's me, really.

Once you have a feed (be it Atom or RSS) anybody can
feed it :) into a rss reader and access it that way.
The rss/feed reader will notify the user when your
site has been updated and show the content.  Just use
them yourself, they save a lot of time.

Enough intro.

Part I An easy Atom feed ------------------------------

OK, let's suppose you have a good old HTML site on the
web.  That's good, because it makes thing easier. Kids
these days have but forgotten gopher so it takes some
trickery to make a gopher feed work on modern readers.
They should work, but the reader isn't ready for them.
I'll tell you of my trickery later, let's dive into
the easy part first

An Atom feed needs to have data about two things

a) The feed itself: how it's named, where it's on the
Internet and when it was updated

b) The entries, each contained how it's named, where
it is...

Let's start with the feed itself. 

<feed xmlns="http://www.w3.org/2005/Atom">
<title>Your feed title</title>
<link href="https://link/to/your/atom.xml" rel="self"/>
<updated>2025-05-18T12:47:04+01:00</updated>
<author>
<name>Your Name</name>
<email>your@email.tla</email>
</author>
<id>https://your-site-url.com</id>

<entry>
Some stuff, tell you later...
</entry>

<entry>
another entry, another stuff
</entry>

</feed> 

That seems pretty easy, Âright? The tricky part is the
<updated></updated> tag. Atom dates need to be in a very
specific format. (RSS use a different one, for
old-fashioned reasons, Atom dates make more sense)

This is not too hard YYYY-MM-DD then a T for "time",
I guess with HH:MM:SS and then your time zone deviation
from GMT.

If you don't publish that often, and you're laid back
enough to be like me, you can make your life easier
by doing something like

<updated>2025-05-20T00:00:00+00:00</updated>

And call it a day, or fill the hour and second with
the real info. Our gopher sites are not updated that
often that they usually need seconds.

There's a second reason of why the <updated> tag is
tricky. You'll add your entry, I'll show soon, but
you'll forget about updating the update tag of your
feed.  Then the reader won't get your new entry and
you'll scratch your head. So, take care.

Now, part b) The entries

For each entry you include this

<entry>
<title>Entry title for gopher content on sdf.org</title>
<link href="gopher://sdf.org:70/0/users/your_user/whatever.txt"/>
<id>gopher://sdf.org:70/0/users/your_user/whatever.txt</id>
<published>2025-02-15T00:00:00+00:00</published>
<updated>2025-02-16T00:00:00+00:00</updated>
<summary>This is my gopher entry</summary>
<content type="xhtml">
<div xmlns="http://www.w3.org/1999/xhtml">
<pre>
Your gopher content in plain text,
as it should be
</pre>
</content>
</entry>

<entry>
<title>Entry title for html content</title>
<link href="https://yoursite.com/entry.html"/>
<id>https://yoursite.com/entry.html</id>
<published>2025-02-15T00:00:00+00:00</published>
<updated>2025-02-16T00:00:00+00:00</updated>
<summary>This is my html entry</summary>
<content type="xhtml">
<div xmlns="http://www.w3.org/1999/xhtml">
<p>
Your html entry. This is tag is optional
for html sites, most feed readers will
fetch the content from your link tag
</p>
<p>
Don't forget to update your feed's
updated tag too!
</p>
</content>
</entry>

See we have two entries in this. Now, we will
need to close the feed tag by ending the whole 
thing with </feed>

DON'T FORGET TO CLOSE EVERY TAG ON XML OR IT
WON'T EVER WORK!!

Sorry for the shouting, my accumulated frustratons...

OK so we need
a) a title
b) a link
c) an id, for that the usual thing is to use the entry link
as well
d) two dates published and updated. They use the same format
as the entry's updated tag and do as they say
e) a summary of your entry

Now, about that content tag, you need that div to enclose
your content so that the html inside won't collide with the
xml outside.... 

This <content> tag is not compulsory, and every feed reader
I know will just download the content from the <link> tag
just fine. However, if your content is in gopher... most
feed readers aren't friends with gopher. Shame on them!
So just include your content

Last, but not least, close your <feed> tag by </feed> and
update your feed's updated tag. Not sorry to reiterate,
you'll thank me later.

The trickery -------------

Now, for atom feeds to work for gopher site you have two
options.

Just host it in your gopher hole and hope the user will
have a reader able to process gopher sites or

Host it on the web, somewhere, in a https site of yours,
for example. If you do that it will be more accessible
to more people, specially those who aren't keen to gopher
(but we can convert them in due time)

^_^

That's literally all. Some links

=> https://validator.w3.org/feed/ tito validate your feed
   and get some error messages so you know what to fix

=> https://validator.w3.org/feed/docs/ The documentation

You can do anything if you read the docs.
2025-05-20 10:17:40