Once you've got slerm pointed at the right directory, it knows it's
own name and you've changed the dat directory's permissions to 775,
things are pretty simple.

To write a post, create a file in your favorite text editor.  The
first line should be the entry's title. The second line can be a
list of comma-separated tags, which get parsed and converted to a
link that when clicked, will display all posts containing that
tag. The format looks like this:

TITLE LINE
#Tags Linux,Sysadmin,Tips

Tags are not case-sensitive, but the space after the '#Tags' is
mandatory. Spaces around the commas get stripped. Spaces within tags
are not supported. Presently, the tag links are only displayed on
individual post pages.

Hit return twice to leave a gap between your tagline and your entry
and then type away.

You can also shorten your post, by adding this text on a line by
itself somewhere in your post:

--more--

On the index and archive pages, anything after this line is not
displayed, just a link that redirects to the full post. This will
cut down on the size of the main index page once you fill it with a
lot of posts.

Slerm will do its best to detect lines with gophermap-style links,
and display them as-is (rather than as inline-text). The server and
port are required. Here is an example:

0slerm.cgi       /users/slugmax/code/slerm-1.9.cgi        sdf.org        70
9slerm-1.9.tgz   /users/slugmax/code/slerm-1.9.tgz        sdf.org        70
IPalm IIIe	/users/slugmax/images/palmiiie.jpg	  sdf.org	 70

With the usual tab characters between line elements.

Note : In emacs, you can enter a literal TAB character in your
editing buffer by typing <ctrl>-q TAB. In vi/vim, from insert mode
use <ctrl-v> TAB.

When you're done, save your entry in your dat directory with a
format like FILENAME.post. If it doesn't end in ".post", slerm
ignores it. Make sure it's world readable. A quick "chmod 644
FILENAME.post" can do that for you (You can change this extension -
see the INSTALL document for an explanation, or just change the
$post_ext variable).

You can also use the provided helper utilities 'publish' and 'upd'
to manage posting and timestamps. With these utilities, it's
possible to have a directory hierarchy of posts and track timestamps
for each, as long as that hierarchy is 'copied' in your staging
area. For example, if you edit posts in ~/docs/phlog, you might have
two subdirectories under it, 'funstuff' and 'work', each containing
their own .post files. Then, in your ~/gopher/dat directory, you
would also have 'funstuff' and 'work' directories. Use relative
pathnames with these two tools, for example:

'publish -u -g -f funstuff/halloween.post'

Note that both utilities can also be used to maintain a
bloxsom/pybloxsom installation, but here we always use the '-g'
switch ('g' for 'gopher').

Here are some examples which should make their use clear:

----------------------- 
Publish 'firstpost.post' from your staging directory to the gopher
phlog directory:

slugmax@iceland:~/tmp> publish -g -f firstpost.post
Publishing firstpost.post to /arpa/ns/s/slugmax/gopher/dat/firstpost.post...

----------------------- 
Publish 'firstpost.post' from your gopher staging directory,
updating the timestamp cache at the same time:

slugmax@iceland:~> publish -u -g -f firstpost.post
Publishing firstpost.post to /arpa/ns/s/slugmax/gopher/dat/firstpost.post...
Updating the timestamp cache for firstpost.post [/arpa/ns/s/slugmax/bin/upd -g -u -f firstpost.post]...
Running touch -r /arpa/ns/s/slugmax/gopher/dat/firstpost.post /arpa/ns/s/slugmax/.gtstamps/firstpost.post

-----------------------
Publish 'firstpost.post' from your staging directory, force
overwriting of the original post, and also update the timestamp
cache to the new modification time:

slugmax@iceland:~> publish -u -g -o -f firstpost.post
Publishing firstpost.post to /arpa/ns/s/slugmax/gopher/dat, overwriting existing post as you requested...
Updating the timestamp cache for firstpost.post [/arpa/ns/s/slugmax/bin/upd -g -u -f firstpost.post]...
Running touch -r /arpa/ns/s/slugmax/gopher/dat/firstpost.post /arpa/ns/s/slugmax/.gtstamps/firstpost.post

-----------------------
Just update the timestamp cache with current post's mtime:

slugmax@iceland:~/tmp> upd -u -g -f firstpost.post
Running touch -r /arpa/ns/s/slugmax/gopher/dat/firstpost.post /arpa/ns/s/slugmax/.gtstamps/firstpost.post

-----------------------
Reset mtime on post to that stored in the cache - use this after
editing a post where you want to restore the original mtime:

slugmax@iceland:~/tmp> upd -g -f firstpost.post
Running touch -r /arpa/ns/s/slugmax/.gtstamps/firstpost.post /arpa/ns/s/slugmax/gopher/dat/firstpost.post

-----------------------

The upd script can also be run without the -f option, which acts
recursively on *all* posts it finds in your ~/gopher/dat directory,
so use this with care.

After that, you're done. Slerm handles the dating, displaying, and
archiving of your posts. It also handles the creation, maintenance,
and dating of your comment files, stored in "FILENAME.post.cmt".

One tip to help you when posting indented text or source code, be
sure to set your editor of choice to convert tabs to spaces. Lines
starting with <TAB> characters don't get displayed as 'inline text'
by the gopher server.

To customize:

To customize your header, footer or post divider, simply edit the
header.txt, footer.txt or div.txt file in your dat directory.

You can change the extension used to indicate posts by editing the
variable '$post_ext' in the script header. For example, set this to
'txt', if you have your editor configured to handle text files
specially (e.g. text-mode in Emacs).

To use as a static phlog maker, with a bit of effort:

Running a command at the command line like:

./slerm.cgi > phlog

will create a static front page linking to dynamically generated
posts and archives.

Similar prompts, such as:

./slerm.cgi archive1 > archive1
./slerm.cgi FILENAME.post > FILENAME.post

will create static pages of your archives and posts with a few
caveats.

If you are running prompts like "./slerm.cgi FILENAME.post >
FILENAME.post" in your dat directory you will overwrite your
original post which can make a mess of things, especially if you go
back to running slerm as a dynamic script.

If you do this, you need to edit each file to create the proper
links, changing things like:

1Older Posts	/users/YOUR_NAME/slerm.cgi?archive1
to
1Older Posts	/users/YOUR_NAME/archive1

Something like this will do the trick:

perl -pi -e 's{slerm\.cgi\?(.+?)\t}{$1}g' archive1

Caveats - once you have a lot of entries it would get to be a hassle
to create a new main page, new archive pages one new post page and
edit them all by hand each time you added a new post. And every time
someone posted a comment, you'd have to regenerate and re-edit the
post they commented on.
