Monday, December 27, 2004

Man Page

I'm back after a long hiatus.. have been very busy with the new project. A tool has been developed by Santosh, the guy who's mantle I've donned in this project, called Randomizer. Additional requirements keep coming from the client, so my role is to change/add to the tool to support these. One of them was a man page, which I made today. I'd like to show you how you to do it and killing two birds with one stone too, 'cuz it explains what the tool does! :)

\" Process this file with groff -man -Tascii rand.txt
\" Thank goodness for the Linux Man-Page Mini-HOWTO.
\" And for man 7 man.
\" This is my first attempt at writing a man page. Bear with me.
\"
\" Note: This is for version 1 of the randomizer.
.TH RANDOMIZER l 2004-12-28 Linux "User Manuals"
.SH NAME
randomizer \- A tool to produce random values for variables supplied.
.SH SYNOPSIS
.B randomizer -file
.I FILENAME
.B [-prefix string] [-ignore varlist] [-change] [-verbose] [-strict]
.B [-scriptfile
.I FILENAME
.B ] [-assertmode]
.SH DESCRIPTION
.B Randomizer
takes in a rules file and optional switches to control output. The rules file
has variables and rules describing the relationships between them.

.B Randomizer
produces random values for these variables as output, such that the rules
governing the relationships between those variables are not, any of them,
violated. If run for long enough, Randomizer would eventually produce all
possible legal combinations for the given input variable sets.

.B Randomizer
assigns a value of -1 to the concerned variable on encountering invalid
rules. Errors are printed to stderr and other output to stdout.
.SH RETURN VALUE
.nf
0 - on successful completion
1 - on encountering error(s)
.fi
.SH OPTIONS
.IP "-file FILENAME"
Specify the rules file for randomizer
.IP "-prefix string"
Specify string to be prefixed for each o/p
.IP "-ignore var1, var,..."
Ignore variables var1, var2,... during o/p
.IP -change
Print only variables that undergo a change
.IP -verbose
Enable debug level messages at runtime
.IP -strict
Compel all variables to be declared with initialisations
.IP "-scriptfile FILENAME"
Specify the scriptfile for variable replacement
.IP -assertmode
Treat randomization rules as assertions
.SH USAGE
A variable must lie in the range (0, 2147483647) to be valid.

The inits file must contain variable initialisations, in the format:
.B variable = value
where the variable name must start with an alphabet or underscore.

The rules file must contain relationships between operands. Operands are
either variables or constants. Rules must adhere to the format:
.B variable ; expression (&&/||) expression (&&/||) expression...

Expressions are to be defined in the format:
.B operand operator operand
, using the operators
.B <=, <, >=, >, !=, ==
and their combination with the ternary operator ?:, which is used as
.B a ? b : c
(if a, then b, else c)

.P Multi-line rules should be enclosed in curly braces.
The rules file may contain comments, beginning with a hash (#) symbol.
.SH AUTHORS
.nf
Santosh B. Kulkarni
Sankar Narayanankutty
.fi