Suggestions of clarifications to the SAC manual
Having worked a bit with the sacio library I've noted a few points in the SAC manual that could be clarified in order to help newbies like myself. All of these relate to the sample scripts for reading/writing sac files
The section title "Reading an Unevenly-Sampled or Spectral file SAC file" can be interpreted to cover reading of evenly sampled spectral files as well. Likewise the text just below indicates that rsac2() is the function to use for a (evenly sampled) spectral file. I would suggest to remove the notation of spectral from the title and text as (I may be mistaken here) in reality rsac2 does not care if the file is spectral or not but only if it is unevenly sampled, hence spectral is not really relevant here. Instead one could perhaps add one paragraph to the section "Reading an Evenly-Sampled SAC file" pointing out that to find out if the file contains time domain data or a spectral components the user should check the value of the header variable iftype and (if the file was written using writesp) check the file suffix to try to deduce which component is in the file if spectral data.
In the comments in the sample scripts to write Unevenly-Spaced Data it is stated that the header variable "delta" must be set, yet the sample scripts does not do so.
In the section "SAC Header Variables" the header parameter "LEVEN" is defined as mandatory, yet in the sample scripts to write Unevenly-Spaced Data it is not mentioned in the comment that explains what parameters needs to be set in the newly created header (it is set though in the scripts). As the default value of the parameter is .true. (fortran), 1 (C) this could potentially lead to bugs.
In the sample scripts to write Unevenly-Spaced Data it could be added to the comment preceeding wsac0() that the xarray argument can be a NULL pointer if the file is evenly spaced as this array will not be considered in that case.
In the sample script "Accessing Header Variables" I would suggest to replace the call to rsac1() with rsach(), as if the only interest lies in accessing header variables it seems un-neccesary to have to read the entire file. Further, if one wishes to read all data in the file one first needs to know the number of samples (if not known pre-hand) in order to allocate the proper chunck of memory, thus using rsac1 first where data actually needs to be read seems a bit odd. I wouldn't mind though a comment explaining that both rsac1() and rsac2() also loads the header into memory and thus can be used if the user already knows how mush data to read in.
In the sample script "Accessing Header Variables" it would be instructive if not only float type header variables were accessed, perhaps replace all but one with accessing header variables of other types.