Howto

How to do sh2doc comments

We have the tool sh2doc that looks through the shell/perl scripts to automatically compile an overview of the existing tools we got, especially for GPS processing. The current result is published on the Shell scripts page. Everybody editing, creating or using a certain script should make sure to follow a few basic rules to make this a valuable documentation of our toolbox. The sample for my explanations are the comments within the parser itself (/usr/local/sh2doc/sh2doc.pl).

The file starts out telling that we want to do Perl. Great. Then comes the header comment part:

#!/usr/bin/perl
#
##BRIEF
# Script for automatic documentation shell scripts
#

The keyword ##BRIEF should be followed by a short one-liner that explains the main functionality of the code. This information goes into the overview table where all scripts are listed. All the rest following below will end up on a separate page, e.g. Special:Call/Include_info,/export/ftpweb/htdocs/sh2doc/sh2doc.pl.html.

#
##AUTHOR
# Ronni Grapenthin
#

Well, give a name in the line after ##AUTHOR - preferably your own - so there is someone to blame in case something goes wrong.

##DATE
# 2007-11-20
#

Give the date of creation in the line following the keyword ##DATE.

##DETAILS
#
# This script runs though all directories specified in the field @DIRS and
# looks at all files whether they contain special documentation makers like:
# <ul>
# <li>##BRIEF</li>
# <li>##AUTHOR</li>
# <li>##DETAILS</li>
# <li>##DATE</li>
# <li>##CHANGELOG</li>
# </ul>
# If any of these are found, the file is added to an overview contained in an
# index.html file which lists file name (and a link to a detailed description).
# Furthermore another HTML file is created which contains detailed information
# of the file given in the documentation. Additional meta data of the file such as
# last changed could be added.<br/>
# A line that (starts with spaces only and) contains a comment starting with '#+#'
# will be added to the details. <p>Empty lines or "##" denote that the subsection
# (e.g. DETAILS) is finished. So use minimal HTML for paragraph formatting and line
# breaks. </p>
#

Following the keyword ##DETAILS you can give all the information about the code you want anyone to have. Being chatty at this point is adviced. And here you should actually read the comment above since it describes what's going on.

##CHANGELOG
#
# 2008-01-28 (ronni): search for executables, includes non-tagged files / binaries in index.<br>
# 2008-01-29 (ronni): sorts filenames, gives separate tables for each letter<br>
# 2009-01-08 (ronni): some cheap hacks with the links to get this included in the wiki, a clean html-non-wiki-version is necessary<br>
#

If you change something, note it in the ##CHANGELOG. No special format is defined, but it would greatly improve readability to follow the given example, e.g. YYYY-MM-DD (USER): What's new.

If there are any comments within the code you would like to add to the details, you can use the special comment #+#:

#+# final writing of index file  ... this is inefficient, optimize, if you can!

Each line followed by that special comment will be added to the DETAILS section preceded by '=>' to mark it as a somewhat 'additional note'. This way you can describe the actual flow of the code right where things happen. Note that you can use HTML formatting within the comments, but do not include empty lines when you are trying to improve readability. Also keep in mind that the comments should be clear when you look at the code, so don't overdo the whole table thing.

How to do Matlab

... batch processing?

To call Matlab from the command line or a shell script and have it execute a command or a Matlab script call:

matlab -nojvm -nosplash -r [x,y,z]=script -logfile script.log > /dev/null

This must be called in a directory that contains a file script.m. Whatever Matlab usually dumps to its console ends up in the file script.log. To make sure it does not show up in your script output stdout is redirected to /dev/null. The [x,y,z]= part is only necessary if your script returns results which you would want to use somehow.

IMPORTANT: make sure your script contains an 'exit;' as last command! Otherwise this Matlab instance would remain running which might end up with really nasty performance results in a loop statement. If a bunch of matlab scripts are to be executed, compile a master .m-file which calls them (and is the only one that contains the 'exit;'). This way Matlab is not closed and restarted for each script which might gain a significant performance gain.

... and NetCDF?

The MEXNC, SNCTOOLS and toolsUI packages are installed in /usr/local/matlab . A tutorial describes which routines are provided by the SNCTOOLS package: http://mexcdf.sourceforge.net/tutorial/index.html. To make use of those, you might have to alter your path:

addpath('/usr/local/matlab/mexnc');
addpath('/usr/local/matlab/snctools');
javaaddpath ( '/usr/local/matlab/classes/toolsUI-4.0.jar' );
setpref ( 'SNCTOOLS', 'USE_JAVA', true );

How to do Shell

NOTE: Some commands might be specific for csh/tcsh. Adjustments to bash, sh etc should be straightforward.

... arithmetics?

You would want to use the command 'expr' which "evaluates basic expressions" to do basic arithmetics in the Shell. Try something like:

set X=`expr 100 + 50 '*' 3`
echo $X

This should give you 250. The '`' denote that a subshell is opened in which the command expr 100 + 50 '*' 3 is executed. The return value is then stored in the variable X. You can also use variables in your expressions:

set X=`expr $X + 50 '*' 3`
echo $X

This should return 400.

For the reason of '*' being interpreted als wildcard in the Shell the asterisk must be in single quotes: '*' otherwise you get a syntax error. Check

man expr

to find other operators you would want to use. For more sophisticated math you would wanna use awk or Perl scripts.

Screen

Screen is a useful command for remote or batch processing. It allows you to log into and out of terminals without killing processes. You can operate many screens at once and monitor activity in each screen. Here are some commands to get you started.

screen -S name

This should open a screen with name. It is not necessary to name your screen sessions, but it makes it easier to return to them if you know the name of the session.

screen -r name

Return to an existing screen.

Inside a screen there is no indication that anything has changed; it looks just like a terminal window. You can pass commands to the screen (as opposed to the command line) by using ctrl-a. Here are a couple useful commands for screen:

ctrl-a d 

Detach from screen, leaves the process running.

ctrl-a n

Next screen, if you are running more than one screen at a time.

ctrl-a ?

Help screen, shows some useful screen commands.

ctrl-a K

Kill current screen.

ctrl-a ctrl-\

Quit screen, this closes all screens.