Introduction to Ecru

Roman Bogorodskiy (bogorodskiy@gmail.com)

About

Ecru is a command-line LiveJournal client which pretends to be flexible and follow Unix way.

You might consult README file in the Ecru distribution in order to get information about dependencies and build process.

Getting started

Configuration

Ecru comes with a tool ecru-config which is responsible for configuration related issues. To generate initial configuration schema, execute ecru-config with -g argument: ecru-config -g . It will prompt for your livejournal username and md5 hash of the password. On Linux systems you can generate md5 hash of your password using md5sum utility and on FreeBSD you might use md5 -s. So, in order to avoid interactivity, you might do the following:

		ecru-config -g -u username -p `md5 -s mypass`

Consider that it might be insecure to leave your plain text password in the shell history.

A new directory ecru.new will be created by ecru-config. Just cp -r it to ~/.ecru and you're done with it.

Posting

A tool called ecru-post is responsible for posting new entries. It can be used either in interactive or command line mode. Let's start with the interactive mode first.

If you type ecru-post without any argument it will load $EDITOR . As soon as you finish typing, save the file and quit from the editor, the post will be submitted and ecru-post will return an URL of the new post.

To add subject to the post, you should add a 'subject' keyword to the top of the text, like:

		subject: hey, this is a subject

		the text of a post goes here
		one more line just to make it look more real

You might add other keywords like current mood and stuff, for example:

		subject: another post
		current_mood: good
		current_music: The Beatles - Let It Be
	
		Some very kewlz post, YA RLY.

Please note a blank line separating headers part and the body, it's required. It could be skipped only if your post has no headers at all.

As it was mentioned before, it's possible to post in non-interactive mode. It could be done this way:

	echo "body of the post" | ecru-post -f - \
		-s "subject of the post" \
		-Dcurrent_mood=good -Dcurrent_music="`music.sh`"

It will post a new entry without invoking editor. As you might have noticed, -s is used to set the subject and -D is used to set properties.

Note that you can use -s and -D in an interactive mode as well, however command line arguments has lower priority than the ones defined in the text. E.g. if you executed ecru-post -s "some subject" and didn't provide 'subject:' keyword in the text, the subject of you post will be "some subject". However, if you execute ecru-post -s "some subject" and add "subject:" keyword to the text, like "subject: cooler subject", the subject of you post will be "cooler subject". The same is valid for -D as well.

About security property

Property "security" has three possible values: "public" (default), "friendsonly" and "private". So in order to make a post visible only to friends, "security" property should be set to "friendsonly", i.e. a header "security: friendsonly" should be added or -Dsecurity=friendsonly option passed.

Templates

Before ecru-post invokes the editor it loads the contents of the ~/.ecru/templates/default file. That's where 'subject:' line comes from with the default configuration. You might alter ~/.ecru/templates/default template for your needs. You might create new templates and place it into ~/.ecru/template/ directory and pass their name to -t arg for ecru-post. For example, if you created ~/.ecru/template/mytemplate you call ecru-post -t mytemplate to use it.

Post operations: list, edit, delete

A tool ecru-list could be used to last of recent posts. In first column it shows item id (important!), then few first chars from the post body and post time. If you pass -s argument, it will show post url as well.

You can delete posts using ecru-delete posts, e.g. if you want to delete posts with ids 10 and 11 you do ecru-delete 10 11. As a reminder: you can look up an id in the first column of ecru-list output.

To edit post with id 10 you need to execute ecru-edit 10.

To obtain an info about a post with id 10 you need to execute ecru-info 10. By the way, there's a special id "-1" which always refers to the latest post in your journal. For example: ecru-info - -1 will show an info about the latest post. Note "-" - it's used to getopt didn't think "-1" is an argument.

Advanced topics

Configuration profiles

Ecru supports having several config profiles (which could be useful if you have few accounts). If you want to add a new profile, just create a new configuration file in ~/.ecru/. Its name should end with .conf. Now if you run ecru-config -l you should see a list of configurations, in our example it should be 'default.conf' marked with asterisk and the configuration file you just created. Asterisk (*) marks currently active configuration profile. To change current configuration file you should do (assuming you named file example.conf):

		ecru-config -s example.conf

Now ecru-config -l should show example.conf marked with asterisk.

Hooks

Ecru supports pre- and post- edit hooks. What does it mean? Before and after invoking an editor, ecru checks for executable files in ~/.ecru/hooks/pre for pre- hooks and ~/.ecru/hooks/post for post hooks and executes them, passing filename of with your post as the first argument. So you can do whatever you want with it. Some typical usages as I see them: replace stuff like 'current_music: `get_my_music` with executon result of get_my_music app (check the hooks directory of the ecru distrubution to find a script that does at; it's possible to use it for introducing various types of macroses, etc.

VIM configuration

If you're using vim, the following tips might be useful to you. Add the following to your .vimrc:

		autocmd BufRead /tmp/ecru* call EcruStuff()

		function EcruStuff()
		        set wrap linebreak textwidth=70
		        set ft=html
			set spell
			set backup " ecru is not stable yet ;]
		endfunction

First line sets to call EcruStuff() function if the filename matches /tmp/ecru* template. The EcruStuff function sets line length to 70 (makes reading more easy) and sets file type to html to get html syntax hightlighted in posts.