Commit 7d871cd1 authored by Franksen, Benjamin's avatar Franksen, Benjamin
Browse files

added documentation of file format to index page

parent d59ed888
......@@ -58,6 +58,45 @@ Documentation
For the csm library, have a look at the `Doxygen generated API docs`_,
otherwise see :doc:`cvtRecord`.
File Format
^^^^^^^^^^^
There are two kinds of table files accepted by the csm library:
one-dimensional and two-dimensional. For both formats the file consists of a
number of lines; each line must not be longer than 1023 bytes (including the
line terminator(s)) for two-dimensional tables and 127 bytes for
one-dimensional tables.
Lines that are empty (i.e. consist only of white space), or start with a '#'
byte (possibly preceded by white space) are silently ignored.
All other lines should consist of two or more *elements*, separated by (any
positive amount of) white space (including tabs). Leading and trailing white
space is ignored. The number of elements per line must not be greater than
512 for two-dimensional tables, and 2 for on-dimensional tables.
Elements are whatever scanf accepts when given the "%lf" format specifier,
i.e. standard C floating point literals.
A one-dimensional table specifies a function of with one parameter. It must
have exactly two elements per line. The first element is the X coordinate,
the second the Y coordinate. The csm library has functions to convert in
both directions (see `csm_x`_ and `csm_y`_).
A two-dimensional table specifies a function with two parameters. The first
line and the first column specify the XY-grid. The first line must have
exactly one element less than the remaining lines; it specifies the Y
coordinates of the grid. The first column (i.e. the first elements of the
remaining lines) specify the X coordinates of the grid, while the remaining
elements specify the value (Z coordinate) at the corresponding point in the
grid (see `csm_z`_).
Lines and columns can be specified in any order. Particularly, there is no
need to specify them in ascending or descending order. However, for
one-dimensional tables, the result is only well-defined if the table
actually defines a function in the specified direction. That is, equal input
coordinates should map to equal output coordinates. Also, for non-monotonic
functions, `csm_x`_ is not the inverse of `csm_y`_.
Problems
--------
......@@ -74,3 +113,6 @@ authors.
.. _EPICS: http://www.aps.anl.goc/epics/
.. _browse the repository: http://www-csr.bessy.de/cgi-bin/darcsweb.cgi?r=csm;a=summary
.. _Doxygen generated API docs: csmApp/html/csmbase_8c.html
.. _csm_x: csmApp/html/csmbase_8c.html#6226f2df9d594321101657cd5c53bb7d
.. _csm_y: csmApp/html/csmbase_8c.html#c28ee80fa3bcc8174ff0844ff92e981f
.. _csm_z: csmApp/html/csmbase_8c.html#c0e3dcd535ce486f004128f9c270cb2b
Supports Markdown
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