=============================================================================
                            C L E A N S C O R E 
=============================================================================
				 

1. What is it?
==============

Cleanscore is a perl-script to remove expired score entries from the
newsreader slrn's scorefile (usually $HOME/News/Score).


2. How to install it?
=====================

Its quite simple. Just copy the script into a directory in your $PATH.
If you in doubt where the right place is just try the directory "$HOME/bin".
Now you can run cleanscore, but at least the '-f <filename>' argument is needed.


3. How does it work?
====================
 
3.1 Basics:
-----------

Cleanscore opens the scorefile given with the '-f <filename>' option and reads
every line in it. If the given filename is a directory, cleanscore
successively opens every file in it (except its own backup-files).

While reading, cleanscore has to phrase every line, trying to see whether this
line is the beginning or the end of a single entry.  And here is the problem.
Because the syntax of slrn's scorefiles is not designed for automatic

cleaning, it's hard for the script to decide where exactly an entry starts or
ends (i.e., to decide to which entry comment lines before/after it belong.)
That's why cleanscore links every empty or comment line after the last
"active" line of an entry to the following entry.

But there's a way to protect comments that should not get removed and to avoid
trouble with automatically generated entries (which often contain some
comments after them). Cleanscore knows the tags '%BOS' (for 'Beginning of
Score') and '%EOS' (for 'End of Score'). Just put those tags around your
entries (entries generated by slrn are marked with these tags since
slrn-version 0.9.7.0)

Checking whether the entry is expired or not is much more simple then finding
the borders of it. Cleanscore phrases the 'Expires:' line and compares it with
the local time. ('Expires:' after a comment-sign ('%' or '#') is ignored, of
course)

If you don't want to remove expired entrys on the same day, the
commandline-option '-k <n>' is your friend. With this option set, cleanscore
will keep your entries 'n' days longer (to be exact, it will calculate with
the date 'n' days before). That way, you can easily reactivate an entry simply
by changing the 'Expires:' line in these 'n' days.

If an entry is expired, it will quietly be deleted (unless you invoke
cleanscore with its '-v' or the '-d' flag). If you want to save your valuable
entries, you can instruct cleanscore to save all removed entries into a file.
This is done via the commandline-option '-s <filename>'.

If cleanscore removes many entries, one problems occurs often: there's a large
block of empty lines. To remove them, there's the '-e <n>' commandline-option.
With this option set, cleanscore only allows 'n' empty lines in a block, every
additional empty line is removed.

If you want to see what cleanscore will remove without risks, use the '-t'
option. With this, cleanscore opens the file read-only and prints everything
that would be removed (except empty line from the '-e' switch) to stdout.


3.2 Other nice things:
----------------------

If slrn generates a entry, it writes every line it could base an entry on into
your scorefile and puts a '%'-commentsign before those it does not need in
this case. If you generate many entries this way, your scorefile gets bloated.
cleanscore has the option '-r' to remove all lines beginning with the
'%'-sign. Comments beginning with the '#'-sign are not removed, so you can
write your own comments beginning with that sign.

If you don't like cleanscore's default backup-extension '.bak', you can change
it with the '-b <extension>' option. Backup-files are ignored if cleanscore
cleans a directory of scorefiles. If you want cleanscore to ignore files with
other extensions too, you can tell cleanscore via the '-i <pattern>' option.
If this option is set, every file ending with '<pattern>' is ignored.


3.3 How to use it:
------------------

I recommend running cleanscore on a daily basis (or whenever you read news if
you don't read every day ;)). On a Unix system, there are many ways to do
this. One possible solution is a script that first runs cleanscore and then
starts slrn. Another way is a little cronjob. On my system, I put the entry

| 0 3 * * * cleanscore -v -i '~' -k 3 -f ~/news/score

into my user crontab (this means run the command 'cleanscore -v -i '~' -k 3 -f
~/news/score' every day at 03:00H -- see 'man 8 cron' and 'man 5 crontab' if
this is new for you).

A short description of the options I use:

-v                 Be verbose (I like to know what is going on ;))

-i '~'             Ignore backup-files from my $EDITOR (vim)

-k 3               Keep entries 3 days longer, so I can easily reactivate it
		   if it is still needed.

-f ~/news/score    Clean '~/news/score'. That is the directory where all my
                   scorefiles are.



4. Commandline options
======================

Required Options:

-f <filename>   "File".   Chose "filename" for cleaning.
                          If "filename" is a directory, clean
			  all files in it.


Standard Options for "help" and "version":

-V              "Version".  Print Version and exit.
-h              "Help".     Prints a help message.


Other Options:

-b <extension>  "Backup extension".   Overwrites the default backup-
                extension ('.bak').
		   
-d              "Debug".    Prints dates and status for each entry.

-e N            "Empty lines". Cut multiple empty lines down to N.

-i <pattern>    "Ignore pattern".   When scanning through a directory,
                ignore files with names matching "pattern".
                The "backup extension" is matched automaticly.

-k N            "Keep for N days".
                Do not remove expired entries immediately; instead, hold them
		for N more days.  This allows to keep expired entries so you
		can still edit them, eg. change the expire date.

-r              "Remove".  Removes comment lines, i.e. lines beginning
                with '%'. (i.e. remove slrn generated comments
                if you use '#' for your own comments)

-s <filename>	"Save to". Save removed entries to "filename".

-t              "Test".  Just check for expired entries,
                but do not change the scorefile.
                Prints "removed" entries to stdout.

-v              "Verbose".  Prints all expired entries to stdout.


3. Copying
==========

Cleanscore is distributed under the terms of the GNU General Public License.


4. Changes
==========

See NEWS.cleanscore


5. Author
=========

Felix Schueller <fschueller@netcologne.de>