Kuehnel at 08:53, 31 July 2018

2018-07-31T08:53:51Z

← Older revision		Revision as of 10:53, 31 July 2018
Line 151:		Line 151:
	</pre>		</pre>
	* discard <tt>yourfuns.tm</tt>		* discard <tt>yourfuns.tm</tt>
	* <tt>add_doc_file("yourfuns.txt");</tt> 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 [[ISIS auto start (.isisrc)\|.~~isissrc~~]]. As an alternative, you can add the help directly through <tt>yourfuns.sl</tt> in the manner of the isisscripts:		* <tt>add_doc_file("yourfuns.txt");</tt> 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 [[ISIS auto start (.isisrc)\|.isssrc]]. As an alternative, you can add the help directly through <tt>yourfuns.sl</tt> in the manner of the isisscripts:
	<pre>		<pre>
	$1 = __FILE__[[:-4]]+".txt";		$1 = __FILE__[[:-4]]+".txt";

Kuehnel at 08:53, 31 July 2018

2018-07-31T08:53:24Z

← Older revision		Revision as of 10:53, 31 July 2018
Line 151:		Line 151:
	</pre>		</pre>
	* discard <tt>yourfuns.tm</tt>		* discard <tt>yourfuns.tm</tt>
	* <tt>add_doc_file("yourfuns.txt");</tt> 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 ~~<tt>~~.isisrc~~</tt>~~. As an alternative, you can add the help directly through <tt>yourfuns.sl</tt> in the manner of the isisscripts:		* <tt>add_doc_file("yourfuns.txt");</tt> 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 [[ISIS auto start (.isisrc)\|.isissrc]]. As an alternative, you can add the help directly through <tt>yourfuns.sl</tt> in the manner of the isisscripts:
	<pre>		<pre>
	$1 = __FILE__[[:-4]]+".txt";		$1 = __FILE__[[:-4]]+".txt";

Stierhof: Copy from old wiki, links missing

2018-04-11T12:44:17Z

Copy from old wiki, links missing

New page

The help/description of S-Lang or ISIS functions -- which can be obtained, e.g., with <code>isis> help function_name</code> --
is defined in plain text files.
(In order to take effect, these must be introduced to S-Lang's help system via [http://www.jedsoft.org/slang/doc/html/slangfun-9.html#ss9.1 add_doc_file]
-- which is usually performed by S-Lang or ISIS itself, or by an external module.
[http://www.jedsoft.org/slang/doc/html/slangfun-9.html#ss9.5 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 [http://www.jedsoft.org/jed/madewithjed.html|tmexpand script (using jed)].

Advantages of defining ''logically structured'' tm-files (using macros like <tt>\usage</tt>, <tt>\description</tt>, ...)
--
rather than ''physically formatted'' help files -- are:
* The structural elements (like <tt>USAGE</tt>, <tt>DESCRIPTION</tt>, ...) 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 [http://www.jedsoft.org/slang/docs.html S-Lang] and [http://space.mit.edu/cxc/isis/manual.html ISIS] manuals) besides S-Lang help files.
(<tt>tmexpand</tt> 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.
<tt>tmexpand</tt> comes with a <tt>tm-strip</tt> script that extracts text macros from comments enclosed by <tt>%!%+</tt> and <tt>%!%-</tt> (in S-Lang files).

A help definition within the ISISscripts,
which [http://www.sternwarte.uni-erlangen.de/git.public/?p=isisscripts;a=blob;f=doc/Makefile automatically] run the <tt>tm-strip</tt> -- <tt>tmexpand</tt> pipeline,
might look like that:
<pre>
%!%+
%\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}
%!%-
</pre>

For example, the help of the <tt>CCF_1D</tt> function:
<pre>
%%%%%%%%%%%%%
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}
%!%-
</pre>

gives the following output when called by <code>help CFF_1d</code>:
<pre>
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
</pre>

The macros <tt>\n</tt> and <tt>\code</tt> are not relevant for plain text help files,
but may become important to structure {{:isis:ccf_1d.pdf|PDF output}}.

=== 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 [http://www.jedsoft.org/snapshots/ tmexpand package]
* copy the *.tm files from <tt>isisscripts/doc/share/</tt> to where you can easily access them locally on you machine
* write the help to your own functions as explained above
* run <tt>tm-strip</tt> and <tt>tmexpand</tt> as
<pre>
tm-strip yourfuns.sl >> yourfuns.tm
tmexpand -Ipath/to/isisscripts/doc/share -Mslhlp_isisscripts yourfuns.tm yourfuns.txt
</pre>
* discard <tt>yourfuns.tm</tt>
* <tt>add_doc_file("yourfuns.txt");</tt> 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 <tt>.isisrc</tt>. As an alternative, you can add the help directly through <tt>yourfuns.sl</tt> in the manner of the isisscripts:
<pre>
$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()]);
</pre>
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.

[[Category:Isis / Slang]]

Help for ISIS/S-Lang - Revision history

Kuehnel at 08:53, 31 July 2018

Kuehnel at 08:53, 31 July 2018

Stierhof: Copy from old wiki, links missing