/*-*- c++ -*-****************************************************************** * GraceTMPL Library * Copyright (C) 2001,2002 Andy Thaller * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License as * published by the Free Software Foundation; either version 2 of * the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this library; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA *****************************************************************************/ /* This file contains NO source code, just some documentation for doxygen to parse. */ /** @mainpage GraceTMPL Index Page @section intro Introduction XmGrace is a very powerful tool to produce 2D-Plots of your data. However, though there is also support for running grace in batch mode there is a certain lack in support for automation. When it comes to producing a presentation of your data on many sheets and your preferred formatting of the data should change sometime in the process, you could easily be confronted with a bunch of work doing the necessary changes. The GraceTMPL classes provide an easy way to use existing grace-files as a template to format any number of graphs in a predefined way and save them as grace-files. This way you can apply the same graphical appearance to all of your data. In case your preferences change, you just alter the template and reformat your complete set of data within the shortest amount of time. The capabilities of GraceTMPL include: - The application using the GraceTMPL classes can define environment variables for the sheet, each graph and each dataset. The variables can be used in the template for dynamic string replacement. Even output filenames can be templated using variable substitution. - Datasets in the template file can be marked to be included in the destination files for easy reference. - Datasets can be tagged with arbitrary information strings to be interpreted by the application using GraceTMPL. This way information can be passed to the application on how to create the datasets and what kind of information is intended by the template author. - In case no template file is loaded by the application, GraceTMPL::Save will output plain sets of data tables which can easily be imported by XmGrace or other applications. See the 'screenshot' below for a first introduction to some of the features and section \ref examples for more. @par Project admins: Andy Thaller \
Andi Brodschelm \
@section screenshot Screenshot The image below shows an example template and the file produced using this template.
\image html demo-template-small.jpg \image html demo-output-small.jpg
Note, that the appearance of the graphs hasn't changed a bit, whereas the data and the variables have been exchanged by the application. On another page you can see some annotations to the template. See the @ref examples section to see more before/after images. @section downloads Downloads - Downloads are available on the Sourceforge Download Page. - Anonymous CVS is also available: To be on the burning edge of GraceTMPL development, the CVS repository can be checked out through anonymous (pserver) CVS with the following instruction set. When prompted for a password for anonymous, simply press the Enter key. @code cvs -d:pserver:anonymous@cvs.gracetmpl.sourceforge.net:/cvsroot/gracetmpl login cvs -z3 -d:pserver:anonymous@cvs.gracetmpl.sourceforge.net:/cvsroot/gracetmpl co gracetmpl @endcode Please keep in mind that compilation of a CVS version might fail. Bugfixes are welcome anytime :-) - Last night's CVS tarball can be found here. @section docref Documentation You are already viewing the automatically generated docs for GraceTMPL. However, there are some special pages we would like to refer to for convenience's sake: - Visit the Sourceforge Project Page on http://sourceforge.net/projects/gracetmpl/ - View the \ref changes to see what's happening. - Check the \ref installation. - The page about @ref examples gives you a nice graphical summary of template capabilities. - When designing a template, you might find @ref tmpl_knowledge useful. @section news News - Anytime soon
New \ref rel0_x_y
- 24-Sep-2004
New \ref rel0_3_2
No autoscaling on hidden datasets Python wrapper adapted to numarray API - 11-Oct-2002
New \ref rel0_3_0
Homepage on SourceForge now created w/ doxygen
Python wrapper included. Some new features and bugfixes - 23-Sep-2002
New \ref rel0_2_0
New design of the homepage on SourceForge and even some 'screenshots'.
- 16-Aug-2001
First \ref rel0_1_0
*/ /** @page demo_tmpl_big
@image html demo-template-big.jpg
*/ /** @page demo_outp_big
@image html demo-output-big.jpg
*/ /** @page annotations Annotated template
@image html demo-annotated.jpg
@par A The two datasets shown in red and black will be generated from file#1 using rule tiso and tani, respectively (as indicated by $'1:tiso and $'1:tani). The legend entry will be depending on what the application sets for $rule in each of the datasets (this will be tiso and tani). Note that the datasets of all other graphs have similar legend strings, with varying filenumbers.
@par B The data files contain certain auxiliary information concerning the conducted experiment. The application provides this information in form of variables. The text object shown here can access a variable named probe that was set for the graph g0 (with the light red background color) by stating "${g0::probe}". In case the variable could not be set, the fallback string "N/A" will be printed instead.
@par C Here, the same variable as in annotation B is accessed. However, since it is referred to from within the subtitle of set g0, we can simply use "${probe}" instead of "${g0::probe}". Both ways are valid, here.
@par D Here you can see a variable reference without a fallback string. If for any reason, zero in graph g2 cannot be resolved, the result will be no change to the string at all, i.e. the generated file will show "zero=${g2::zero}" to help you find the problem.
@par E By default, GraceTMPL autoscales the axes according to the data provided by the application. This behavior can be suppressed by the template for certain axes. Prepending and Suffixing the axis title with two spaces is sufficient (that's why you can't really see it here...).
*/ /** @page installation Installation notes You'll have to download a version of GraceTMPL, first. Follow the instructions in the @ref downloads section to do so. @section compilation Compilation After downloading and unpacking the GraceTMPL source distribution or checking out the cvs version, change the working directory to the GraceTMPL sources. Please note that you must have numarray installed to be able to compile the python wrap. Also note that it's really worth it! If you have not yet done so, copy Makefile.defs.tmpl to Makefile.defs and edit it to contain your preferred installation path. Normally, the base path is @c /usr/local, so binaries will go to @c /usr/local/bin , libraries to @c /usr/local/lib and header files to @c /usr/local/include . Now you can just type @code # make # make pythonwrap @endcode If numarray is not installed on your system the pythonwrap will not be built. After a cvs update it might happen that you are advised to edit Makefile.defs again. You can safely leave your settings, but it would be wise to compare Makefile.defs.tmpl with Makefile.defs to see if any important declarations are missing in the latter. @section install Installation If all of the above went well you can now type @code # make install # make python_install @endcode If the installation base directory is not writable for you, you have to do it as root. Upon installation, the script gracetmpl-config will be installed in the binary destination directory. It can be taken by projects using GraceTMPL to identify the necessary CFLAGS and LIBS settings for compilation of the project. You can use 'gracetmpl-config --cflags' and 'gracetmpl-config --libs' for that. @section make_test Making the tests There are several tests contained in the directory tests to check GraceTMPL's correct behavior and also put on a little show. The tests' output are included in the docs' section \ref examples. @code # make test @endcode should do. The results are \c .agr files you can open with @c xmgrace. @section make_docs Building the docs Normally you wouldn't have to build the docs since GraceTMPL is already shipped with complete docs. Only when starting from a CVS-version you might want to take this step. Note you must have Image Magick installed to be able to build the test output images for the section \ref examples. Doxygen is an essential must-have to process the inline documentation. If all prerequisites are met, just type @code # make doc @endcode */ /** @page todo ToDo - There are some strange behaviours when there are set requests in graphs which come after empty graphs. Actually data gets inserted in other graphs, then. This is a design flaw, so the user should be warned about it. To fix it, we must redesign the concept of graph (also also data) handling. This will possibly require some API changes, while the behaviour must stay consistent for working templates. - Revise the build system - consider autoconf/automake (or something more lightweight?) - We still have that feature of applying the style of the first graph to all others. This could cause significant pain with the new features (like @ref dict_protected_graph, @ref dict_copy_data, etc.). Maybe we should drop that one feature in favor of the others. */ /** @page changes Changelog @section differentversions Releases - @ref rel0_x_y - @ref rel0_3_2 - @ref rel0_3_0 - @ref rel0_2_0 - @ref rel0_1_0
@section rel0_x_y Release 0.x.y @par Feature additions: @par Bugfixes: @par Changes:
@section rel0_3_2 Release 0.3.2 No autoscaling on hidden datasets Python wrapper adapted to numarray API @par Bugfixes: - Data hidden in the template was used for autoscaling which can be quite annoying in most cases. Ausoscale now honours the hidden flag. @par Changes: - Numeric Python seems to be deprecated, so we switched to Python NumArray.
@section rel0_3_0 Release 0.3.0 @par Feature additions: - Thanks to Andi Brodschelm we now have a @b python @b wrap for GraceTMPL. - Certain graphs contained in the template can be completely hidden from the application (see @ref dict_protected_graph) - Datasets can be exact copies of other datasets provided by the application (see @ref dict_copy_data) - Output pages can be sent to a pipe. To ensure maximum security, this behavior has to be turned on explicitly by the application. @par Bugfixes: - Found bug in autoscale: When autoscaling was turned off for a certain axis data that got invisible this way still was used to autoscale the other axis. - @ref dict_literal_data, when last set in a graph, produced a SIGSEGV @par Changes: - Revised and added bigger parts of the API documentation. - Added docs on template features. - Added docs on how GraceTMPL works internally (in parts).
@section rel0_2_0 Release 0.2.0 @par Bugfixes: - Some minor bugs removed @par Feature additions: - Templates can pass arbitrary per-dataset-strings to application - New environment system for variable expansion. Allows variables to be set for datasets (application side) and referenced from datasets (template side). Thus also legend strings can be expanded. @par Changes: - Cleaned up the code a lot, did some necessary API changes which only affect internals. - Minor API change regarding setenv() (see @ref GraceTMPL::EnvironmentUser). - Revised build system. A static library is produced and installed in a choosable location. Third-party projects can use gracetmpl-config to learn about compiler flags and linking options.
@section rel0_1_0 Release 0.1.0 This is the first release. */ /** @page dictionary Terminology This is a proposal on how to name things in GraceTMPL. It's work in progress, so stay tuned.
@section dict_variable Variable A variable is a value with a name and can be set by the application within a certain environment
@section dict_environment Environment is the context for a number of variables. Environments can be organized in a treelike structure, i.e. each environment may have one other environment where it resides in and a number of other environments which reside in it.
@section dict_variable_substitution Variable substitution is the action where a certain variable name with an optional context name and fallback value are used to produce a new value. For this, the current environment is searched for a variable with the specified name. If the first part of the given context matches one of the child environments, the variable is searched in the corresponding environment. If this lookup doesn't yield a value (even an empty string is a value!) the parent environment is asked for substitution. If we should end with no successful lookup at all, the fallback value is returned, if one was given. If it was omitted, the resulting string will be a description of the variable specification to allow for template debugging
@section dict_variable_expansion Variable expansion operates on a string which may contain any number of variable specifications which are parsed for context, variable name and fallback string. With these informations, the variable specification is replaced by the result of the variable substitution.
@section dict_variable_specification Variable specification is a string which addresses a variable within a certain context and may contain a fallback value. Valid variable specifications are (within quotes): - "$NAME" - "${NAME}" - "${NAME:}" (here, the fallback is "") - "${NAME:FALLBACK}" - "${CONTEXT::NAME}" - "${CONTEXT1::CONTEXT2::NAME}"
...
@section dict_protected_graph Protected graph is a graph to which the application cannot add data. The application will not even know the graph is there. It doesn't appear in the requestinfo and also doesn't add to the graphs-per-page count. Even so, it will be processed when producing output files, literal data is taken as found in the template and copy-data-sets will be copied. Variable expansion is fully functional but there (naturally) are no variables set in the graph. A graph can be marked a protected graph by adding two spaces (" ") to the front and the end of the graph's subtitle. If the subtitle is otherwise empty, this makes four spaces.
@section dict_literal_data Literal-data is a dataset which appears in the template and is literally passed to the output file. It's invisible to the application, i.e. it does not appear in the requestinfo list and cannot be changed or overwritten by the application. Variable expansion works, however, though (naturally) no variables can be set within the literal-data-set. Graph autoscaling is turned off for literal data. When "-set" is omitted, the data itself is referred to, otherwise all additional information, like legend string, formats, etc. are included. Literal-data-sets are marked by adding "$!" to the end of their legend string.
@section dict_copy_data Copy-data is a dataset which gets its data by copying that of another data set. The source data must have been produced by the application, i.e. it must not be literal-data or copy-data. The copy-data-set itself is invisible to the application, i.e. it does not appear in the requestinfo list and cannot be changed or overwritten by the application (in this regard it's very similar to literal-data-sets). As with literal-data-sets, variable expansion works, though (naturally) no variables can be set by the application. When "-set" is omitted, the data itself is referred to, otherwise all additional information, like legend string, formats, etc. are included. Data can be copied by adding a special string to the destination set's legend string, namely "$' @section dict_autoscaling Autoscaling is done to adjust a graph's axis ranges to show all of the data the application provides. The only kind of data not taken into account is literal data. GraceTMPL's autoscale function works somewhat different from the one XmGrace provides, the emphasis is on displaying as much data as possible, not on prettifying the axis range (this is no insult on the XmGrace autoscale policy!). Autoscaling is turned on for each axis by default and can be turned off explicitely by adding two spaces (" ") to the front and the end of the axistitle. If the axistitle is otherwise empty, this makes four spaces. */ /** @page tmpl_knowledge The Template Knowledge Base Here you'll find some useful information on some magic to be used in a template ------------------------------------------------------------------------------- - There are two major ways to layout your template: Either you know how many data sets go to each graph (in which case the template gives hints to the application on what kind of data to put into which set) or you don't (here, the application decides how many and which datasets go to which graph). In either case, the number of graphs per page is fixed and the number of pages depends on the number of graphs to be written. - VARIABLES are written as $NAME or ${[CONTEXT::[CONTEXT::[..]]]NAME[:DEFAULT]} (simplest form is ${CONTEXT::NAME:DEFAULT}, stuff in [] is optional, [..] denotes further contexts) - Any context automatically uses variables from the surrounding context (i.e. a set uses those from the graph it's in) unless it has a variable with the same name.
VARIABLE expansion will always match a variable defined in the current context (Gx or Gx::Sy) - a variable in the page context is accessible using "::NAME". To address another set in the same or another graph, "Sx::NAME" or "Gy::Sx::NAME" can be used, respectively. - VARIABLES of a certain graph can be accessed as $NAME or ${NAME} from within that graph and with ${Gx::NAME} from text objects (x is the graph number). - Most global variables are set by the application. Useful variables to be set could be $file, $path, $ext, etc. - Some global variables are set by GraceTMPL itself, these are: - $p is the number of the page, starting with 1 - $pz is also the number of the page, but with leading zeros (enough to reach the number of digits needed by the largest pagenum - this is very useful when used for filename templates, i.e. "output-$pz.agr") - $P is the number of pages, or files, to be saved - $filename is the name of the current output file - Autoscaling can be turned off for a specific graph axis by placing two space at the beginning and the end of the axis title, i.e. " TITLE ". If there is to be no title, use four spaces: " " - Normally, the application sets the legend string for a certain dataset. - There are certain ways to change that behavior by adding one of the following to the legend string: - $' : take the legend string as given in the template - $! : keep this dataset, don't overwrite it from the app - this is quite useful to include reference data in the template - Data can be copied from one set to another. Just append the following to the legend string of the destination set with x and y being the graph and set number of the source set:
  • $' $= Please note that literal data cannot be copied this way. It's not much sense anyway, better use XmGrace's "Edit/Set operations.../Copy" mechanism instead - Information interpretable by the application can be set by adding one of the following to the legend string:
    • $'INFO : take the legend string as given in the template, pass INFO to the application
    • $=INFO : only pass INFO to the application, legend string is provided by the application
    All template dataset information can be queried calling the method GraceTMPL::Save::templateDataRequestInfo() - the information for dataset S in graph G is represented by the string templateDataRequestInfo()[G][S]. */ /** @page examples Examples and tests This page shows some examples produced by the example application, gracetmpldemo, using several templates. In each image, you will find two frames: Left-hand-side the template, right-hand-side the result using that template. For variable expansion, a fallback value "@c FAILED" is used for evaluation purposes. @section test_01 Test01: basic data-type and legend-string test In this test, two data types are demonstrated, i.e. data provided from the application and \ref dict_literal_data which is provided by the template and goes literally to the output. Also, different ways of handling the legend string are shown. The test is performed using a python script. \image html test01.jpg @section test_02 Test02: copy-data and literal-data with variable expansion In this test, the template contains two graphs, one of which is hidden from the applications and contains \ref dict_copy_data sets and a \ref dict_literal_data set. This so-called \ref dict_protected_graph contains a reference to a variable from another graph which tests for correct setup of the environment internals. This also applies for the variable references in the copy-data and literal-data sets. Note the subtle difference between the two copy-data sets in magenta and red: The magenta one copies data from G1.S0 and uses the legend string the application sets for that dataset (which is the filename, @e transient.dat ), denoted by @c "$=" . The red copy-data set copies the same data, but uses the legend string provided by the template, as indicated by "$'". As the data points are the same for both the magenta and the red curve, you can only see the latter lying on top, actually. The test also shows, that autoscaling can be turned off for certain axes (see lower graph) and that literal data is not used for autoscaling purposes (see blue data in upper graph). The test is performed using the @c gracetmpldemo application. \image html test02.jpg @section test_03 Test03: variable expansion and environments This test shows how well variable expansion within the various environments works. The environments are: - The sheet: The test application sets the variable \c application in the sheet's environment. This variable can be addressed from \e anywhere in the template (here only demonstrated with text objects). GraceTMPL itself sets the variables \c pz and \c P which are the current pagenumber and the number of pages, respectively. Text objects reside in the sheet's environment. All graphs on the page are children to the sheet, as far as environments are concerned. - The graph: In each graph, the test application sets a variable \c graph which tells the name of the graph in the application. As shown with text objects and graph subtitles, the variable \c graph inside a graph can also be accessed from anywhere. Graph environments have the sheet as their surrounding environment and all contained sets as children (see below). - The dataset: The test application sets a variable \c what in all datasets telling the name of that set. As always, these variables can be accessed from anywhere in the template, as shown with text objects and dataset legend strings. Each of the environments can contain \e any number of variables - which of those are used in the template, is totally up to the template author. Also, if a variable is addresses from within the template that wasn't defined by the application, a fallback value can be used to print instead. Otherwise, nothing happens. \image html test03.jpg @section test_04 Test04: multiple output pages This test shows how GraceTMPL behaves when the application stores more graphs than the template defines. The output filename should then contain the pagenumber (i.e. @c filename-$p.agr ). GraceTMPL automatically outputs as many files as needed to store the requested graphs. The pure horizontal and vertical data on pages 2 and 4 show how autoscale behaves, when the data has no true range in one dimension. \image html test04.jpg @section test_05 Test05: autoscaling, hidden data This test demonstrates graceTMPL's built-in autoscaling and how well this feature ignores hidden data. The test application supplies data with 100 times larger amplitude to the hidden data set and still the nonhidden data is scaled properly. \image html test05.jpg */