<?xml version='1.0'?>

<!-- ====================================================================== -->
<!-- = chapter-1.xml                                                      = -->
<!-- = afnix cross spreadsheet - chapter 1                                = -->
<!-- ====================================================================== -->
<!-- = This  program  is  free  software; you  can redistribute it and/or = -->
<!-- = modify it provided that this copyright notice is kept intact.      = -->
<!-- = 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. In no event = -->
<!-- = shall  the  copyright  holder be liable for any  direct, indirect, = -->
<!-- = incidental  or special  damages arising  in any way out of the use = -->
<!-- = of this software.                                                  = -->
<!-- ====================================================================== -->
<!-- = copyright (c) 2005-2007 - amaury darsch                            = -->
<!-- ====================================================================== -->

<chapter client="axs" number="1">
  <title>Getting started</title>

  <p>
  This chapter is short introduction to the <afnix/> cross 
  spreadsheet or <product>axs</product>. The <afnix/> spreadsheet is a
  special interpreter that provides special commands to manipulate
  spreadsheets, made out of sheet and folio. The
  <product>axs</product> interface is also designed to ease some
  operations like loading or saving sheets.
  </p>

  <!-- invocation and termination -->
  <section>
    <title>Invocation and termination</title>

    <p>
    The <product>axs</product> spreadsheet is started by typing the
    command <command>axs</command>. Once started, the spreadsheet reads
    the commands from the terminal. Since the spreadsheet is built on top
    of the <afnix/> interpreter, any command is in fact a special form
    that is executed by the interpreter. The natural way to invoke the
    debugger is to pass the primary file to execute with eventually some
    arguments.
    </p>

    <example>
    zsh&gt; axs PROGRAM [arguments]
    </example>

    <p>
    When the spreadsheet is started, a prompt <tt>'(axs)'</tt> indicates
    that the  session is running. The session is terminated like any
    <afnix/> interpreted session by using <em>ctrl-d</em>. 
    </p>

    <example>
    zsh&gt; axs PROGRAM
    (axd) 
    </example>

    <!-- spreadsheet options -->
    <subsect>
      <title>Spreadsheet options</title>

      <p>
      The available options can be seen with the <option>-h</option>
      option and the current version with the <option>-v</option>
      option. This mode of operations is similar to the one found with
      the <afnix/> interpreter.
      </p>

      <example>
      zsh&gt; axs -h
      usage: axs [options] [file] [arguments]
                 [-h]             print this help message
                 [-v]             print version information
                 [-i] path        add a path to the resolver
                 [-f  assert]     enable assertion checking
      </example>
    </subsect>
  </section>

  <!-- folio operation -->
  <section>
    <title>Folio operations</title>

    <p>
    The process of importing data requires first to create a
    <em>folio</em> which will act as a collection of sheets. When
    starting from the beginning, the best way is to create a new
    folio and then create, one or several sheets in which data can be
    added or imported.
    </p>

    <!-- creating a folio -->
    <subsect>
      <title>Creating a folio</title>

      <p>
      The process of importing data requires first to create a
      folio. When starting from the beginning, the best way is to
      create a new folio with the <code>axs:new</code> command, then
      create one or several sheets with the <code>axs:create</code>
      command and finally import data with the <code>axs:import</code>
      command.
      </p>

      <example>
      (axs) axs:new "elements"
      </example>

      <p>
      The <code>axs:new</code> command creates a new folio those
      name is given by the argument. Without argument, the command
      creates an unnamed folio. The command also returns the
      <code>Folio</code> object that can be later used for special
      operations.
      </p>
    </subsect>

    <!-- saving a folio -->
    <subsect>
      <title>Saving a folio</title>

      <p>
      The <code>axs:save</code> command writes a binary representation
      of the folio in a file. The folio is serialized with the help of
      the <afnix/> serialize engine. The serialization is done in a
      file that can be reloaded with the <code>axs:open</code>
      command.
      </p>

      <example>
      (axs) axs:save "elements.xss"
      (axs) axs:open "elements.xss"
      </example>
    </subsect>

    <!-- creating a default sheet -->
    <subsect>
      <title>Creating a default sheet</title>

      <p>
      In order to import data, a sheet must be created in the folio.
      The <code>axs:create</code> command creates a sheet
      in the folio. The command take an optional argument which is the
      sheet name. The command also returns the <code>Sheet</code>
      object that can be used for other special processing.
      </p>

      <example>
      (axs) axs:create "data"
      </example>

      <p>
      A new sheet named <tt>data</tt> is created and becoming the
      default one. Once the sheet is created, the data can be added
      into it with the help of the <code>axs:import</code> command.
      There is always a default sheet attached to a folio. The default
      sheet is set by creating a new sheet or by using the
      <code>axs:select</code> command.
      </p>
    </subsect>

    <!-- importing data into the sheet -->
    <subsect>
      <title>Importing data in the sheet</title>

      <p>
      The <em>periodic table of the elements</em> is a simple example
      that illustrates the importation process. The original file is
      located into the <path>exp/elem</path> directory. The
      <file>elements.tbl</file> file is a simple file that associates
      the <em>atomic number</em> with an element name, it chemical
      symbol and other parameters. An extract of the file is shown
      below.
      </p>

      <example>
      # ------------------------------------------------------------
      # - elements.tbl                                             -
      # - the periodic sheet of elements                           -
      # ------------------------------------------------------------
      # - element name   sym   weight  bp (c)  mp (c)  density     -
      # ------------------------------------------------------------

      1   "Hydrogen"     "H"   1.00797 -252.7  -259.2  0.071
      2   "Helium"       "He"  4.0026  -268.9  -269.7  0.126
      3   "Lithium"      "Li"  6.939    1330    180.5  0.53
      4   "Beryllium"    "Be"  9.0122   2770    1277   1.85
      5   "Boron"        "B"   10.811   nil     2030   2.34
      </example>

      <p>
      There are 112 rows in this sheet. Not all rows have data. A
      particular cell, with no data is marked with the special symbol
      <code>nil</code>. Strings are enclosed with double
      quotes. Integer and reals numbers differentiate themselves
      automatically. A line with no data is ignored. A comment starts
      with the <code>#</code> character.
      </p>

      <example>
      (axs) axs:new    "elements"
      (axs) axs:create "data"
      (axs) axs:import "elements.tbl"
      (axs) axs:save   "elements.xss"
      </example>

      <p>
      After the <code>axs:import</code> command, the <code>axs:save</code>
      command writes the folio in a file called
      <file>elements.xss</file>. Such file can be later used with the
      <code>axs:open</code> command.
      </p>
    </subsect>

    <!-- folio reloading -->
    <subsect>
      <title>Folio reloading</title> 

      <p>
      Given a folio, the <code>axs:open</code> command reload the
      folio in memory and permit the sheet manipulation. When a folio
      is loaded, the default sheet can be selected. Using the previous
      example, and assuming a new session is started:
      </p>

      <example>
      # reload the folio
      (axs) axs:open "elements.xss"
      </example>
      
      <p>
      When the folio is loaded, the first sheet is set as the default
      sheet.
      </p>
    </subsect>
    
    <!-- folio information -->
    <subsect>
      <title>Folio information</title>

      <p>
      When the folio is loaded, the <code>axs:info</code> command reports
      some information about the folio.
      </p>

      <example>
      (axs)axs:info
      Object             Value
      Folio name         elements
      Current sheet      data
      </example>

      <p>
      In the previous example, the folio name is reported as well as
      the default sheet.
      </p>
    </subsect>
  </section>

  <!-- sheet operations -->
  <section>
    <title>Sheet operations</title>

    <p>
    Sheets can be manipulated once loaded into a folio. There is
    always a <em>default sheet</em> on which most of the operation
    apply. In certain cases, the operations can also be done with the
    help of the sheet index.
    </p>

    <!-- sheet information -->
    <subsect>
      <title>Sheet information</title>

      <p>
      The <code>axs:list</code> command displays the folio
      content with the sheet index, sheet name and sheet length. This
      command permits to check, among other things, that an
      importation process operated correctly.
      </p>

      <example>
      (axs)axs:list
      Sheet index Sheet name Sheet length
      0           data       112
      </example>

      <p>
      The command reports for each sheet, its name and size. The size
      is the number of records which is the number of rows. After a
      <code>axs:create</code> command, the <code>axs:list</code>
      command will report a sheet without element.
      </p>
    </subsect>

    <!-- viewing the sheet contents -->
    <subsect>
      <title>Viewing the sheet contents</title>

      <p>
      The best way to visualize the sheet content is to use the
      <code>axs:view</code> command. The command operates with
      the default sheet. Without argument, the whole sheet is
      shown. With one argument, an integer number that specifies the
      report length and eventually a secondary number that specifies
      the starting index.
      </p>

      <example>
      (axs)axs:view 5 10
      11 Sodium     Na 22.989800 892  97.800000 .97
      12 Magnesium  Mg 24.312000 1107 650       1.740000
      13 Aluminum   Al 26.981500 2450 660       2.700000
      14 Silicon    Si 28.086000 2680 1410      2.330000
      15 Phosphorus P  30.984000 nil  nil       nil
      </example>
    </subsect>

    <!-- sorting a sheet -->
    <subsect>
      <title>Sorting a sheet</title>

      <p>
      The <code>axs:sort</code> command sorts the default sheet. The
      sheet column as well as well as the sorting mode are the sorting
      parameters. Without argument the first column and the ascending
      mode are used to sort the sheet. For example, a sorting on the
      second column in ascending order, produces the following result:
      </p>

      <example>
      (axs)axs:sort 1
      (axs)axs:view 5
      95 Americium Am 243.060000 nil         nil         nil
      13 Aluminum  Al 26.981500  2450        660         2.700000
      18 Argon     Ar 39.948000  -185.800000 -189.400000 1.400000
      33 Arsenic   As 74.992000  613         817         5.720000
      51 Antimony  Sb 121.750000 1380        630.500000  6.620000
      </example>

      <p>
      On the other end, sorting in descending order produces the
      following result:
      </p>
      
      <example>
      (axs)axs:sort 1
      (axs)axs:view 5
      40 Zirconium Zr 91.220000  3580 1852        6.490000
      30 Zinc      Zn 65.370000  906  419.500000  7.140000
      70 Ytterbium Yb 173.040000 1427 824         6.980000
      39 Yttrium   Y  88.905900  nil  nil         nil
      54 Xenon     Xe 131.300000 -108 -111.900000 3.060000
      </example>
    </subsect>
  </section>
</chapter>
