Plog reviewed

Plog has recently seen a major overhaul, and I consider it finally usable for others.

I will try to add some explanations to aid in understanding the whole system. The following examples will probably be converted into part of README.md in the Plog suite. As soon as I will find sufficient time... `;-)

Please also have a look at the previous blog entry, introducing Plog!

New and Improved

only one configuration script, making upgrades much easier
scripts in one global directory, but configuration local to each working directory, allowing for independent projects
external conversion script for handling certain UTF8 characters (or whatever abbreviations or special chars)
better logging
transparent use of conversion scripts, permitting replacement by cat for pure plaintext mode

Examples

I use the plog suite now regularly for two different setups from one single installation.

E-Mail Newsletter

One project consists in a personal newsletter going to a handful of addresses. In its configuration ( .plog.rc ) stored in the project directory Newsletter, the values for the publication directories pubdirhtml and pubdirtext are set to '' so that they get ignored, and therefore no files are written into any publication directory.

A cronjob runs pubnext.sh Newsletter twice a week, resulting in two newsletters per week processed and sent. As long as I am working on one, I keep the word DRAFT at the beginning of its first line.

Newsletter looks like this:

A/
.plog.rc
_pubnext.html
_pubnext.log
_pubnext.txt
ad.txt
t150110-news.md
t150112-test.md

A is the archive directory where processed posts are saved. ad.txt contains the addresses of the newsletter recipients, and looks like

# addresses
jim@example.com
fred@example.org

The _pubnext.* files are for internal use by the scripts; _pubnext.log contains the detailed log.

The contents of .plog.rc look like this:

pubtext=''
lentext=24
indtext='gophermap'
indtexthead=''
pubhtml=''
lenhtml=12
indhtml='list.html'
indhtmltitle=""
rsshtml='rss.xml'
rsstitle='feed'
rssdesc='recent entries'
baselink='http://example.com'
subject='Newsletter:'
fprefix='t'
draft='DRAFT'
arch='Archiv'
htmlhead='<HTML><BODY>'
htmlfoot="</BODY><!-- generated by $myself --></HTML>"
logfile='_pubnext.log'
convert0="$mydir/convchars.sh"
convert1="$mydir/mrkdwn.pl"
convert2='lynx -display_charset=US-ASCII -force-html -dump'
mailer=mailx
tmpf1='_pubnext.html'
tmpf2='_pubnext.txt'
lockf='.pubnext.lock'

Blog

This blog itself is handled by a different project. It also has a newsletter section, but it is sending posts to just one of my own addresses, so that I can monitor its correct functioning.

A daily cronjob calls allpub.sh blog, which in turn repeatedly calls pubnext.sh on the working directory blog, and afterwards (re)generates the index files list.html (for the HTML/blog version) and gophermap (for the text/gopherlog) version, and in addition the feed rss.xml for the HTML version as well. These files are saved two levels above the working directory in ../../pubdirhtml/ and ../../pubdirtext.

To compartmentalize the scripts, there is an additional daily cronjob, which in turn updates the directories facing the internet. It is based on allsync.sh, which is also included in the Plog suite for reference.

The directory blog looks quite similar to the one in the previous section:

Archiv/
.plog.rc
_pubnext.html
_pubnext.log
_pubnext.txt
ad.txt
t15119-plog.md
template.md

The source text you are now reading was put into the file t15119-plog.md. When it will be processed, pubnext.sh will move it (via Git, see below) into the archive directory Archiv.

And here is the configuration script .plog.rc for this project:

adds='ad.txt'
pubtext='../../pubdirtext'
lentext=24
indtext='gophermap'
indtexthead='recent entries'
pubhtml='../../pubdirhtml'
lenhtml=12
indhtml='list.html'
indhtmltitle="Y's blog"
rsshtml='rss.xml'
rsstitle="Y's blog feed"
rssdesc='recent blog entries'
baselink='http://yargo.sdf.org/blog'
subject='(blogmonitor)'
fprefix='t'
draft='DRAFT'
arch='Archiv'
htmlhead='<HTML><BODY>'
htmlfoot="</BODY><!-- generated by $myself &mdash; 2015 YCB --></HTML>"
logfile='_pubnext.log'
convert0="$mydir/convchars.sh"
convert1="$mydir/mrkdwn.pl"
convert2='lynx -display_charset=US-ASCII -force-html -dump'
mailer=mailx
tmpf1='_pubnext.html'
tmpf2='_pubnext.txt'
lockf='.pubnext.lock'

Notes

Please keep in mind that the .plog.rc file in fact is a shell script, which will be executed ("sourced") by allpub.sh and pubnext.sh, and therefore strange things may happen if you do not correctly pair '...' or "...", or if you make other syntactic mistakes.

Git

The following paragraphs require understanding of Git. If you lack this, please learn about Git basics, from any of the good resources on the net.

There are no .git files in the directories presented in the examples, because in my case, their parent directory is version controlled by Git.

pubnext.sh handles the core Git functionality, as it tries to do a git pull before changing anything in the working directory (i.e, to update changes from a possible remote directory), and it does a git commit and a git push afterwards.

Currently, a local only repository without remote might not be handled gracefully. If you have such a setup, try the scripts, but be prepared to do some hacking. In case you desperately need it, but cannot get it working, feel free to contact me; I might try to add the necessary logic.

Why cronjobs and not Git hooks?

You may ask yourself why I rely on cronjobs to launch the different scripts, and not on Git itself by making use of hooks. Here are my reasons:

Some people may not want to use Git at all, but still would like to have a simple setup to allow for publishing Markdown formatted posts simultaneously to a blog and a glog (HTML and pure text), and possibly send them as newsletters.
Setting up Git hooks is a slightly tricky task, especially if you are only running Git in userspace. If your system permits addition of Git hooks, it will most probably already allow you to install cronjobs, and the latter in general are a much more useful tool, at least in my opinion.
Having defined publication times (slots) helps me in writing posts: A real and automatic (merciless) deadline is one of the best motivators!

If you make it that far, please tell me what you think about Plog! And good luck for your writing endeavours!