Documentation has to Scale

Whenever you create a program and try to not suffer the Not Invented Here syndrom, you have to research all kind of libraries. The biggest obstactle at this point it mostly the lack of good documentation, that let you start quickly. I lay particular emphasis on quickly, because there are a lot of excellent libraries available that have very detailed and precice documentation, but take a lot of time just to find out what it does and how to use it. A nice example is log4j. The first link in the documentation section links to Short introduction to log4j, which contains about 5600 words. That’s not what I call short, and it is certainly too much if you just want to get a quick overview.

Documentation should scale. It has to allow the reader to get to the level of understanding he really needs. This is what I believe what good software documentation should contain.

Read more

DVD to WAV, DVD to OGG

Converting the audio of a DVD into a WAV is a piece of cake, with the right tools and if one is willing to use the command line:

mplayer dvd://1 -vc null -vo null -ao pcm -quiet -mc 0 -ni

This is already pretty neat, but I usually want to convert backup the DVD’s audio into an Ogg Vorbis stream. This is possible without an intermediate wav file:

mkfifo pipe
mplayer dvd://1 -vc null -vo null -ao pcm:file=pipe -quiet -mc 0 -ni &
oggenc -o out.ogg - <pipe
vorbisgain out.ogg
rm pipe

Yet another example of the power of named pipes 8-)

Subversion Propset Script

I use a script to set the svn:keywords properties recursively for all files of a given pattern:

#!/bin/sh
PATTERNS="*.txt *.java build.xml *.properties *.sh *.sample"
KEYWORDS="Date Id Rev Author"

for PATTERN in $PATTERNS
do
  find . -name "$PATTERN" -prune -exec svn propset svn:keywords "$KEYWORDS" \{\} \;
  echo "-----------------"
done

echo
echo "don't forget to execute 'svn commit'."

Modify the PATTERNS and KEYWORDS variables as you like, and execute it with

./setSvnKeywordProperties.sh .

to set properties for all the files found by the script. You can do a

svn st

to list all files that are modified with this action, and commit via

svn commit

Who Is Martin Ankerl?

I have studied software engineering and am currently working for Profactor in the multi agent systems group.

You can contact me with with martin.ankerl@gmail.com.

Secure SSH, CVS, SCP without Password Prompt

For the old version of this homepage I have used CVS to update the websites. I have done this via SSH, which is pretty secure but has the annoying disadvantage of asking for a password for each operation. If you can trust the security of your client computer, there is a way to get rid of the password altogehter, without loosing security:

  1. Suppose the domain name of your server is server, and your login name loginname.
  2. On the client, generate a public and private key.
    ssh-keygen -C loginname@server -t dsa

    When asked for a password, simply press return. The private key is stored in ~/.ssh/id_dsa, and the public key in ~/.ssh/id_dsa.pub. Never give the private key away!

  3. Copy the public file to the server with
    scp ~/.ssh/id_dsa.pub loginname@server:~/
  4. Login on the server with
    ssh loginname@server

    append the copied file to ~/.ssh/authorized_keys with

    cat ~/id_dsa.pub >>~/.ssh/authorized_keys
  5. If you want to enable this features on other servers, just repeat step 3 on each of the servers.

That’s it! If you have done everything correctly, the next time you login via SSH or use CVS over SSH, you will not need to enter a password yet you have a secure connenction.

Next Page →