How does a user approach documentation? He has some concrete geophysical task to do, and must find out which of the 400 or so programs in Madagascar ( sfdoc -k . | wc -l ) does what he needs. He can get some help from sfdoc, but that does not account for keyword ambiguity and does not offer a quick overview of what is available. Moreover, there is no quick way of knowing whether the program will fit the user's data. Sometimes the documentation mentions a label, i.e. 2-D or 3-D, but is it prestack or poststack? It requires a velocity file; would a 1-D v(z) array work, or does the process work in v(x,z)? Does it take slowness or velocity? Half offset or full offset? Much too often the answer needs to be found by reading the source code – if the poor user did not give up already, that is.
Some of these issues (which kind of offset, especially) can be countered by standardization. The dimensionality issue can be countered by some "static typing" mechanism, in which the program communicates through the self-doc to SCons and to the documentation system what kind of data it accepts and it outputs, permitting filtering of documentation to display, say, only programs that can take as input a prestack 2-D line and do not require a velocity model. However, the problem of discovering functionality still remains.
To counter this problem, I started a map of Madagascar: a Task-centric program list. I have done so far what my patience and time allowed. I hope it is useful to other users as well. There is still a list of programs yet to be classified. It is also quite possible that I made classification mistakes. Any help with the page is appreciated. As I found out firsthand, exploring Madagascar is great for getting to know it!