Help for ISIS/S-Lang
The help/description of S-Lang or ISIS functions -- which can be obtained, e.g., with isis> help function_name --
is defined in plain text files.
(In order to take effect, these must be introduced to S-Lang's help system via add_doc_file
-- which is usually performed by S-Lang or ISIS itself, or by an external module.
get_doc_files can be used to query at runtime which files are available.)
Although these help files could, in principle, be edited directly, most programs from the S-Lang ecosystem generate them from text macro files, which are rendered by the script (using jed).
Advantages of defining logically structured tm-files (using macros like \usage, \description, ...) -- rather than physically formatted help files -- are:
- The structural elements (like USAGE, DESCRIPTION, ...) will always be rendered consistently.
- The same text macro file can be rendered in different formats -- for example also produce PDF documentation (see, e.g., the S-Lang and ISIS manuals) besides S-Lang help files.
(tmexpand can simply use different macro definitions. Note the similarity to LaTeX!)
For convenience (and more correct documentation... ;-)), text macros can be directly defined within the source code. tmexpand comes with a tm-strip script that extracts text macros from comments enclosed by %!%+ and %!%- (in S-Lang files).
A help definition within the ISISscripts, which automatically run the tm-strip -- tmexpand pipeline, might look like that:
%!%+
%\function{function_name}
%\synopsis{short description}
%\usage{type return_value = function_name( arguments );}
%\altusage{alternative usage, if applicable}
%\qualifiers{
%\qualifier{qualifier1}{: description}
%\qualifier...
%}
%\description
% Describe the function and tell what it does.
%\example
% Give an example of the usage here.
%\seealso{function_name2, function_name3}
%!%-
For example, the help of the CCF_1D function:
%%%%%%%%%%%%%
define CCF_1d()
%%%%%%%%%%%%%
%!%+
%\function{CCF_1d}
%\synopsis{calculates the cross correlation function of two (1d) arrays}
%\usage{Double_Type CCF = CCF_1d(a1, a2, Integer_Type dx);
%\altusage{Array_Type CCF[] = CCF_1d(a1, a2);}
%}
%\qualifiers{
%\qualifier{notperiodic}{: no periodic boundary conditions at the edges.}
%}
%\description
% The arrays \code{a1} and \code{a2} from which the CCF is to be computed can
% either be passed directly or by a reference to the arrays (see example).
% This function computes the correlation of a1[x] and a2[x-dx],
% where the index x takes all values such that x and x-dx are contained:
% \code{CCF = sum_x { (a1[x]-<a1>)/|a1| * (a2[x]-dx)-<a2>)/|a2| }}
% The norm \code{|a| = sqrt{ sum_x a[x]^2 }} ensures that \code{CCF_1d(a, +-a, 0) = +-1}.
% for any array \code{a}.\n
% \n
% If just a1 and a2 are give, the function returns an array which
% contains all possible correlations between them. Its first entry
% responds to dx=0, the second to dx=1, ... .\n
% \n
% By default, periodic boundary conditions are taken at the edges
% of the array.
%
%\example
% variable a1 = Double_Type[N]; % some data
% variable a2 = Double_Type[N]; % some other data
% variable DX = [-N/2;N/2];
% variable CCF = array_map(Double_Type, &CCF_1d, &a1, &a2, DX);
% % If used with array_map, explicit references to a1 and a2 are required,
% % as each function call to CCF_1d has to get the full array.
% variable dx_opt = DX[where( abs(CCF) == max(abs(CCF)) )];\n
% \n
% or\n
% \n
% variable a1 = Double_Type[N];
% variable a2 = Double_Type[N];
% variable CCF[] = CFF_1d(a1,a2);
%\seealso{CCF_2d}
%!%-
gives the following output when called by help CFF_1d:
SYNOPSIS
calculates the cross correlation function of two (1d) arrays
USAGE
Double_Type CCF = CCF_1d(a1, a2, Integer_Type dx);
% or
Array_Type CCF[] = CCF_1d(a1, a2);
QUALIFIERS
; notperiodic: no periodic boundary conditions at the edges.
DESCRIPTION
The arrays a1 and a2 from which the CCF is to be computed can
either be passed directly or by a reference to the arrays (see example).
This function computes the correlation of a1[x] and a2[x-dx],
where the index x takes all values such that x and x-dx are contained:
CCF = sum_x { (a1[x]-<a1>)/|a1| * (a2[x]-dx)-<a2>)/|a2| }
The norm |a| = sqrt{ sum_x a[x]^2 } ensures that CCF_1d(a, +-a, 0) = +-1.
for any array a.
If just a1 and a2 are give, the function returns an array which
contains all possible correlations between them. Its first entry
responds to dx=0, the second to dx=1, ... .
By default, periodic boundary conditions are taken at the edges
of the array.
EXAMPLE
variable a1 = Double_Type[N]; % some data
variable a2 = Double_Type[N]; % some other data
variable DX = [-N/2;N/2];
variable CCF = array_map(Double_Type, &CCF_1d, &a1, &a2, DX);
% If used with array_map, explicit references to a1 and a2 are required,
% as each function call to CCF_1d has to get the full array.
variable dx_opt = DX[where( abs(CCF) == max(abs(CCF)) )];
or
variable a1 = Double_Type[N];
variable a2 = Double_Type[N];
variable CCF[] = CFF_1d(a1,a2);
SEE ALSO
CCF_2d
The macros \n and \code are not relevant for plain text help files, but may become important to structure Isis:ccf 1d.pdf.
Create your own help files
Here is what you can do to use tm-strip and tmexpand to generate help files for your private function collections:
- install the tmexpand package
- copy the *.tm files from isisscripts/doc/share/ to where you can easily access them locally on you machine
- write the help to your own functions as explained above
- run tm-strip and tmexpand as
tm-strip yourfuns.sl >> yourfuns.tm tmexpand -Ipath/to/isisscripts/doc/share -Mslhlp_isisscripts yourfuns.tm yourfuns.txt
- discard yourfuns.tm
- add_doc_file("yourfuns.txt"); for ISIS to find your new help file. If you'd like to have the help files available at all times without loading them by hand, you can add this command to your .isssrc. As an alternative, you can add the help directly through yourfuns.sl in the manner of the isisscripts:
$1 = __FILE__[[:-4]]+".txt"; ifnot(path_is_absolute($1)) $1 = path_concat(getcwd(), $1); if(stat_file($1)!=NULL) set_doc_files([$1, get_doc_files()]);
However, this particular set of command only works if your help files are in the same folder as your scripts and you are not accessing your script through a softlink. It works correctly, if you required your function collection through a location that is added to your ISIS load path.