Latex Equation Compiler Code

1119 lines (1015 with data), 62.3 kB

<!doctype linuxdoc system>
<article>

<#if output="html">
<meta name="description" content="Latex Equation Compiler">
<meta name="author" content="Jan Rheinl&auml;nder">
<meta name="keywords" content="Latex equation symbolic computation mathematics numeric calculations spreadsheet">
<meta name="date" content="2006-05-07">

<meta name="DC.Title" content="Latex Equation Compiler">
<meta name="DC.Creator" content="Jan Rheinl&auml;nder">
<meta name="DC.Subject" content="Handbook">
<meta name="DC.Description" content="The Latex Equation Compiler Handbook">
<meta name="DC.Publisher" content="Jan Rheinl&auml;nder">
<meta name="DC.Contributor" content="Jan Rheinl&auml;nder">
<meta name="DC.Date" content="2006-05-07">
<meta name="DC.Identifier" content="http://eqc.sourceforge.net">
<meta name="DC.Source" content="">
<meta name="DC.Language" content="en">
<meta name="DC.Coverage" content="Stuttgart/Germany">
<meta name="DC.Rights" content="Copyright 2002 Jan Rheinl&auml;nder">
</#if>

<title>The EQC Handbook
<author><htmlurl url="mailto://jrheinlaender@users.sourceforge.net" name="Jan Rheinländer">
<date>Version 1.4.1, 25.02.2010
<abstract>
This Handbook describes EQC Version 1.4.1
</abstract>

<toc>

<sect>Introduction
<p>

The LaTeX Equation Compiler is a preprocessor for LaTeX files that
enables numeric and symbolic calculations. It reads equations specified by special
keywords in the LaTeX file and uses them to calculate the numeric value
of variables. Symbolic calculation capabilities are also implemented,
for example, adding two equations or substituting a variable with a
numerical or symbolic value into an equation. EQC makes use of the GiNaC library
(<htmlurl url="http://www.ginac.de" name="GiNaC library homepage">).

<p>The development of EQC was prompted by a problem which I often
encountered doing calculations in my profession as a mechanical engineer.
I would first begin writing out the problem on paper, putting together the
necessary equations, and then turn to a spreadsheet to do the actual
calculations. EQC is meant to integrate this process in a single Latex source
file.

<p>Programming language: C++, bison, flex, using kdevelop.
Implemented on Linux-i386. Cross-compiled to Windows, but not extensively tested there.

<p>EQC makes use of the GiNaC library for numeric and symbolic calculations, and of
course needs a Latex installation to be useful. If you wish to use physical units, the SIunits.sty
package is required as well.

<sect1>Changes
<p>
All code changes are documented in the source files by three asterixes (***) and the change number.

<itemize>
  <item> Version 0.1: First version made accessible on SourceForge. All basic functionality implemented.
  <item> Version 0.2:
    <itemize>
      <item> Updated SGML documentation
      <item> Added eqc-tour.tex example
      <item> Minor code enhancements
    </itemize>
    <item> Version 0.3:
    <itemize>
      <item> Minor code enhancements and bug squashing
      <item> Changed compile default to static linking because of problems with libginac, libcln, libgmp3
      <item> Added Precision_type in printing.h, modified printing of floats in printing.cpp
      <item> Better control of the format in which quantities are printed
      <item> Decimal marker is set to <tt>.</tt> or <tt>,</tt> according to the language specified
      <item> <tt>\preferredunits</tt> no longer adds the units to previously registered ones. The old units
        are now deleted and only the new ones used.
      <item> The <tt>\val</tt> macros now take an optional parameter to set the units for expressing a quantity.
      <item> Removed options <tt>thickspace, thickqspace</tt> for <tt>SIunits.sty</tt> in <tt>eqc.sty</tt>.
        The user should define his preferred spacing in SIunits.cfg.
    </itemize>
  <item> Version 0.4:
  <itemize>
    <item> Corrected Latex display of <tt>','</tt> as decimal marker by putting it in parentheses.
    <item> Added class expression to encapsulate the GiNaC <tt>ex</tt> class and make it possible to preserve
      the user's formatting of equations using the commands <tt>\raw</tt> and <tt>\eqc</tt>.
    <item> EQC now recognizes <tt>\verb</tt> and respects verbatim environments.
  </itemize>
  <item> Version 0.5:
  <itemize>
    <item> Minor code enhancements
    <item> Removed bug that caused EQC to crash if a file mentioned after <tt>\input</tt>
           could not be opened.
    <item> Enabled EQC to recognize if the left hand side of an equation becomes a symbol through
           an operator, a substitution or a reversal. The equation is then registered so that the
           value of the symbol can be computed if wished.
    <item> Manipulating an expression with <tt>+</tt>, <tt>-</tt>, <tt>*</tt>, <tt>/</tt> no sets
           the Latex representation (for <tt>\raw</tt> printing to an empty string since the former
           result was undesirable.
    <item> Added support of symbolic functions with the keywords <tt>\function</tt> and
           <tt>\deffunc</tt>. These functions can be defined at runtime.
    <item> Enabled EQC to parse vectors, i.e. <tt>{x;y}</tt>. This resulted in a change of equation
           list syntax because of the ambiguity of the ; in something like
           <tt>\eqsubst{"prev"}{x = 3; y = 4}</tt>. Equations in lists now have to be enclosed in
           brackets: <tt>\eqsubst{"prev"}{{x = 3}; {y = 4}}</tt>
  </itemize>
  <item> Version 0.6:
  <itemize>
    <item> Added keyword <tt>\eqpow</tt>.
    <item> Enabled parsing of keywords <tt>\lhs</tt> and <tt>\rhs</tt> inside expressions.
    <item> Implemented more flexible expression substitution and removed a bug concerning
           substitution of functions.
    <item> Changed scanner so that the extra brackets in equation lists are not necessary any more.
    <item> Added keywords <tt>\printeq</tt>, <tt>\deleq</tt> and <tt>\eqsimpf</tt>.
    <item> Added symbolic differentiation with the keyword <tt>\eqdiff</tt>.
    <item> Added function hints to <tt>\function</tt> to allow for nicer printing etc.
  </itemize>
  <item> Version 0.7.0:
  <itemize>
    <item> Port to g++-3.0 and GiNaC 1.2.1
    <item> Removed bug that omitted '-' sign when printing adds
    <item> Introduced concept of library equations
    <item> Added simplification type "eval" and "normal"
    <item> Added automatic normalization after division of expressions
    <item> Rewrite of the \val{} algorithm in order to speed things up
    <item> Rewrite of all message printing via the new class <tt>message</tt>
    <item> Removed <tt>using namespace std</tt> everywhere
    <item> Debianized the package
  </itemize>
  <item> Version 0.8.0:
  <itemize>
    <item> Added keywords <tt>aligneq</tt>, <tt>autoalign</tt>, <tt>noautoalign</tt> and
       <tt>dumpeq</tt>
    <item> The amsmath keywords <tt>tfrac</tt> and <tt>dfrac</tt> are now recognized (but
      not printed in eqc output)
    <item> Implemented keyword nesting (e.g., <tt>\eqsubst{z = x^2}{\eqadd{x-y = 4}{y}}</tt>, which
      would result in <tt>z = (4+y)^2</tt>)
    <item> Merged the equation and the file parser to simplify the code.
    <item> Implemented operators <tt>+</tt>, <tt>-</tt>, <tt>*</tt>, <tt>/</tt> and
       <tt>^</tt> for equations (e.g. <tt>\eqrev{"prev" + 3y}</tt>).
    <item> Added simplification type <tt>collect_common</tt>.
    <item> Added keywords <tt>\denom</tt> and <tt>\numer</tt>.
    <item> Added keyword <tt>\eqsolve</tt>.
  </itemize>
  <item> Version 0.9.0:
  <itemize>
    <item> Removed bug which did not print muls inside muls and adds inside adds.
    <item> Removed automatic expansion and normalization after divisions, this must be done
      manually now using <tt>\eqsimpf</tt>.
    <item> Changed <tt>\preferred_units</tt> to <tt>\preferredunits</tt> for LaTeX conformity.
    <item> Introduced dummy macros in <tt>eqc.sty</tt> to enable the raw tex file to be
      passed through LaTeX without generating too many errors. This allows the use of
      preview-latex in emacs, for example.
    <item> Added keyword <tt>\eqfunc</tt> to apply a function to both sides of the equation.
    <item> Added simplification type <tt>unsafe</tt>.
    <item> Added keyword<tt>\printoptions</tt>, this now replaces <tt>\autoalign</tt>.
      <tt>\raw</tt> and <tt>\eqc</tt> are now printing options <tt>eqraw</tt> and <tt>eqnoraw</tt>.
    <item> Trigonometric functions now evaluate automatically if possible (for example,
      <tt>\cos(\pi)</tt> becomes 0).
    <item> Made <tt>equation</tt> a subclass of <tt>GiNaC::relational</tt> and
      <tt>expression</tt> of <tt>GiNaC::ex</tt>, which allows a great deal of
      simplifications in the grammar.
    <item> Removed bug which prevented <tt>\val[\degree]{...}</tt> from working correctly.
    <item> Removed bug which prevented substitutions of user-defined functions from working correctly.
    <item> Changed the <tt>func::eval()</tt> routine so that it takes advantage of the simplification rules
      defined for GiNaC's hard-coded functions, e.g. <tt>\tan\arctan{x} = x</tt>.
  </itemize>
  <item> Version 1.0.0:
  <itemize>
    <item> Vectors can now be created with the syntax <tt>begin:end:step</tt>.
    <item> Port to gcc3.3.
    <item> Added wildcard function <tt>wild()</tt>.
    <item> Made differentiation of functions work and print better.
    <item> Added keyword <tt>\diff</tt> to create derivatives. They can be evaluated (that
      is, the derivative can be explicitly calculated) by <tt>\eqsimpf{...}{diff}</tt>.
    <item> Added factorial function <tt>!</tt>.
    <item> Added the sum function <tt>\sum</tt>.
    <item> Added keyword <tt>\eqevalp</tt> to evaluate functions given in parameter form.
    <item> Added keyword <tt>\eqwrite</tt> to save equations to a file and reuse them in another
      document.
    <item> Added Taylor series creation of an expression with <tt>\tseries</tt>.
    <item> Optimized the value finding code for faster execution.
    <item> Added the <tt>AM_PATH_GINAC</tt> macro to configure.in
    <item> Cross-compiled EQC to windows (see section Compilation and Installation)
    <item> Added Digits = 12 globally to aleviate problems like x^(0.99999999999999995)
  </itemize>
  <item> Version 1.1.0:
  <itemize>
    <item> Added keywords <tt>\ceil</tt> and <tt>\floor</tt>.
    <item> In equations, <tt>i</tt> is now recognized as the imaginary unit (square root of -1).
    <item> Sorted out some autoconf/automake problems and updated the documentation. Cross-compiling
      to Windows now works with the configure/make commands (see that section for details).
    <item> <tt>\eqsolve</tt> now handles problems with denominators not equal to one.
    <item> Added command-line parsing of options (see <tt>eqc --help</tt>) (but not for the Windows version)
    <item> Combined all option keywords into the common syntax <tt>\eqcoptions {'key' = 'val'}</tt>
    <item> Automatic aligning of equations (formerly <tt>eqautoalign</tt>) is now always on. It can be
      overriden by specifying a certain alignment type, e.g. <tt>\eq[eqalign=none]{...}</tt>.
  </itemize>
  <item> Version 1.2.0:
  <itemize>
    <item> Minor bug fixes.
    <item> Any equations that do not have a user-defined label are not considered any more for finding
      values, except if they are a direct assignment to a symbol.
    <item> Added keywords <tt>\valwith</tt>, <tt>quantitywith</tt>, <tt>numvalwith</tt> and <tt>unitswith</tt>.
    <item> Some beautification for the LaTeX printing routine output.
    <item> Added simplification type <tt>gather-sqrt</tt> to combine single square roots into one root symbol.
    <item> Added option <tt>eqsplit</tt> and <tt>eqsplittext</tt> to split a long equation at a given operator.
    <item> Added option <tt>vecautosize</tt> to automatically size a vector (if the step count is given as 0).
    <item> Switched to using pkg-config instead of AM_PATH_GINAC, as required by ginac >= 1.3.7
  </itemize>
  <item> Version 1.2.1:
  <itemize>
    <item> Updated to use libginac 1.4 and libcln5
  </itemize>
  <item> Version 1.3.0:
  <itemize
    <item> Added support for matrices
    <item> Removed confusion between the Euler-Mascheroni constant (0.57721...) and Euler's number (2.71828...)
  </itemize>
  <item> Version 1.3.1:
  <itemize>
    <item> Added support for integrals
    <item> Function hint <tt>no_bracket</tt> renamed to <tt>nobracket</tt>
    <item> Removed most globals to make linking as a shared library easier
  </itemize>
  <itemize> Version 1.4.0:
    <item> The code was split to provide libeqc independently from the program eqc
  </itemize>
  <itemize Version 1.4.1:
    <item> Minor changes to adapt libeqc to iMath
    <item> Changed class Unit to use a factory for creating Unit objects
    <item> Changed <tt>\eqdiff</tt> to differentiate e.g. <tt>f(x)</tt> to <tt>d f(x)/dx</tt> instead of
      differentiating the function definition. The old behaviour can be 
      achieved with the function hint <tt>defdiff</tt>.
  </itemize>
</itemize>

<sect>Installation
<p>

EQC is hosted at <htmlurl url="http://sourceforge.net/projects/eqc/" name="SourceForge">.

<sect1>How to obtain EQC
<p>

The <htmlurl url="http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/?cvsroot=eqc" name="CVS web interface">.
You can also download a source.tgz and binary packages from the
<htmlurl url="http://sourceforge.net/projects/eqc" name="EQC project page">.

<sect1>Requirements
<p>

To compile and use EQC, the GiNaC, CLN and GMP libraries are required, as well as the standard C++ development libraries, flex and bison. Information about these libraries can be found at the
<htmlurl url="http://www.ginac.de" name = "GiNaC library homepage"> and
<htmlurl url="http://clisp.cons.org/~haible/packages-cln.html" name = "CLN library homepage">
Compilation has been tested with GiNaC 1.5 using g++-4.4. Older versions will most probably not work.
Of course, a Latex installation is necessary, and the SIunits.sty package should be present if you wish to use physical units in your equations.

<sect1>Compilation and installation
<p>

In order to compile and install EQC on your system, type the following in
the base directory of the EQC distribution:

<tscreen><verb>
% ./configure
% make
% make install
</verb></tscreen>

<p>
Since EQC uses <tt>autoconf</tt> you should have no trouble compiling it.
Should you run into problems please report them to the the
<htmlurl url="mailto:jrheinlaender@users.sourceforge.net" name = "author">.

<p>
If all else fails, try executing <tt>make -f Makefile.my</tt> in the source directory. This compiles
EQC independent of all the autoconf stuff, but of course you may have to tweak the <tt>Makefile.my</tt>
to meet your local requirements.

If you want more debugging output, set the <tt>msg_info</tt> reporting level in <tt>main.cpp</tt> to higher, positive values. The default is -1 and 5 is the largest possible value (beware: This might produce a huge
amount of output!)

<sect1>Using EQC with xemacs auctex mode
<p>
In xemacs, choose Options-Advanced (Customize)-Group from the menu, and enter the group name auctex. Open the
Command group, and under List:, add the following entry:

<tscreen><verb>
[INS] [DEL] Name: EQC
            Command: eqc %t; %l "%(mode)\input{%s.eqc}"
            How: [Value Menu] TeX-run-LaTeX
            Create a process for NAME using COMMAND to format FILE with TeX.
Create a process for NAME using COMMAND to process FILE. *
            Return the new process.
            Prompt: [Toggle]  off (nil)
            Modes: [Value Menu] Set:
            * Plain TeX
            * LaTeX
            * DocTeX
            * ConTeXt
            * Texinfo
            * AmSTeX
            Menu elements:
            [INS] [DEL] Lisp expression: :help
            [INS] [DEL] Lisp expression: "Run EQC, then LaTeX"
            [INS]
</verb></tscreen>

Choose save from the top of the buffer. To run EQC, followed by LaTeX, hit
Ctrl-C twice in the buffer, and when asked for the command to run, say eqc (just typing "e"
usually is sufficient)

<sect1>Cross-compiling for Windows
<p>
EQC can be cross-compiled for windows by installing the mingw32 package. The following steps
are necessary to build EQC for windows under Debian GNU Linux:
<itemize>
  <item> Compile and install the CLN library (run configure with
    <tt>--host=i586-mingw32msvc --prefix=/usr/i586-mingw32msvc --without-gmp</tt>, then <tt>make</tt> and <tt>make install</tt>).
  Maybe it needs to be patched (see  <htmlurl url="http://thep.physik.uni-mainz.de/pipermail/cln-list/2005-April/000116.html">). 
  <item> Compile and install the gmp library. (run configure with 
	<tt>--host=i586-mingw32msvc --prefix=/usr/i586-mingw32msvc</tt>, then <tt>make</tt> and <tt>make install</tt>).
	On my system, this requires a patch to configure: Replace the statement
	<tt>BITS_PER_MP_LIMB=`expr 8 \* $ac_cv_sizeof_mp_limb_t`</tt> with <tt>BITS_PER_MP_LIMB=32</tt> (or whatever value is
	correct for your system. To find this out, insert an <tt>echo $ac_cv_sizeof_mp_limb_t</tt> and multiply by 8 manually).
  <item> Compile and install the ginac library (run configure with 
    <tt>--host=i586-mingw32msvc --prefix=/usr/i586-mingw32msvc --with-cln-prefix=/usr/i586-mingw32msvc</tt>, then <tt>make</tt> and
  <tt>make install</tt>).. You can ignore the error about libreadline not being found, since we will not be needing ginsh.
  <item> If make reports an error while compiling input_lexer.cc, edit the file config.h created by configure, and at the end,
    put <tt>#define YYTEXT_POINTER 1</tt>. If you don't want to rebuild all the files
    compiled up to then, run <tt>make -t</tt>, remove all files with size 0, and re-run make.
  <item> Probably, linking of ginsh.exe and viewgar.exe will also fail, but since they are
    not necessary, just run <tt>make -t</tt> in the subdirectories ginsh and tools.
  <item> Adapt the eqc search path in ltxfilelex.ll to your system (default:
    "C:\texmf\tex\latex\eqc\"
  <item> Set the environment variable <tt>CPPFLAGS</tt> to <tt>-DMINGW</tt> (Not required any more since version 1.4.0)
  <item> Run 'make distclean' if necessary.
  <item> Run configure with <tt>--host=i586-mingw32msvc --prefix=/usr/i586-mingw32msvc
     --with-ginac-prefix=/usr/i586-mingw32msvc</tt>. This might requiree a patch to
     <tt>/usr/i586-mingw32msvc/bin/ginac-config</tt>: Replace the line saying
     <tt>echo $libdirs -lginac -L/usr/lib -lcln -lgmp</tt> with
     <tt>echo ${exec_prefix}/lib/libginac.a ${exec_prefix}/lib/libcln.a ${exec_prefix}/lib/libgmp.a</tt>
  <item> Run <tt>make CXXFLAGS=-O0</tt>. Note that if you try to compile ltxfileparse.cc with optimization,
    you might need huge amounts of memory, depending on your system and compiler version.
  <item> You might want to strip the eqc.exe binary: <tt>i586-mingw32msvc-strip eqc.exe</tt>. This will greatly
    reduce the file size.
  <item> Install eqc.exe, eqc.sty, units.tex, substitutions.tex and mathconstants.tex into
    your favourite locations (don't forget to run texhash afterwards).
  <item> Install the html documentation from the docs subdirectory in your favourite location.
  <item> Depending on your TeX distribution, you might also have to install the siunits and fp packages.
    The first is mandatory, the second can be disabled if you comment out the makepspicture macros in
    eqc.sty.
</itemize>

<sect1>Compiling with Cygwin
<p>
EQC can be compiled for windows using the Cygwin environment.The following steps
are necessary to build EQC for windows under Cygwin:
<itemize>
  <item> Install Cygwin
  <item> Install the base system and at least the following packages:
  <itemize>
    <item> From Devel: autoconf automake bison flex gcc-g++ libncurses-devel make pkg-config readline
    <item> From Interpreters: m4
    <item> From Libs: libreadline6
    <item> From Math: gmp libgmp-devel libgmp3
    <item> From system: util-linux
    <item> From utils: diffutils
  </itemize>
  <item> Get the cln source, run <tt>configure --without-gmp</tt>, <tt>make</tt>, and <tt>make install</tt>
  <item> <tt>cp cln.pc /usr/lib/pkgconfig</tt> (or adjust the pkg-config path to <tt>/usr/local/lib/pkgconfig</tt> for the following steps).
  <item> Get the ginac source, configure, make, make install
  <item> <tt>cp ginac.pc /usr/lib/pkgconfig</tt>
  <item> Get the autoconf-archive, for example, from <htmlurl url="http://autoconf-archive.cryp.to/autoconf-archive-2008-05-16.tar.bz2">, configure, make install. 
  <item> Get eqc source. Run <tt> aclocal -I/usr/local/share/aclocal</tt>, autoconf, automake, autoheader.
  <item> Adapt the eqc search path in ltxfilelex.ll to your system (default: <tt>C:\texmf\tex\latex\eqc\</tt>
  <item> Run 'make distclean' if necessary.
  <item> Run <tt>configure CPPFLAGS="-DMINGW"</tt>, make. If compilation of <tt>ltxfileparse.cc</tt> takes forever, compile it manually with the setting <tt>-O0</tt>.
         (Note: Setting CPPFlAGS is not required any more since 1.4.0)
  <item> You might want to strip the eqc.exe binary: <tt>eqc.exe</tt>. This will greatly reduce the file size.
  <item> Install eqc.exe, eqc.sty, units.tex, substitutions.tex and mathconstants.tex into
    your favourite locations (don't forget to run texhash afterwards).
  <item> Install the html documentation from the docs subdirectory in your favourite location.
  <item> Depending on your TeX distribution, you might also have to install the siunits and fp packages.
    The first is mandatory, the second can be disabled if you comment out the makepspicture macros in   
    eqc.sty.
</itemize>

<sect1>Binary packages
<p>

If all this is too complicated for you, RPM and Debian packages have been released on SourceFourge. They
are accessible on the <htmlurl url="http://sourceforge.net/projects/eqc" name="EQC project page">.

<sect1> Bugs
<p>
<sect2> Known bugs
<p>

<itemize>
  <item> The option <tt>eqsplit</tt> must be the last one in a list, for example: 
	<tt>\eq[eqsplit=2; eqraw=true]{a + b = c}</tt> will not work correctly, but
 	<tt>\eq[eqraw=true; eqsplit=2]{a + b = c}</tt> will. The reason for this is that <tt>eqsplit</tt> takes
	an expression as an argument, and the definition of an expression allows for a list separated by semicolons.
	Therefore, an ambiguity occurs.
  <item> The number <tt>0.012345</tt> is not rounded correctly to 4 digits (precision type fixed_digits),
    rather the result ist <tt>0.1234</tt>. This appears to be a bug in the <tt>cln::round1()</tt> function
    because <tt>1234.5d0</tt> is rounded to <tt>1234</tt>, but <tt>1234.56d0</tt> is rounded to <tt>1235</tt>!
		
		Actually, it is not a bug, but a feature. The CLN documentation says (!)
		<tt>round(x)</tt>: The integer nearest to x. If x is exactly halfway between two integers, choose the even one.
</itemize>

<sect2> Reporting bugs
<p>

Please report all bugs to the <htmlurl url="mailto://jrheinlaender@users.sourceforge.net" name="author">.
You should include the following information:

<itemize>
  <item> Version of eqc, how you obtained it (RPM, CVS, binary or source).
  <item> The input file that produces the errors.
  <item> The output produced by eqc (on screen and in the file <tt>inputname.eqc</tt>).
  <item> If you compiled eqc yourself, try setting DEBUG to larger values to get more debugging output.
    This can be done in <tt>main.cpp</tt> by increasing the <tt>msg_info</tt> level to positive numbers.
</itemize>

<p>
<sect> Usage <p>

<sect1> General Usage
<p>

EQC reads LaTeX files from the command line and writes its output to corresponding <tt>.eqc</tt> files. One output
file is generated for each file given on the command line. Note that files included with <tt>\input</tt> directives are
directly included in the output file. EQC keywords contained in the input files are processed, everything else is
written out unchanged. The resulting <tt>.eqc</tt> files can then be processed like any regular LaTeX file (don't
forget to give the <tt>.eqc</tt> file extension to latex).

An auxiliary package needs to be included with <tt>\usepackage{eqc}</tt>. It takes an optional argument <tt>english</tt> or
<tt>german</tt> which defines how numbers are read (whether a comma or a point is expected as the decimal marker).
English is the default.

Inside the Latex file, equations can now be defined and registered. EQC will read the equation, produce
Latex output, and store it for later manipulation or evalution. For example:

<tscreen><verb>
\documentclass{article}
\usepackage{eqc}
\begin{document}
\input mathconstants.tex
$$\eq[eq:myequation]{x = a \sin(b)}$$
$$\eq{a = 3}$$
$$\eq{b = 3.141/2}$$
$$\printeq{"eq:myequation"} = \val{x}$$
\end{document}
</verb></tscreen>

This would produce the following Latex output (without the preamble created by including mathconstants.tex):
<tscreen><verb>
$$x = a sin(b)$$
$$a = 3$$
$$b = 1.57$$
$$x = a sin(b) = 3$$
</verb></tscreen>

In order to determine the value of the variable <tt>x</tt>, EQC automatically uses the three
equations that were registered with the keyword <tt>\eq</tt>. Note that only equations that have
in this way been explicitly registered with EQC will be used! Any other equations present in the file are
ignored. To see what else is possible in EQC have a look at the example and the reference section.

<sect1> Physical units
<p>

Because EQC was developed to tackle mechanical engineering problems, it supports physical units. The Latex
side is handled by SIunits.sty, which needs to be present on your system (it is included, for example, in the
tetex distribution). Units inside equations are designated by their Latex macro names, e.g., <tt>\mm</tt>.
Variable values can take on four different forms:

<enum>
  <item> A numerical value, like 4 or 3.141.
  <item> A unit, like <tt>\mm</tt>
  <item> A physical quantity, that is, a united and a number, like <tt>4 \mm</tt>. This form of course
    includes the first two ones.
  <item> Any other kind of mathematical expression, like <tt>x + 4 \mm</tt>. This of course includes the
    other three forms.
</enum>

The <tt>\val</tt> keyword used in the example above prints the fourth kind of variable value. If we had wished
to ensure that a numerical value is printed, we would have used <tt>\numval</tt>. EQC will then print a warning
if the value of the variable does not have this form.

<sect1> Library of substitutions
<p>

The file substitutions.tex contains a growing library of equations that are useful for working with
symbolic equations, for example, <tt>\sin(\alpha + \beta) = \sin\alpha \cos\beta + \cos\alpha \sin\beta</tt>
or <tt>\sin(\pi - \alpha) = \sin\alpha</tt>. By substitution, they can be adapted to special cases:

<tscreen><verb>
$$\eq{\cos\phi = \sin(\phi + \psi)}$$
$$\eqsubst{"prev"}{"lib:trig:sina+b"}$$
</verb></tscreen>

which would produce the following output:

<tscreen><verb>
$$\cos\phi = \sin(\phi + \psi)$$
$$\cos\phi = \sin\phi \cos\psi + \cos\phi \sin\psi$$
</verb></tscreen>

<sect1> Formatting of floating point numbers
<p>

There are several options available to control how floating point numbers are printed. The precision can be set
to a specific number of digits with <tt>\eqcoptions{precision = 'num'}</tt>.Two different concepts of precision
are implemented, these can be selected by <tt>\eqcoptions{precision_type = fixed_marker}</tt> or <tt>\eqcoptions{precision_type = fixed_digits}</tt>.

<enum>
  <item> Fixed marker: All numbers are printed with a fixed number of digits after the decimal marker.
    For example, let the precision be three digits. Then 1.2345 will be printed as 1.235, and 1234.5678 will be
    printed as 1234.568.
  <item> Fixed digits: All numbers are printed with a fixed number of digits precision. For example, let the
    precision be three digits. Then 1.2345 will be printed as 1.23, and 1234.5678 will be printed as 1230.
</enum>

Very large and very small numbers should be printed in scientific format (mantissa * 10^exponent) for the sake of
readability. The limits which determine what a "very large" or "very small" number is can be set with
<tt>\eqcoptions{scientific_limit_low = 'num'}</tt> and <tt>\eqcoptions{scientific_limit_high = 'num'}</tt>.

<sect1> Formatting of equations
<p>

Using the command <tt>\eqcoptions{eqraw = true/false}</tt> in you Latex input
file makes it possible to choose whether <tt>\eq</tt> statements should be formatted the way
you typed them or whether EQC should use it's own output function to format them. Note that
any equations obtained by <tt>\eqadd</tt> etc. will always have the EQC formatting, as EQC
can hardly foresee what you would have typed if you had written this equation yourself.

EQC formats equations inside certain environments (<tt>eqnarray</tt>, <tt>align</tt> etc.)
automatically, that is, the correct number of ampersands (<tt>&</tt>) is added before/after
the equal sign. You can override the formatting by setting the <tt>eqalign</tt> option manually.

<sect> Reference
<p>
<sect1> Basic syntax
<p>
There are two categories of keywords recognized by EQC: Keywords in the Latex file, and keywords inside
equation statements. The syntax used to describe the keywords is:

<tscreen><verb>
keyword [optarg1] [optarg2] ... {argument1} {argument2} ...
</verb></tscreen>

Arguments in square brackets are optional.

The following abbreviations for the different types of arguments are used:
<p>
<descrip>
  <tag>exp</tag>
    A mathematical expression like x + sin(y).
  <tag>equation: exp = exp</tag>
    An equation created by equating two mathematical expressions.
  <tag>equation: exp & = & exp</tag>
    Same as before, but inside an equation array. Other positions of the <tt>&</tt> are possible
    as well.
  <tag>equation: "label"</tag>
    EQC optionally accepts an equation label in any place where an equation is required. Labels
    must be enclosed in double quotes. The special equation label <tt>"prev'</tt> references the
    last equation that was registered with EQC.
  <tag>eqlist: equation OR equation ; equation ; equation ...</tag>
    Either a single equation or a list of equations separated by colons.
  <tag>unitlist: unit ; unit ; unit ...</tag>
    A list of physical unit names like \mm; \N, separated by colons.
  <tag>explist: exp ; exp ; exp ...</tag>
    A list of expressions like x; y; z^2, separated by colons.
  <tag>simplifications: simplification ; simplification ; simplification ...</tag>
    A list of strings describing simplifications to be performed on an equation.
  <tag>vector: start : end : step </tag>
    A vector beginning at <tt>start</tt> and ending at <tt>end</tt>, with steps of
    <tt>step</tt>. If <tt>end - start</tt> is not a multiple of <tt>step</tt>, the
    last element of the vector will be smaller than <tt>end</tt>. If you don't care about the size
		of the step, give a value of 0: EQC will make the vector have the number of elements defined
		by the option <tt>vecautosize</tt> (default 20).
 <tag>matrix: {element1; element2; ... elementN} OR {{element11; element12; ... element1N}; { ... }; {elementM1; ... elementMN}}</tag>
    A vector or a matrix of arbitrary expressions. The brackets are important, but not the type of bracket. A matrix can be used 
    anywhere an expression is allowed.
</descrip>

Numbers can have the imaginary unit <tt>i</tt>, which on the other hand means that you cannot use
<tt>i</tt> as a variable name.

<sect1> Keywords in the Latex file
<p>
<sect2> Keywords for manipulating equations
<p>
All these keywords take several optional arguments. The asterisk form suppresses printing the 
equation. A label may be given to the equation in square brackets. In addition, all the options listed 
for the keyword <tt>eqcoptions</tt> can be used and will then apply for this equation only. Note that
if only an equation label and no further option is provided the square brackets, the key <tt>label =</tt> 
can be omitted, and the label does not need to be quoted (<tt>""</tt>).
<descrip>
  <tag>\constant [*] {equation}</tag> Registers a constant with EQC. Constants are not erased by
    <tt>\clearequations</tt>. This makes it possible to specify general constants only once in
    the file and reuse them for several different calculations. The value assigned to this constant
    is automatically used when calculating the value of variables. The asterix form suppresses printing of
    the constant equation in the Latex output file.
  <tag>\eq [*] [[label]] {equation}</tag> Registers an equation with EQC. Only equations that have been
    registered are used to calculate the values of variables. The asterix form suppresses printing of
    the equation in the Latex output file. The equation can be assigned an optional label which may be used
    to reference it later on in the file. The Latex <tt>\ref{}</tt> command will also work with this label.
    Note that here the label may not be surrounded by quotes!
    For the special case of the equation label starting with <tt>lib:</tt>, the equation will
    not be erased by <tt>\clearequations</tt>. This is useful for building a library of generic
    equations, as for example in the file <tt>substitutions.tex</tt>.
  <tag>\deleq{label}</tag> Removes an equation such that it has no influence on future searches
    for variable values. Note that since LaTeX does not support removing labels, the label itself
    will be not be re-usable!
  <tag>\eqadd [*] [[label]] {equation}{expr}</tag> Adds an expression to the equation.  A label may be
  assigned to the result. The resulting equation is only registered with the EQC if it has been assigned a
  label. The reason for this is that the equation is usually redundant in terms of using it for calculating
  the value of variables. The asterix form suppresses printing of the resulting equation.
  <tag>\eqdiv [*] [[label]] {equation}{exp}</tag> Divides the equation by an expression. The asterix
    suppresses Latex output, the label enables the equation to be referenced later and causes it to be
    registered with the EQC.
  <tag>\eqmul [*] [[label]] {equation}{exp}</tag> Multiplies the equation with an expression. The asterix
    suppresses Latex output, the label enables the equation to be referenced later and causes it to be
    registered with the EQC.
  <tag>\eqpow [*] [[label]] {equation}{exp}</tag> Raises both sides of the equation to the
    power of an expression. <em>Beware:</em> This ignores alternative results, as in the case of
    <tt>\eqpow{x^2}{1/2}</tt>, which might evaluate to <tt>+x</tt> or <tt>-x</tt>. Only use this
    function if you are sure that you want the first possible result!
  <tag>\eqfunc [*] [[label]] {equation}{exp}</tag> Applies the expression, which must be a
    valid function name (without parameters), to both sides of the equation.
  <tag>\eqsub [*] [[label]] {equation}{exp}</tag> Subtracts an expression from the equation. The asterix
    suppresses Latex output, the label enables the equation to be referenced later and causes it to be
    registered with the EQC.
  <tag>\eqrev [*] [[label]] {equation}</tag> Swaps left hand side and right hand side of the equation. The asterix
    suppresses Latex output, the label enables the equation to be referenced later and causes it to be
    registered with the EQC.
  <tag>\eqsubst [*] [[label]] {equation}{eqlist}</tag> Substitutes expressions inside an equation. The
    <tt>eqlist</tt> argument is a list of equations separated by ';'. Any occurences of the left hand side of
    these equations is replaced by the right hand side. The asterix
    suppresses Latex output, the label enables the equation to be referenced later and causes it to be
    registered with the EQC.
  <tag>\eqsimpf [*] [[label]] {equation}{simplifications}</tag> Simplifies both sides of the equation
    according to the simplifications given in a list. Possible values are:
    <descrip>
      <tag>expand</tag> Fully expands all expressions, including function arguments.
      <tag>expandf</tag> Only expand function definition, not arguments.
      <tag>eval</tag> Numerically evaluate the equation as far as possible.
      <tag>normal</tag> Normalize the equation (see description of GiNaC normal() method).
      <tag>collect-common</tag> Collect common factors (see description of GiNaC
        collect_common_factors() method).
      <tag>unsafe</tag> Does unsafe simplifications, for example
      <itemize>
        <item> <tt>\sqrt{x^2} => x</tt>
        <item> <tt>\arctan\tan{x} => x</tt>. Note that the opposite <tt>\tan\arctan{x}</tt> is
          not an unsafe evaluation and is thus done automatically (by GiNaC).
      </itemize>
      <tag>diff></tag> Evaluates differential function <tt>\diff</tt>.
      <tag>sum</tag> Evaluates sum functions <tt>\sum</tt>.
      <tag>gather-sqrt</tag> Gathers single square roots under one root symbol.
      <tag>integrate</tag> Symbolically integrates any integrals in the expression (if possible)
    </descrip>
  <tag>\eqsolve [*] [[label]] {equation}{exp}{exp}</tag> Solves the equation for a given variable.
    The last argument indicates which solution is requested (in case there are several solutions, like
    for a quadratic equation). The function returns an assignment for the variable.
</descrip>

<sect2> Keywords for manipulating expressions
<p>
<descrip>
  <tag>\lhs {equation}</tag> Returns the left hand side of the equation.
  <tag>\rhs {equation}</tag> Returns the right hand side of the equation.
  <tag>\val [[int]] [[unitlist]] {exp}</tag> EQC replaces this keyword with the value of the specified expression (which
		usually is, but need not be, a variable). EQC tries to derive the value from the given equations
    in the form of a physical quantity. If this is not successful, a symbolic expression will be printed instead. Any
    floating point numbers will be printed with an optional precision. If the quantity should be expressed in other units
    than those set by <tt>\preferredunits</tt>, a list of units can be passed as an optional parameter.
  <tag>\valwith [[int]] [[unitlist]] {exp} {exp}
		An additional list of assignments can be given to find the value. All the assignments given are registered as new 
			equations and then the value is searched for. This is the same as doing 
				<tscreen><verb>
					\eq*[eq:temp_1]{assignment_1}%
					...
					\eq*[eq:temp_n]{assignment_n}%
					\val{exp}
					\deleq{"eq:temp_1"; ... "eq:temp_n}%
				</verb></tscreen>
  <tag>\quantity [[int]] {exp}</tag> Same as val, but an error is printed if the value of the variable is no
    quantity. Any floating point numbers will be printed with an optional precision.
  <tag>\numval [[int]] {exp}</tag> Same as val, but an error is printed if the value of the variable is no
    number. Any floating point numbers will be printed with an optional precision.
  <tag>\units [[int]] {exp}</tag> Same as val, but an error is printed if the value of the variable is no
    unit or a multiplication of several units and/or powers of units. Any floating point numbers will be printed with
    an optional precision.
  <tag>\eqeval{equation}{equation}</tag> Evaluates the first equation to a matrix of
    values. The second equation needs to have the form <tt>sym = vector</tt>. The symbol
    is treated as the independent variable, and the equation is evaluated for all values of the symbol
    given in the vector. The result is a 2x2 matrix, with the values of the independant variable in the
    first column and the evaluation results in the second column. For example:
    <tt>\eqeval{y = x^2}{x = 1:5:1}</tt> would become <tt>(1; 4; 9; 16; 25)</tt>
  <tag>\eqevalp{x-equation}{y-equation}{equation}</tag> Evaluate a function given in parameter form
    to a matrix of values. Example (the evolvent function):
    <tt>\eqevalp{x = R (\cos t + t \sin t)}{y = R(sin t - t \cos t)}{t = 0:90\degree:5\degree}</tt>
  <tag>\numer{exp}</tag> Returns the numerator of the expression.
  <tag>\denom{exp}</tag> Returns the denominator of the expression.
  <tag>\diff{exp;var;num}</tag> Creates a differential of the expression with respect to <tt>var</tt> to
    the degree of <tt>num</tt>. It can be evaluated using <tt>\eqsimpf{exp}{diff}</tt>
  <tag>\sum{equation;exp;exp}</tag> The sum function. The first equation is the lower bound, the second the upper
    bound, the third the expression to sum up. Example: <tt>\sum{n=1;3;n}</tt>. Note that the bounds must become integer values when the
    function is evaluated with <tt>\eqsimpf{exp}{sum}</tt>. 
  <tag>\tseries{exp}{equation}{exp}</tag> Creates a Taylor series for the first expression. The second
    parameter must have the form <tt>sym = number</tt>. The series is created for the dependant variable
    <tt>sym</tt> around <tt>number</tt>. The third parameter must be an integer defining the degree of
    the series expansion.
  <tag>\ceil{exp}{digits}</tag> Return the numeric value of the expression, rounded up to the nearest integer
    with the given number of digits after the decimal point.
  <tag>\floor{exp}{digits}</tag> Return the numeric value of the expression, rounded down to the nearest integer
    with the given number of digits after the decimal point.
</descrip>

<sect2> Keywords for defining new units and functions
<p>
<descrip>
  <tag>\defunit [*] [latexname] {macro}{exp}</tag> Defines a new unit. The <tt>macro</tt> is the name of the
    unit, this must begin with a backslash because a Latex macro will be created with this name for
    referencing the unit later on. The expression defines the unit in terms of units already known to the EQC.
    If this expression contains data types apart from units, powers of units, numerics, or constants already
    known to EQC, a warning is issued, but the unit definition is created anyway.

    To suppress the generation of the Latex command for this unit, use the asterix form. If you wish the
    Latex macro to output something other than the expression, supply this as an optional argument. It
    will be printed in the mathrm font.
  <tag>\function [[hints]] {name} {explist}</tag> Registers a user-defined function with EQC. The function has
    the arguments given in the explist. Example: <tt>\function{f}{x;y}</tt>. The function may be
    used in equations and expressions with or without arguments. The following hints are possible:
    <descrip>
      <tag>lib</tag> This is a library function. It will not be erased by
        <tt>\clearequations</tt>.
      <tag>trig</tag> This is a trigonometric function. It will be printed as sin²x
        instead of (sin(x))² (for example).
      <tag>nobracket</tag> This functions needs no brackets when printed (for example, the
         <tt>sqrt()</tt> function).
      <tag>expand</tag> The function will be expanded immediately (provided it has been given
        a definition). This is useful for example with <tt>square()</tt> und <tt>cubic()</tt>
    </descrip>
   <tag>\deffunc [*] {name}{exp}</tag> Define an expression which will be used to evaluate the function,
    for example, <tt>\deffunc{f}{ax^2+bx+c}</tt>. Without the asterix, this command will produce
    output like <tt>f(x) = ax^2 + bx + c</tt>.
</descrip>

<sect2> Keywords for printing results
<p>
<descrip>
  <tag>\printeq {equation}</tag> Prints the equation (this will usually be an equation label)
  <tag>\printvector{exp}</tag> Prints a vector in the format required by pstricks.sty.
  <tag>\eqwrite\filename{equation}{label}</tag> Write an equation to a file. The equation has the
    label as given. This is useful to create a file of equations, which can then be included into
    another document and reused there. A typical usage would be
    <verb>
      \printoptions{eqparse}%Turn off pretty-printing of equations
      \newwrite\eqfile%
      \immediate\openout\eqfile filename.tex%
      \eqwrite\eqfile{\printeq{"eq:example"}}{eq:example}%
      \immediate\closeout\eqfile%
      \printoptions{eqnoparse}%
   </verb>
   This file could then be reused as follows:
   <verb>
     \input filename.tex
     Equation \eqcref{"eq:example"} in 'whatever original file it came from' states
     \begin{equation}
       \printeq{"eq:example"}
     \end{equation}
   </verb>
</descrip>

<sect2> Output formatting
<p>
All options are handled by the common keyword <tt>\eqcoptions</tt>. It takes a list of key-value pairs
<descrip>
  <tag>label = <tt>string</tt> Specifies a label for the equation, the label must be enclosed in quotes (<tt>""</tt>).
  <tag>precision = integer</tag> Specifies what precision is to be used for printing floating point numbers. The
    precision is the absolute number of digits printed, more digits are rounded away. The precisions is 4
    by default.
  <tag>fixeddigits = true|false</tag> Specifies whether floating point numbers should be
    printed with a fixed number of digits after the decimal marker or with a fixed number of digits in total. The
    default is fixed_digits.
  <tag>lowsclimit = exp</tag> Defines the low limit beyond which
    floating point numbers are printed as <tt>mantissa * 10^exponent</tt>.
  <tag>highsclimit = exp</tag> Defines the high limit beyond which
    floating point numbers are printed as <tt>mantissa * 10^exponent</tt>.
  <tag>units = unitlist</tag> Specifies a list of units separated by ';' preferred for printing
    physical quantities.
    If no such list is specified, the SI base units are used. This usually makes for ugly output, for example,
    when printing forces the unit Newton. A useful list of preferred units for mechanical engineering might be
    <tt>{\mm; \N; \Nm; \Nosqmm}</tt>. The order in which the preferred units are specified is important! Simple
    units should be specified first, more complex ones later on. The reason is that the complex units usually
    imply the simpler ones, for example, <tt>\N</tt> implies <tt>\mm</tt> because 1 <tt>\N</tt> equals
    1 <tt>kg m/s^2</tt>.
  <tag>eqchain = true|false</tag> Omit the left hand side in chains of equations, in cases where only
    the rhs changed from one line to the next.
  <tag>eqraw = true|false</tag> Raw formatting of <tt>\eq</tt> statements means that
    the equations are printed exactly as you typed them in. This of course only works until
    you manipulate the equation with <tt>\eqadd</tt> etc. The other options is to have EQC format
    your equations.
  <tag>eqparse = true|false</tag> Turns of some pretty-printing features that make the LaTeX output of EQC
    difficult to re-parse. For example, cos^2(x) is printed as (cos(x))^2.
  <tag>eqalign = type</tag> Change the LaTeX alignment type of an equation. Values
    for <tt>type</tt> are 'onlyleft' (alignment will be <tt>&=</tt>, for ams math), 'both' (<tt>&=&</tt>, for eqnarray environment), 'none'.
    If no alignment type is specified, EQC automatically formats depending on the environment.
  <tag>eqsplit = exp</tag> Split the equation after the nth operand. The count starts at the left hand side of
		the equation. Operands are those parts of the equation that are separated either by addition/subtraction or multiplication symbols.
		At the given position, <tt>\\\notag</tt> or <tt>\\\nonumber</tt> are printed, depending on  
		the environment
  <tag>eqsplittext = string </tag> The text to interject after the split (in quotes <tt>""</tt>). By default, 
		this tries to align	the second part of the equation to the right of the equals sign.
  <tag>difftype = string</tag> Set the format for displaying derivatives. Possible values are <tt>dfdt</tt> for <tt>df/dx</tt> display 
    (this is also the default), <tt>dot</tt> to display one or two dots for the first and second derivative (usually used only for
    derivatives respective to the time <tt>t</tt>, and <tt>line</tt> to display apostrophes (e.g. <tt>f''(x)</tt>).
  <tag>path = string</tag> Set the path for the EQC-specific data files (default
    <tt>"/usr/share/texmf/tex/latex/eqc/"</tt> on Unix systems). 
  <tag>lang = "english"|"german"</tag> Changes the language which EQC expects the input file to use. At the moment,
    this only has an effect on parsing floating point numbers, i.e., the decimal separator is set to ',' for
    <tt>"german"</tt> and to '.' for <tt>"english"</tt> or any other language.
</descrip>

<sect2> Other EQC options
<p>
Further key-value pairs to <tt>\eqcoptions</tt> are:
<descrip>
	<tag>vecautosize = integer</tag> Specifies the size of a vector when no step count is given (i.e., the count is zero,
		<tt>x = 10:20:0</tt>. In this case, the vector will have the number of elements as given with this option (default 20).
</descrip>

<sect2> Miscellaneous
<p>
<descrip>
  <tag>\clearequations</tag> Clears the list of equations and variables. Constants are not cleared.
    Functions are cleared except for those declared in the file mathconstants.tex.
  <tag>\input filename</tag> Includes the specified file. There is no difference to the Latex <tt>\include</tt>
    command. All include files are written to one output .eqc file. The extension .tex need not be given.
  <tag>\dumpeq</tag> Write a list of all equations known to the compiler into the output file. The
    list is sorted by variable name (for assignments) and includes the equation label and number.
    This list is very useful in larger projects where it is difficult to remember the label of a specific
    equation and where it was defined. Note: This command requires AMS maths to be loaded and sets
    <tt>allowdisplaybreaks[1]</tt>!
  <tag>\usepackage[language]{eqc}</tag> This command must be used in the Latex preamble to include some
    EQC-specific commands. For the meaning of the <tt>language</tt> parameter, see <tt>\eqlang</tt>.
</descrip>

<sect1> Keywords inside equations
<p>
EQC does not parse all of the possible Latex mathematical keywords. The following keywords and tokens are recognized:

<descrip>
  <tag>Basic mathematics</tag>
    Apart from the basic addition, subtraction, multiplication and division symbols, EQC interprets the
    '^' and '_' symbols in the same way as Latex does. Note that the '*' multiplication symbol may be omitted,
    just as in Latex.
  <tag>Mathematical functions</tag>
    The functions listed below are recognized. All of these are defined in the
    file mathconstants.tex, which needs to be included. Further functions may be defined at
    runtime with the <tt>\function</tt> and <tt>\deffunc</tt> keywords.
    <itemize>
      <item>\arccos Arcus cosine.
      <item>\arcosh Hyperbolic arcus cosine.
      <item>\arcsin Arcus sine.
      <item>\arsinh Hyperbolic arcus sine.
      <item>\arctan Arcus tangens
      <item>\artanh Hyperbolic arcus tangens.
      <item>\cos    Cosine.
      <item>\cosh   Hyperbolic cosine.
      <item>\cot    Cotangens
      <item>\coth   Hyperbolic cotangens
      <item>\csc    Cosecans
      <item>\cubic  Cubic function (x^3)
      <item>\exp    Exponential function (e^x).
      <item>\ln     Natural logarithm.
      <item>\log    Decimal logarithm
      <item>\sec    Secans
      <item>\sin    Sine.
      <item>\sinh   Hyperbolic sine.
      <item>\square Square function (x^2)
      <item>\sqrt   Square root
      <item>\tan    Tangens.
      <item>\tanh   Hyperbolic tangens.
      <item>!       Factorial function
    </itemize>
  <tag>Brackets</tag>
    All the standard Latex brackets are recognized: <tt>{, \lbrace, (, [, \lbrack, \lfloor, \lceil, \langle</tt> and
    of course the corresponding right brackets. The brackets may be modified in their size by <tt>\left, \bigl,
    \Bigl, \biggl, \Biggl</tt> and <tt>\right</tt> etc. EQC checks for bracket mismatches and issues a warning. Note
    that EQC does not preserve your bracket types, but creates its own brackets and bracket sizes in the Latex output.
  <tag>Division</tag>
    The Latex keywords <tt>\over</tt> and <tt>\frac</tt> are recognized.
  <tag>Access to equations</tag>
    Equations may be accessed using the <tt>\lhs</tt> and <tt>\rhs</tt> keywords. This will provide
    the left hand side resp. the left hand side of the equation. An equation label may be given
    instead of an equation.
  <tag>Variable evaluation</tag>
    Variable evaluation with the keywords <tt>\val</tt>, <tt>quantity</tt>, <tt>\numval</tt> and <tt>\units</tt>
    can take place inside equations. For details on how this works, see the corresponding keywords in the
    description above.
  <tagg>Constants</tag>
    EQC has the following built-in constants:
    <itemize>
	<item>\pi	3.14159...
	<item>\e	2.71828...
	<item>\Euler	0.57721...
    </itemize>
  <tag>Numbers</tag>
    EQC recognizes integers and floating point numbers. The latter may not be in scientific notation as of yet.
    Whether the decimal separator is a comma or a dot is determined by the <tt>\eqlang</tt> keyword, or by
    the language parameter to <tt>\usepackage[language}{eqc}</tt>.
  <tag>Vectors</tag>
    A vector can be created with the syntax <tt>begin:end:step</tt>. For example, <tt>x = 1:3:1</tt>
    will create a vector with three rows, containing the number 1, 2 and 3.
  <tag>Integrals</tag>
    A symbolic integral can be created with the syntax <tt>\integral(x=a; b; f(x))</tt> where x is the integration
    variable, a the lower and b the upper bound, and f a function in the integration variable. Note that if f(x) does 
    not explicitly mention x, then the result will not be what you expected.
  <tag>Variables</tag>
    Any letter that is not part of a keyword is assumed to be a variable. Variable names are registered
    automatically on their first appearance. Any occurence of the same letter is taken to mean the same variable,
    until a <tt>\clearequations</tt> command is read. Any Latex macros that are not known to EQC are also
    interpreted as variable names, e.g., <tt>\phi</tt>.
  <tag>Physical units</tag>
    Physical units are identified by their Latex macro name, e.g., <tt>\mm</tt>. Any units other than the
    base SI units need to be defined with <tt>\defunit</tt> (include the file <tt>units.tex</tt> to get
    the most common physical unit definitions).
  <tag>Percentages</tag>
    To express percentages in an equation, use the <tt>\percent</tt> keyword.
</descrip>

<sect1> Command line arguments
<p>
<descrip>
  <tag>-d --debug LEVEL</tag> Produce debugging and informational output at level LEVEL
  <tag>-p --path PATH</tag> Path to EQC specific files (eqc.sty etc.)
  <tag>-v --verbose</tag> Produce verbose output (same as -d1)
  <tag>-q --quiet</tag> Don't produce any output (same as -d-1)
  <tag>-s --silent</tag> Don't produce any output (same as -d-1)
  <tag>-V --version</tag> Print program version
  <tag>-? --help --usage</tag> Produce informational output
</descrip>
Note that as of version 1.2.0, command line arguments are not yet supported on Windows.

<sect> Examples
<p>
The <htmlurl url="eqc-tour.dvi" name="EQC tour"> gives an overview of EQC functionality. It was created
with the following commands on the source file <htmlurl url="eqc-tour.tex" name="eqc-tour.tex">:

<tscreen><verb>
eqc eqc-tour.tex
latex eqc-tour.eqc
</verb></tscreen>

If you do not have a DVI viewer installed, try the <htmlurl url="eqc-tour.pdf" name="eqc-tour.pdf">
produced with pdflatex. In case you are curious what your Latex source looks like after EQC has had a go
at it, have a look at the intermediate file <htmlurl url="eqc-tour.eqc" name="eqc-tour.eqc">.

<p>

<sect>Questions and Answers
<p>

<sect1> Why is the spacing between numbers and units ugly?
<p>
You can control your spacing in the <tt>SIunits.cfg</tt> file. EQC simply uses the <tt>\unit</tt> macro
to display physical quantities.

<sect1> Why is the spacing between units ugly?
<p>
See above

<sect1> Why doesn't substitution of <tt>x^2 = y</tt> work in <tt>1/x^2</tt>?
<p>
This is a problem with GiNaC's canonical format of expressions. Your equation will be represented
as <tt>x^(-2)</tt>, so you need to substitute <tt>x^(-2) = 1/y</tt>. This is perhaps more of
a bug than a feature, but difficult to solve without manipulating GiNaC's internals.

<sect1> How do I get EQC to accept a variable name like <tt>\varphi'</tt>?
<p>
This is not possible at the moment, but you can circumvent the problem by defining a new macro, e.g.
<tt>\newcommand{\varphis}{\varphi'}</tt>.

<sect1> EQC complains about a wrong number of arguments for a self-defined function
<p>
Probably you did something like: <tt>\function{x}{y; z} $\eq{a = x b + c}$</tt>. Because
functions have precedence over multiplication, EQC parsed this as <tt>a = x(b; </tt> and
then complained about the missing second argument. EQC does not require function arguments
to be enclosed in brackets, so you can write <tt>\cos\alpha</tt> instead of
<tt>\cos{\alpha}</tt>. There are several ways to solve your problem:
<itemize>
  <item> Provide a multiplication symbol: <tt>x \cdot b</tt>
  <item> Use brackets: <tt>{x} b</tt>
  <item> Provide function arguments <tt>x(y;z) b</tt>
</itemize>

<sect1> EQC does not use my library functions for finding variable values
<p>
This is not a bug, but a feature: Library functions are assumed to be generic and must be adapted
to the special purpose you have in mind. For details, see the HTML documentation. Basically, you
need to 'activate' the equation with either <tt>\eq{"lib:myeq"}</tt> or something like
<tt>\eqsubst{"lib:myeq"}{x = x_1; y = y_1}</tt>.

<sect1> How do I use bibtex with EQC?
<p>
Just run bibtex on the original TeX file, not on the .eqc file.

<sect1> Why do my equations look ugly?
<p>
EQC's formatting algorithm is far from perfect. In fact, it will never become perfect because different people
have different ideas about what a properly formatted equation should look like. You can alleviate this problem
by using the <tt>\raw</tt> statement. This means that the contents of your <tt>\eq</tt> statements retain the
original formatting. Of course, this option does not work with equations obtained by <tt>\eqadd</tt> etc. as
there is no original formatting. After all, EQC is designed to save you the work of typing all these equations
yourself!

<sect1> AMS math complains about multiple labels
<p>
AMS math puts out an error message like <tt>Error: Multiple \label's: label '...' will be lost</tt>.
This error occurs (for example, inside an <tt>align</tt> environment) if you use <tt>\notag</tt>
with an equation that has a label, e.g.: <tt>\eqadd[eq:1]{x = 3}{4}\notag</tt>. EQC will automatically
add a <tt>\label{eq:1}</tt> when it processes the equation, and AMS math now complains that the
equation has a label but should not be tagged at the same time! You can use <tt>\tag*{}</tt> to
circumvent the problem.
<p>
Note that the standard <tt>eqnarray</tt> environment does not produce this error.

<p>
This error occurs (for example, inside an <tt>align</tt> environment) if you use <tt>\notag</tt>
with an equation that has a label, e.g.: <tt>\eqadd[eq:1]{x = 3}{4}\notag</tt>. EQC will automatically
add a <tt>\label{eq:1}</tt> when it processes the equation, and AMS math now complains that the
equation has a label but should not be tagged at the same time! You can use <tt>\tag*{}</tt> to
circumvent the problem.
<p>
Note that the standard <tt>eqnarray</tt> environment does not produce this error.

<sect1> Why does my self-compiled EQC crash immediately?
<p>
There appears to be a problem with different versions of libginac, libgmp, libcln. Not all versions of these
libraries work with EQC. If you have such a problem, try using one of the binary packages. These contain
statically linked versions of the libraries See also the bugs section.

<sect1> When I try to build the package, the command <tt>ccache</tt> is not found
<p>
I use <tt>ccache</tt> because my machine is so slow... Edit eqc/Makefile.am and remove it.

<sect1> The program does not build.
<p>
Check that you are using <tt>g++-3.0</tt>. The program will not work with g++-2.95 or earlier
(due to the GiNaC library). You can force the program to compile with g++-3.0 by setting the
environment variable <tt>CXX</tt> to <tt>g++-3.0</tt> (and <tt>CC</tt> to <tt>gcc-3.0</tt>
if necessary).

<sect1> Autoconf says that the GiNaC library is not present or has a wrong version, but that's not true.
<p>
The autoconf macro <tt>AM_PATH_GINAC</tt> might not work correctly on your system, because
it tries to run a program using <tt>ginac/versions.h</tt> with gcc instead of g++. I had
to patch ginac.m4 with <tt>AC_LANG_SAVE</tt>, <tt>AC_LANG_CPLUSPLUS</tt> and
<tt>AC_LANG_RESTORE</tt>.
<tscreen><verb>
if test "x$enable_ginactest" = "xyes" ; then
        ac_save_CPPFLAGS="$CPPFLAGS"
        ac_save_LIBS="$LIBS"
        CPPFLAGS="$CPPFLAGS $GINACLIB_CPPFLAGS"
        LIBS="$LIBS $GINACLIB_LIBS"
        rm -f conf.ginactest
        AC_LANG_SAVE
        AC_LANG_CPLUSPLUS
        AC_TRY_RUN([
include <stdio.h>
include <string.h>
include <ginac/version.h>
        ... some more code ...
        return 0;

,, no_ginac=yes,[echo $ac_n "cross compiling; assumed OK... $ac_c"])
        AC_LANG_RESTORE
        CPPFLAGS="$ac_save_CPPFLAGS"
        LIBS="$ac_save_LIBS"
fi
</verb></tscreen>
Note that you have to re-run automake/autoconf for this change to take
effect.

<sect1> KDevelop throws a fit after I run dpkg-buildpackage or do a configure by hand
<p>
Close KDevelop, remove the target directory (for example, debug). Run make -f Makefile.cvs and configure and
then make distclean and then hope for the best...

<sect>Copyright
<p>

EQC Copyright 2002-2006 Jan Rheinlaender, jrheinlaender@users.sourceforge.net

This program 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 program 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 program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
<p>

</article>