Q: Why are the variable names in log4sh so strange? There seems to be no rhyme
or reason to them.

A: Not all shells support the variable scoping that one would expect. All
variables are treated as global variables, which means that if a variable has a
value outside a function call, and then a function call changes the value, the
original value is not returned upon exiting the function. To get around this,
each function must have different variable names so that when one function
calls another, variables are not overwritten. Where things get especially hairy
is when any sort of recursion is needed, and as such, recursion is avoided in
log4sh. The best example of the described behavior is the default Bourne shell
of Solaris.


Q: Why are the variables in log4sh not more "shell" like? In other words, why
are they so long?

A: Two reasons really. The first reason is for readability. log4sh has been
developed over a long period of time (years), and when going back to the code
after any length of time, it is very easy to forget how or why things were done
the way they were. Long descriptive variable names make it much easier to
remember how and why. The second reason is, well, for readability. The hope is
that newbie shell developers (and experienced ones as well) will look at the
code and be able to learn and/or improve upon it. The faster and easier they
can understand the code, the better their understanding and improvements will
be.


Q: Why is there strange XML in the comments? There are almost more comments
than code!

A: Along the same lines of having long variable names, it is for better
understanding. Maintaining spearate documentation for the functions available
in log4sh is difficult, and it tends to be out-of-date with respect to the
code. This way, everything is in one document and there is a much better chance
that the function documentation remains up-to-date. As to why XML is in there
-- the documentation for log4sh is written in DocBook so that it is
standardized. The log4sh XML is not pure DocBook as it does not fit the need
well enough, but the log4sh XML is run through XSLT to generate pure DocBook
XML, and thereby it fits in nicely with the rest of the DocBook documentation.

If you would prefer to see log4sh without the majority of XML comments, a
simple 'grep' might help you out. Try the following:

$ grep -v '^#' log4sh


$Revision: 345 $