Commit 26f97671 authored by thomas.forbriger's avatar thomas.forbriger
Browse files

ts/wf/foutra [TASK]: put usage texts in separate files

Usage texts are moved from the compilation unit foutra.cc to separate text
files. Upon compilation appropriate C++ source code will be prepared
automatically. This style of providing the documentation makes it easier to
keep it up to date and to provide references from elsewhere.
parent 7b4fe7af
*_help.cc
*_help.h
...@@ -91,14 +91,8 @@ FFLAGS += -ff2c -Wall -ffixed-line-length-0 -fno-backslash $(FLAGS) ...@@ -91,14 +91,8 @@ FFLAGS += -ff2c -Wall -ffixed-line-length-0 -fno-backslash $(FLAGS)
CXXFLAGS+=-Wall $(FLAGS) CXXFLAGS+=-Wall $(FLAGS)
LDFLAGS=$(addprefix -L,$(LOCLIBDIR) $(subst :, ,$(SERVERLIBDIR))) $(STATIC) LDFLAGS=$(addprefix -L,$(LOCLIBDIR) $(subst :, ,$(SERVERLIBDIR))) $(STATIC)
#---------------------------------------------------------------------- # ----------------------------------------------------------------------
# standard edit targets #
.PHONY: clean
clean: ;
-find . -name \*.bak | xargs --no-run-if-empty /bin/rm -v
-find . -name \*.d | xargs --no-run-if-empty /bin/rm -v
-/bin/rm -vf flist *.o *.xxx *.ps *~ $(PROGRAMS)
TESTCASEMAKE=$(filter-out %.bak,$(wildcard testcases/Makefile*)) TESTCASEMAKE=$(filter-out %.bak,$(wildcard testcases/Makefile*))
# the frame of doxygen documentation is placed in text files # the frame of doxygen documentation is placed in text files
...@@ -106,12 +100,27 @@ DOXYTXT=$(wildcard doxygen*.txt */doxygen*txt) ...@@ -106,12 +100,27 @@ DOXYTXT=$(wildcard doxygen*.txt */doxygen*txt)
EDITFILES=Makefile README $(wildcard *.cfg) COPYING $(DOXYTXT) \ EDITFILES=Makefile README $(wildcard *.cfg) COPYING $(DOXYTXT) \
$(filter-out %.bak,$(wildcard */README*)) $(filter-out %.bak,$(wildcard */README*))
EDITSRC=$(wildcard *.cc *.h *.c *.f *.gpt *.inc) EDITSRC=$(filter-out $(EDITFILES) \
$(patsubst %.txt,%.h,$(DESCRIPTIONTXT)) \
$(patsubst %.txt,%.cc,$(DESCRIPTIONTXT)),\
$(wildcard *.cc *.h *.c *.f *.gpt *.inc))
EDITTESTS=$(wildcard testcases/*.par) $(wildcard testcases/*.tpl) \ EDITTESTS=$(wildcard testcases/*.par) $(wildcard testcases/*.tpl) \
$(TESTCASEMAKE) $(wildcard testcases/*.gpt) $(TESTCASEMAKE) $(wildcard testcases/*.gpt)
DESCRIPTIONTXT=$(wildcard *_help.txt)
EDITTXT=$(DESCRIPTIONTXT)
#----------------------------------------------------------------------
# standard edit targets
.PHONY: clean
clean: ;
-find . -name \*.bak | xargs --no-run-if-empty /bin/rm -v
-find . -name \*.d | xargs --no-run-if-empty /bin/rm -v
-/bin/rm -vf flist *.o *.xxx *.ps *~ $(PROGRAMS)
-/bin/rm -fv $(patsubst %.txt,%.h,$(DESCRIPTIONTXT))
-/bin/rm -fv $(patsubst %.txt,%.cc,$(DESCRIPTIONTXT))
flist: $(wildcard *.txt *.c *.f *.h *.inc *_text.txt Makefile *.cc *.gpt) \ flist: $(wildcard *.txt *.c *.f *.h *.inc *_text.txt Makefile *.cc *.gpt) \
doxydoc.cfg README COPYING $(DOXYTXT) $(EDITFILES) \ doxydoc.cfg README COPYING $(DOXYTXT) $(EDITFILES) $(EDITTXT) \
$(wildcard testcases/*.par) $(wildcard testcases/*.tpl) \ $(wildcard testcases/*.par) $(wildcard testcases/*.tpl) \
$(TESTCASEMAKE) $(wildcard testcases/*.gpt) $(TF_EDIT) $(TESTCASEMAKE) $(wildcard testcases/*.gpt) $(TF_EDIT)
echo $(filter $(EDITFILES),$^) | tr ' ' '\n' | sort > $@ echo $(filter $(EDITFILES),$^) | tr ' ' '\n' | sort > $@
...@@ -121,10 +130,12 @@ flist: $(wildcard *.txt *.c *.f *.h *.inc *_text.txt Makefile *.cc *.gpt) \ ...@@ -121,10 +130,12 @@ flist: $(wildcard *.txt *.c *.f *.h *.inc *_text.txt Makefile *.cc *.gpt) \
echo $(sort $(filter %.f,$^)) | tr ' ' '\n' >> $@ echo $(sort $(filter %.f,$^)) | tr ' ' '\n' >> $@
echo "---- C++ source files only ----" >> $@ echo "---- C++ source files only ----" >> $@
echo $(sort $(filter %.cc,$^)) | tr ' ' '\n' >> $@ echo $(sort $(filter %.cc,$^)) | tr ' ' '\n' >> $@
echo "---- program documentation ----" >> $@
echo $(filter $(EDITTXT),$^) | tr ' ' '\n' | sort >> $@
echo "---- test cases ----" >> $@ echo "---- test cases ----" >> $@
echo $(sort $(filter $(EDITTESTS),$^)) | tr ' ' '\n' >> $@ echo $(sort $(filter $(EDITTESTS),$^)) | tr ' ' '\n' >> $@
echo "----" >> $@ echo "----" >> $@
echo $(filter-out $(EDITFILES) $(EDITSRC) $(EDITTESTS),$^) \ echo $(filter-out $(EDITTXT) $(EDITFILES) $(EDITSRC) $(EDITTESTS),$^) \
| tr ' ' '\n' | sort >> $@ | tr ' ' '\n' | sort >> $@
.PHONY: edit .PHONY: edit
...@@ -136,7 +147,7 @@ edit: flist; vim $< ...@@ -136,7 +147,7 @@ edit: flist; vim $<
#---------------------------------------------------------------------- #----------------------------------------------------------------------
# description and online texts # description and online texts
%.cc %.h: %_help.txt %_help.cc %_help.h: %_help.txt
echo "// DO NOT EDIT: this file is automatically derived from $<" \ echo "// DO NOT EDIT: this file is automatically derived from $<" \
> $(patsubst %.txt,%.h,$<) > $(patsubst %.txt,%.h,$<)
echo "extern char $(patsubst %.txt,%,$<)[];" >> $(patsubst %.txt,%.h,$<) echo "extern char $(patsubst %.txt,%,$<)[];" >> $(patsubst %.txt,%.h,$<)
...@@ -158,7 +169,7 @@ edit: flist; vim $< ...@@ -158,7 +169,7 @@ edit: flist; vim $<
> $@; \ > $@; \
[ -s $@ ] || rm -f $@' [ -s $@ ] || rm -f $@'
include $(patsubst %.txt,%.d,$(wildcard *_help.txt)) include $(patsubst %.txt,%.d,$(DESCRIPTIONTXT))
include $(patsubst %.cc,%.d,$(wildcard *.cc)) include $(patsubst %.cc,%.d,$(wildcard *.cc))
#---------------------------------------------------------------------- #----------------------------------------------------------------------
...@@ -237,7 +248,12 @@ noisymize: \ ...@@ -237,7 +248,12 @@ noisymize: \
$(LINK.cpp) $^ $(LOADLIBES) $(LDLIBS) -o $@ \ $(LINK.cpp) $^ $(LOADLIBES) $(LDLIBS) -o $@ \
$(LIBTSIOXX) $(LIBTSIOXX)
cross fregra foutra deconv: \ foutra: \
%: %.o $(patsubst %.txt,%.o,$(wildcard foutra_*_help.txt))
$(LINK.cpp) $^ $(LOADLIBES) $(LDLIBS) -o $@ \
-lfourierxx $(LIBTSIOXX) -lfftw3
cross fregra deconv: \
%: %.o %: %.o
$(LINK.cpp) $^ $(LOADLIBES) $(LDLIBS) -o $@ \ $(LINK.cpp) $^ $(LOADLIBES) $(LDLIBS) -o $@ \
-lfourierxx $(LIBTSIOXX) -lfftw3 -lfourierxx $(LIBTSIOXX) -lfftw3
......
...@@ -97,6 +97,10 @@ ...@@ -97,6 +97,10 @@
#include <fourier/fftwaff.h> #include <fourier/fftwaff.h>
#include <sstream> #include <sstream>
#include "foutra_options_brief_help.h"
#include "foutra_options_help.h"
#include "foutra_usage_help.h"
using std::cout; using std::cout;
using std::cerr; using std::cerr;
using std::endl; using std::endl;
...@@ -135,110 +139,9 @@ int main(int iargc, char* argv[]) ...@@ -135,110 +139,9 @@ int main(int iargc, char* argv[])
{ {
// define usage information // define usage information
char usage_text[]= char version_text[]=
{ {
FOUTRA_VERSION "\n" FOUTRA_VERSION "\n"
"usage: foutra [-v] [-o] [-type type] [-Type type] [-D] [-ASCII[=base]]\n"
" [-amplitude] [-power] [-logascii[=n]]" "\n"
" [-boxcar] [-avg[=n]] [-rbw[=n]] [-avgascii]" "\n"
" [-demean[=n]] [-dtrend[=n]] [-scalerbw[=n]]" "\n"
" [-divisor[=n]] [-rms] [-harmonic] [-pad n]" "\n"
" [-derivative n]" "\n"
" [-nsegments n]" "\n"
" outfile infile [t:T] [infile [t:T] ...]" "\n"
" or: foutra --help|-h" "\n"
" or: foutra --xhelp" "\n"
};
// define full help text
char help_text[]=
{
"outfile output filename" "\n"
"infile input filename" "\n"
" t:T select traces T, where T may be any range" "\n"
" specification like \'3-4\' or \'5,6,7-12,20\'" "\n"
"\n"
"-help prints this help text" "\n"
"-xhelp print information concerning supported data formats" "\n"
"\n"
"-v be verbose" "\n"
"-D debug mode" "\n"
"-o overwrite output" "\n"
"-boxcar apply boxcar taper (i.e. no taper; default is Hanning)" "\n"
"-amplitude calculate amplitude spectrum" "\n"
"-power calculate power spectrum" "\n"
"-type type select input file type" "\n"
"-Type type select output file type" "\n"
"-avg[=n] smooth power spectrum by averaging over n samples" "\n"
"-rbw[=n] smooth power spectrum by averaging over n decades" "\n"
"-demean[=n] remove average (determined from n samples)" "\n"
"-detrend[=n] remove trend (determined from n samples)" "\n"
"-derivative[=n] take n-th derivative of time series" "\n"
"-scalerbw[=n] scale to mean value in n decades" "\n"
"-divisor[=n] FFT becomes very inefficient if the factorization" "\n"
" of the number of samples includes large prime numbers." "\n"
" This option removes the least number of samples to" "\n"
" the total number of samples a multiple of \"n\"" "\n"
"-ASCII[=base] write result to two-column ASCII files "
"with basename \'base\'" "\n"
"-logascii[=n] write ASCII data on logarithmic frequency axis with" "\n"
" one value per \'n\' decades" "\n"
"-avgascii only average values for output to ASCII file" "\n"
" this option speeds up calculation together with" "\n"
" -scalerbw which increases computation time" "\n"
" with the square of frequency" "\n"
"-rms report rms values of input data" "\n"
"-harmonic scale output appropriate fro harmonic signals" "\n"
" useful for two-tone-tests of linearity (see below)" "\n"
"-pad n pad time series with zeroes; n gives the integer factor" "\n"
" for the number of samples; the raw amplitude spectrum" "\n"
" has to be understood as the spectrum of the whole" "\n"
" series including the padded zeroes; PSD and harmonic" "\n"
" signals are scaled to represent the taper time window" "\n"
" only, such that padding is a means of smoothing only" "\n"
"-nsegments n subdivide input time series in \"n\" overlapping" "\n"
" sequences (overlap is 50%); spectral analysis is" "\n"
" done for each sequence individually; the result" "\n"
" is the mean of all sequences; this applies to PSD" "\n"
" and harmonic signal analysis only; it is particularly" "\n"
" useful for two-tone-test where spectral smoothing" "\n"
" of background noise is anticpated, while maintaining" "\n"
" the full resolution for harmonic peaks" "\n"
"\n"
"If input units are K, then the output units of power spectra will" "\n"
"be K*K/Hz. The units for amplitude spectra then are K/Hz. If scaling" "\n"
"to the mean in a relative bandwidth is used (only applies for power" "\n"
"spectra; switch -scalerbw) the output units are K*K." "\n"
"\n"
"The Fourier transformation does not exist for harmonic signals." "\n"
"The option \"-harmonic\" supports the analysis of a time limited" "\n"
"portion of an harmonic signal. If this option is set, the output" "\n"
"is scaled such that the spectral values of the peaks of harmonic" "\n"
"signals are the time domain amplitude in units of K." "\n"
"\n"
"The integral over the power spectral density calculated by foutra" "\n"
"over the total bandwidth (over all frequencies from 0 Hz to Nyquist" "\n"
"frequency) provides the total power of the signal (i.e. the" "\n"
"variance of the input signal, i.e. the square of the rms value)." "\n"
"This is called the one-sided power spectral density." "\n"
"\n"
"The input signal can be extended by padding with zeroes. This" "\n"
"mainly is used to obtain a smoother representation of the" "\n"
"corresponding spectral display where the amplitude of narrow" "\n"
"peaks might not fall on a spectral node when analysing harmonic" "\n"
"signals. The spectral representation consequently is scaled" "\n"
"to the length of the applied taper function (and not to the" "\n"
"full length of the padded time series) for harmonic" "\n"
"signal analysis and power spectral densities, since the" "\n"
"signal under investigation is understood as being infinite in" "\n"
"time. For amplitude spectra of transient signals (the default)" "\n"
"no scaling to a time window takes place, since padding with" "\n"
"zeroes is understood as not altering the signal." "\n"
"\n"
"Output is written in SFF. There the sampling interval provided" "\n"
"in the WID2 line specifies the frequency sampling interval of the" "\n"
"spectrum. The first coefficient in the file is at 0 Hz. The" "\n"
"last is the coefficient at Nyquist frequency." "\n"
}; };
// define commandline options // define commandline options
...@@ -304,7 +207,8 @@ int main(int iargc, char* argv[]) ...@@ -304,7 +207,8 @@ int main(int iargc, char* argv[])
// no arguments? print usage... // no arguments? print usage...
if (iargc<2) if (iargc<2)
{ {
cerr << usage_text << endl; cerr << version_text << endl;
cerr << foutra_options_brief_help << endl;
exit(0); exit(0);
} }
...@@ -314,8 +218,10 @@ int main(int iargc, char* argv[]) ...@@ -314,8 +218,10 @@ int main(int iargc, char* argv[])
// help requested? print full help text... // help requested? print full help text...
if (cmdline.optset(0) || cmdline.optset(21)) if (cmdline.optset(0) || cmdline.optset(21))
{ {
cerr << usage_text << endl; cerr << version_text << endl;
cerr << help_text << endl; cerr << foutra_options_brief_help << endl;
cerr << foutra_options_help << endl;
cerr << foutra_usage_help << endl;
datrw::supported_data_types(cerr); datrw::supported_data_types(cerr);
if (cmdline.optset(21)) { datrw::online_help(cerr); } if (cmdline.optset(21)) { datrw::online_help(cerr); }
exit(0); exit(0);
......
# this is <foutra_options_brief.txt>
# ============================================================================
# foutra: short list of command line options
# ------------------------------------------
usage: foutra [-v] [-o] [-type type] [-Type type] [-D] [-ASCII[=base]]
[-amplitude] [-power] [-logascii[=n]]
[-boxcar] [-avg[=n]] [-rbw[=n]] [-avgascii]
[-demean[=n]] [-dtrend[=n]] [-scalerbw[=n]]
[-divisor[=n]] [-rms] [-harmonic] [-pad n]
[-derivative n]
[-nsegments n]
outfile infile [t:T] [infile [t:T] ...]
or: foutra --help|-h
or: foutra --xhelp
#
# ----- END OF foutra_options_brief.txt -----
# this is <foutra_options.txt>
# ============================================================================
# foutra: definition of command line options and parameters
# ---------------------------------------------------------
outfile output filename
infile input filename
t:T select traces T, where T may be any range
specification like '3-4' or '5,6,7-12,20'
-help prints this help text
-xhelp print information concerning supported data formats
-v be verbose
-D debug mode
-o overwrite output
-boxcar apply boxcar taper (i.e. no taper; default is Hanning)
-amplitude calculate amplitude spectrum
-power calculate power spectrum
-type type select input file type
-Type type select output file type
-avg[=n] smooth power spectrum by averaging over n samples
-rbw[=n] smooth power spectrum by averaging over n decades
-demean[=n] remove average (determined from n samples)
-detrend[=n] remove trend (determined from n samples)
-derivative[=n] take n-th derivative of time series
-scalerbw[=n] scale to mean value in n decades
-divisor[=n] FFT becomes very inefficient if the factorization
of the number of samples includes large prime numbers.
This option removes the least number of samples to
the total number of samples a multiple of "n"
-ASCII[=base] write result to two-column ASCII files with basename 'base'
-logascii[=n] write ASCII data on logarithmic frequency axis with
one value per 'n' decades
-avgascii only average values for output to ASCII file
this option speeds up calculation together with
-scalerbw which increases computation time
with the square of frequency
-rms report rms values of input data
-harmonic scale output appropriate fro harmonic signals
useful for two-tone-tests of linearity (see below)
-pad n pad time series with zeroes; n gives the integer factor
for the number of samples; the raw amplitude spectrum
has to be understood as the spectrum of the whole
series including the padded zeroes; PSD and harmonic
signals are scaled to represent the taper time window
only, such that padding is a means of smoothing only
-nsegments n subdivide input time series in "n" overlapping
sequences (overlap is 50%); spectral analysis is
done for each sequence individually; the result
is the mean of all sequences; this applies to PSD
and harmonic signal analysis only; it is particularly
useful for two-tone-test where spectral smoothing
of background noise is anticpated, while maintaining
the full resolution for harmonic peaks
#
# ----- END OF foutra_options.txt -----
# this is <foutra_usage.txt>
# ============================================================================
# foutra: online usage information
# --------------------------------
If input units are K, then the output units of power spectra will
be K*K/Hz. The units for amplitude spectra then are K/Hz. If scaling
to the mean in a relative bandwidth is used (only applies for power
spectra; switch -scalerbw) the output units are K*K.
The Fourier transformation does not exist for harmonic signals.
The option "-harmonic" supports the analysis of a time limited
portion of an harmonic signal. If this option is set, the output
is scaled such that the spectral values of the peaks of harmonic
signals are the time domain amplitude in units of K.
The integral over the power spectral density calculated by foutra
over the total bandwidth (over all frequencies from 0 Hz to Nyquist
frequency) provides the total power of the signal (i.e. the
variance of the input signal, i.e. the square of the rms value).
This is called the one-sided power spectral density.
The input signal can be extended by padding with zeroes. This
mainly is used to obtain a smoother representation of the
corresponding spectral display where the amplitude of narrow
peaks might not fall on a spectral node when analysing harmonic
signals. The spectral representation consequently is scaled
to the length of the applied taper function (and not to the
full length of the padded time series) for harmonic
signal analysis and power spectral densities, since the
signal under investigation is understood as being infinite in
time. For amplitude spectra of transient signals (the default)
no scaling to a time window takes place, since padding with
zeroes is understood as not altering the signal.
Output is written in SFF. There the sampling interval provided
in the WID2 line specifies the frequency sampling interval of the
spectrum. The first coefficient in the file is at 0 Hz. The
last is the coefficient at Nyquist frequency.
#
# ----- END OF foutra_usage.txt -----
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment