<?xml version="1.0"?>

<document extend="style.bml">

  <pageTitle>usage</pageTitle>
  <pageLink>
    <define name="usage.html" scope="global"/>
  </pageLink>

  <import document="prec_sitemap.bml"/>
  <pageNavigation>
	<maplink link="#params" 	title="Usage"	/>
        <maplink link="#configfile"	title="Configuring the conversion"	/>
        <maplink link="#preparse"	title="Finding variables"	/>
        <maplink link="#skipfile"	title="Skipping variables and functions"	/>
        <maplink link="#constants"	title="Finding constants"	/>
        <maplink link="#noprintf"	title="Printf statements"	/>
        <maplink link="#nofor"		title="For loops"	/>
        <maplink link="#init"		title="Adding extra settings after main"	/>
        <maplink link="#default"	title="MpIeee default settings"	/>
        <maplink link="#radix"		title="MpIeee radix"	/>
        <maplink link="#precision"	title="MpIeee precision"	/>
        <maplink link="#exp"		title="MpIeee exponent"	/>
        <maplink link="#expbits"	title="MpIeee exponent bits"	/>
        <maplink link="#round"		title="MpIeee rounding mode"	/>
        <maplink link="#outputverbose"	title="MpIeee verbose mode"	/>
        <maplink link="#outputmpieee"	title="MpIeee output flags"	/>
        <!--
         <maplink link="#outputrational"	title="Arithmos Rational
	 output flags"	/>-->
  </pageNavigation>

  <content>
  <firstSection id="usag" title="Usage">
  </firstSection>

  <section id="params" title="Usage and parameters">
	<p>
	Running the precompiler without parameters, displays the list of
	command line options :
	</p>
	<pre>
wschrep> ./precompile
Usage: ./precompile <lt/>inputfile> <lt/>outputfile> [options]

Options:
  <a href="#configfile">-x <lt/>configfile></a>    specifies the conversion configuration file 
  <a href="#preparse">-preparse</a>          preparse rather than precompile to generate a list of all variables and functions
                     that would normally be converted
  <a href="#skipfile">-c <lt/>skipfile></a>      specifies a file containing functions and/or variables which must not be converted
  <a href="#constants">-constants</a>         identify all constants in C/C++ file 
  <a href="#noprintf">-noprintf</a>          don't convert printf statements
  <a href="#nofor">-nofor</a>             don't convert variables in for loops
  <a href="#init">-init <lt/>initfile></a>   insert source code contained in <lt/>initfile> file after the main(){

The following options are specific for transcription with the <a href="http://www.mpieee.ua.ac.be/">MpIeee library</a>.

  <a href="#default">-default</a>           insert default <a href="http://www.mpieee.ua.ac.be/">MpIeee</a> settings after the main(){ 
  <a href="#radix">-radix <lt/>size></a>      set the radix size, default size=2
  <a href="#precision">-precision <lt/>size></a>  set the precision size, default size=24
  <a href="#exp">-exp <lt/>low> <lt/>up></a>    set the exponent, default low=-126, upper=127
  <a href="#expbits">-expbits <lt/>bitsize></a> set the number of exponent bits
  <a href="#round">-round <lt/>n|p|m|z></a>   set the rounding mode, default = n
                      n = round to nearest
                      p = round to plus inf
                      m = round to min inf
                      z = round to zero
  <a href="#outputverbose">-outputverbose</a>     set verbose output
  <a href="#outputmpieee">-outputmpieee <lt/>p|d|b|y|h|r|f>+</a> set the MpIeee output format, default = d
                      p = parameter
                      d = decimal
                      b = binary
                      y = binary representation
                      h = hexadecimal representation
                      r = rational
                      f = flags

	</pre>
<!--
 <a href="#outputrational">-outputrational <lt/>d|r|f>+</a> set the Rational output type, default = r
                       d = decimal
                       r = rational
                       f = flags
 The options -outputmpieee and -outputrational can have more than 1
 output type(indicated with the +)
 for example: ./precompile in out -outputmpieee pdy 
-->

  </section>

  <section id="configfile"	title="Configuring the conversion (-x)"	>
  <p>
	The <b>-x <lt/>configfile<gt/> </b> option specifies the
	XML configuration file that determines the conversions performed
	by the precompiler.  We write and use a new configuration file in 
	<a href="examples.html#ex9">Example 9</a>.
  </p>
  </section>

  <section id="preparse"	title="Finding variables (-preparse)"	>
  <p>
	With this option, the precompiler operates
	in preparse mode. This means that the output file will not contain
	converted source code but instead a list with the name of all
	variables and functions that would normally be converted when
	using the specified conversion configuration file.
	This option is illustrated in <a href="examples.html#ex2">Example
	2</a>. 
  </p>
  </section>

  <section id="skipfile"	title="Skipping variables and functions (-c)"	>
  <p>
  With this option, the user can
  specify a file with functions and/or variables that must not be
  converted. The format of this file is XML.
  A sample skipfile is given in <a href="examples.html#ex4">Example 4</a>.
  </p>
  </section>

  <section id="constants"	title="Finding constants (-constants)"	>
  <p>
	Analogue to the <a href="#preparse">-preparse</a> option, the <a href="#constants">-constants</a> option is used 
        to generate a file with all constants and their location in the input file.
	In <a href="examples.html#ex3">Example 3</a> this option is used.
  </p>
  </section>

  <section id="noprintf"	title="Printf statements (-noprintf)"	>
  <p>
	This option skips conversion of printf statements. This overrules
	the default behavior of the precompiler which converts
	<b> printf </b> statements to <b> std::cout </b>
	instructions. The default behavior is the obvious choice when
        converting standard types to C++ class types. This option is
	illustrated in <a
	href="examples.html#ex1">Example 1</a>.
  </p>
  </section>

  <section id="nofor"		title="For loops (-nofor)"	>
  <p>
	With this command line option, variables declared in for-loops are not converted.
	This option is illustrated in <a href="examples.html#ex1">Example
	1</a>. 
  </p>
  </section>

  <section id="init"		title="Adding extra settings after main (-init)"	>
  <p>
	With the option <b> -init <lt/>initfile<gt/> </b>, the C/C++ code in the 
	initfile will be inserted at the beginning
	of the main function. It is mainly used to add extra
	initialization code.
	The same effect can also be achieved by using an <lt/>init<gt/>
	tag inside a <a href="#configfile">configuration file</a>.  
	The usage of this option is illustrated
	in <a href="examples.html#ex7">Example 7</a>.
  </p>
  </section>


  <section id="default"	title="MpIeee default settings (-default)" >
  <p>
        The MpIeee default settings for radix, precision, exp, expbits,
	rounding mode, and output format are inserted into the <b> main </b>
	routine of the input file. The default MpIeee settings can be overridden using one of the following options:
        <a href="#radix">-radix</a>, 
	<a href="#precision">-precision</a>, 
	<a href="#exp">-exp</a>, 
	<a href="#expbits">-expbits</a>, 
	<a href="#round">-round</a>, 
	<a href="#outputverbose">-outputverbose</a>, 
	<a href="#outputmpieee">-outputmpieee</a>. 
	<!-- <a href="#outputrational">-outputrational</a> .-->
	See Examples <a href="examples.html#ex5">5</a> and <a href="examples.html#ex6">6</a>.
  </p>
  </section>

  <section id="radix"		title="MpIeee radix (-radix)"	>
  <p>
	Initializes the given radix size in the main function. Needs to
	be used in combination with the <a href="#default">-default</a> option.
	The radix must be a power of 2 or 10. The default radix setting is 2.
	With the options 
        </p>
        <pre>./precompile in.cpp out.cpp -radix 16 -default </pre> 
	<p>the following is inserted in the main function of out.cpp:</p>
	<pre>MpIeee::fpEnv.setRadix(16);</pre>
	<p>See also <a href="examples.html#ex5">Example 5</a>. </p>
  </section>

  <section id="precision"	title="MpIeee precision (-precision)"	>
  <p>
	Initializes the given precision in the main function. Needs to be
	used in combination with the <a href="#default">-default</a> option.
	The default precision setting is 24. The given precision should be
	larger than or equal to 4. 
	With the options </p>
        <pre>./precompile in.cpp out.cpp -precision 5 -default </pre>
	<p>the following is inserted in the main function of out.cpp:</p>
	<pre>MpIeee::fpEnv.setPrecision(5);</pre>
  <p>	See also <a href="examples.html#ex5">Example 5</a>.
  </p>
  </section>

  <section id="exp"		title="MpIeee exponent (-exp)"	>
  <p>
	Sets the minimum and maximum exponent sizes L and U.
	The defaults are L=-126 and U=127. 
	This option needs to be used in combination with the <a href="#default">-default</a> option.
	For example
  </p>
        <pre>./precompile in.cpp out.cpp -exp -2000 1999 -default</pre> 
        <p>inserts the following in the main function of out.cpp:</p>
	<pre>MpIeee::fpEnv.setExponentRange(-2000,1999);</pre>
  <p>
	See also <a href="examples.html#ex6">Example 6</a>.
  </p>
  </section>

  <section id="expbits"	title="MpIeee exponent bits (-expbits)"	>
  <p>
	Sets the number of exponent bits. The default is 8 bits, which
	corresponds to L=-126 and U=127.
	Use this option only in combination with the <a href="#default">-default</a> option.
	For example, 
  </p>
        <pre>./precompile in.cpp out.cpp -expbits 16 -default</pre> 
  	<p>inserts the following in the main function of out.cpp:</p>
	<pre>MpIeee::fpEnv.setExponentRange(-32766,32767);</pre>
  <p>
	See also <a href="examples.html#ex5">Example 5</a>.
  </p>
  </section>

  <section id="round"		title="MpIeee rounding mode (-round)"	>
  <p>
	Sets the rounding mode (n,p,m,z). The default setting is round to
	nearest.
	Use only in combination with the <a href="#default">-default</a> option.
	With the options</p> 
	<pre>./precompile in.cpp out.cpp -round z -default </pre> 
	<p>the following is inserted:</p>
	<pre>MpIeee::fpEnv.setRound(FP_RZ);</pre>	
  <p>	See also <a href="examples.html#ex5">Example 5</a>.
  </p>
  </section>

  <section id="outputverbose"	title="MpIeee verbose mode (-outputverbose)"	>
  <p>
	This sets the ARITHMOS_IO_VERBOSE flag of the library which has the effect that more verbose information is printed when calling different
        routines in the MpIeee library. Use this option only in combination with the <a href="#default">-default</a> option.
	For example,
  </p> <pre>./precompile in.cpp out.cpp -outputverbose -default</pre>
  <p>inserts the following line of code in the main function of out.cpp:</p>
	<pre>ArithmosIO::setIoMode(ARITHMOS_IO_VERBOSE|ARITHMOS_IO_MPIEEE_DECIMAL);</pre>
  <p>This is illustrated in <a href="examples.html#ex6">Example 6</a>.
  </p>
  </section>

  <section id="outputmpieee"	title="MpIeee output flags (-outputmpieee)"	>
  <p>
	This option enables various output formats for
	MpIeee variables. Use this option only together with the <a href="#default">-default</a> option.
	To enable all 6 available MpIeee output options, include the following options:</p>
	<pre>./precompile in.cpp out.cpp -outputmpieee pdbyhf -default</pre>
  <p> This will set all available output options in out.cpp:</p>
	
	<pre>ArithmosIO::setIoMode(ARITHMOS_IO_MPIEEE_PARAM|ARITHMOS_IO_MPIEEE_DECIMAL|
                                   ARITHMOS_IO_MPIEEE_BINARY|ARITHMOS_IO_MPIEEE_BINREP|
                                   ARITHMOS_IO_MPIEEE_HEXREP|ARITHMOS_IO_MPIEEE_FLAGS);</pre>
  </section>

  <!-- <section id="outputrational"	title="Arithmos Rational output flags (-outputrational)"	>
  <p>
	This option enables you to set various output flags for Rational objects from arithmos. Also use it together with <a href="#default">-default</a> option.
	To turn on all 3 available Rational flags you use the following options:</p>
	<pre>./precompile in.cpp out.cpp -outputrational drf -default</pre> 
  <p>and this will activate all available output flags in out.cpp:	 </p>
	<pre>ArithmosIO::setIoMode(ARITHMOS_IO_MPIEEE_DECIMAL|
                                   ARITHMOS_IO_RATIONAL_DECIMAL|
                                   ARITHMOS_IO_RATIONAL_RATIONAL|
                                   ARITHMOS_IO_RATIONAL_FLAGS); </pre>
  <p>	Demonstrated in <a href="examples.html#ex6">Example 6</a>.
  </p>
  </section> -->


  </content>

</document>
