Although the current shader gallery does much to show off the possibilities of the shader languages it is of little help when it comes to categorize and use the files given in the "share/crystalspace/data/shader" directory in one's installation.
In that case a list of the shaders, their usage contexts, list of input parameters and their range of values as well as a resulting image (or more, as the case may be) as an example would help much to choose the correct one for a task at hand.
You're absolutely right. We need better documentation or shader examples.
Volunteers?

Greetings,