<?xml version='1.0'?>

<!-- ====================================================================== -->
<!-- = appendix-i.xml                                                     = -->
<!-- = afnix cross spreadsheet - appendix i                               = -->
<!-- ====================================================================== -->
<!-- = 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                            = -->
<!-- ====================================================================== -->

<appendix client="axs" number="i">
  <title>Cross spreadsheet reference</title>
  
  <p>
  This appendix is a reference of the <afnix/> cross spreadsheet or
  <product>axs</product>. The <afnix/> cross spreadsheet is started with
  the <command>axs</command> command. All control commands are bound
  to the <code>axs</code> nameset.
  </p>

  <!-- =================================================================== -->
  <!-- = create control                                                  = -->
  <!-- =================================================================== -->

  <control nameset="axs">
    <name>create</name>

    <p>
    The <code>axs:create</code> command create a new sheet in the
    folio. In order to succeed, a folio object must exist prior
    creating a sheet. Without argument, a default sheet is created
    without name. The optional argument is the sheet name
    </p>

    <syntax>
    axs:create
    axs:create <em>name</em>
    </syntax>

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

    <p>
    This example create a sheet with the name <tt>data</tt>. Once the
    sheet has been created, it becomes the default sheet.
    </p>
  </control>

  <!-- =================================================================== -->
  <!-- = export control                                                  = -->
  <!-- =================================================================== -->

  <control nameset="axs">
    <name>export</name>

    <p>
    The <code>axs:export</code> command exports the contents of the
    default sheet to the specified file. When exported, the sheet is
    formatted in such way that it can be read again with the import
    command.
    </p>

    <syntax>
    axs:export <em>file</em>
    </syntax>

    <example>
    (axs) axs:export "elements.txt"
    </example>
  </control>

  <!-- =================================================================== -->
  <!-- = import control                                                  = -->
  <!-- =================================================================== -->

  <control nameset="axs">
    <name>import</name>

    <p>
    The <code>axs:import</code> command imports data into the current
    sheet. The data must be formatted in such way that they are
    readable by the <afnix/> reader. In particular, the string must be
    placed between double quotes and the character between single
    quotes. Blank and tabulation characters are used as separators.
    </p>

    <syntax>
    axs:import <em>file</em>
    </syntax>

    <example>
    (axs) axs:import "elements.tbl"
    </example>
  </control>

  <!-- =================================================================== -->
  <!-- = info control                                                    = -->
  <!-- =================================================================== -->

  <control nameset="axs">
    <name>info</name>

    <p>
    The <code>axs:info</code> command prints some information about
    the folio. Among the information is the folio name and the current
    sheet. An optional output stream argument can be used to write the
    sheet information. 
    </p>

    <syntax>
    axs:info
    axs:info <em>file</em>
    </syntax>

    <example>
    (axs) axs:info
    </example>
  </control>

  <!-- =================================================================== -->
  <!-- = insert control                                                  = -->
  <!-- =================================================================== -->

  <control nameset="axs">
    <name>insert</name>

    <p>
    The <code>axs:insert</code> command insert data into the current
    sheet. The data are seen as a vector of literals. When the command
    is executed, a record is automatically created, filled with the
    data and inserted into the sheet.
    </p>

    <syntax>
    axs:insert <em>data+</em>
    </syntax>

    <example>
    (axs) axs:insert "hello" "world" 2000
    </example>

    <p>
    In this example, a record of 3 elements is created with 2 strings
    and one integer.
    </p>
  </control>

  <!-- =================================================================== -->
  <!-- =  insert-marker                                                  = -->
  <!-- =================================================================== -->

  <control nameset="axs">
    <name>insert-info</name>

    <p>
    The <code>axs:insert-marker</code> command insert marker data into
    the current sheet. The data are seen as a vector of literals. When
    the command is executed, the marker record is filled
    with the data. This command is similar to the
    <code>axs:insert</code>. The marker record is primarily used to
    mark the sheet columns.
    </p>

    <syntax>
    axs:insert-marker <em>data+</em>
    </syntax>

    <example>
    (axs) axs:insert-marker "hello" "world" 2000
    </example>

    <p>
    In this example, the 2 strings and one integer are added into the
    sheet marker record.
    </p>
  </control>

  <!-- =================================================================== -->
  <!-- =  insert-header                                                  = -->
  <!-- =================================================================== -->

  <control nameset="axs">
    <name>insert-header</name>

    <p>
    The <code>axs:insert-header</code> command insert header data into
    the current sheet. The data are seen as a vector of literals. When
    the command is executed, the header record is filled with the data.
    This command is similar to the <code>axs:insert</code>
    </p>

    <syntax>
    axs:add-info <em>data+</em>
    </syntax>

    <example>
    (axs) axs:add-info "hello" "world" 2000
    </example>

    <p>
    In this example, the 2 strings and one integer are added into the
    sheet informatino record.
    </p>
  </control>

  <!-- =================================================================== -->
  <!-- =  insert-footer                                                  = -->
  <!-- =================================================================== -->

  <control nameset="axs">
    <name>insert-footer</name>

    <p>
    The <code>axs:insert-footer</code> command insert footer data into
    the current sheet. The data are seen as a vector of literals. When
    the command is executed, the footer record is filled with the data.
    This command is similar to the <code>axs:insert</code>
    </p>

    <syntax>
    axs:add-info <em>data+</em>
    </syntax>

    <example>
    (axs) axs:add-info "hello" "world" 2000
    </example>

    <p>
    In this example, the 2 strings and one integer are added into the
    sheet informatino record.
    </p>
  </control>

  <!-- =================================================================== -->
  <!-- = new control                                                     = -->
  <!-- =================================================================== -->

  <control nameset="axs">
    <name>new</name>

    <p>
    The <code>axs:new</code> command create a new folio. Without
    argument an empty folio is created. With one string argument, a
    new folio is created with the argument name. with two arguments, a
    new folio is created by name and info. If a folio already
    exists, it is closed prior the creation of the new one.
    </p>

    <syntax>
    axs:new
    axs:new <em>name</em>
    </syntax>

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

  <!-- =================================================================== -->
  <!-- = open control                                                    = -->
  <!-- =================================================================== -->

  <control nameset="axs">
    <name>open</name>

    <p>
    The <code>axs:open</code> command open a new folio those name is
    the file name given as the argument. The file name must
    corresponds to a serialized folio that was generated with the
    <code>axs:save</code> command.
    </p>

    <syntax>
    axs:open <em>file</em>
    </syntax>

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

  <!-- =================================================================== -->
  <!-- = save control                                                    = -->
  <!-- =================================================================== -->

  <control nameset="axs">
    <name>save</name>

    <p>
    The <code>axs:save</code> command saves the current folio into a
    file those name is given as the argument. The
    <code>axs:save</code> command operates by serializing the folio.
    </p>

    <syntax>
    axs:save <em>file</em>
    </syntax>

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

  <!-- =================================================================== -->
  <!-- = select control                                                  = -->
  <!-- =================================================================== -->

  <control nameset="axs">
    <name>select</name>

    <p>
    The <code>axs:select</code> command selects a sheet by
    index. Since there is no guarantee that the sheet name is unique,
    an index is more appropriate to guarantee a unique selection. Once
    selected, the sheet becomes the default one.
    </p>

    <syntax>
    axs:select <em>index</em>
    </syntax>

    <example>
    (axs) axs:select 1
    </example>
  </control>

  <!-- =================================================================== -->
  <!-- = list control                                                    = -->
  <!-- =================================================================== -->

  <control nameset="axs">
    <name>list</name>

    <p>
    The <code>axs:list</code> command reports the folio
    contents. For each sheet, the index, the sheet name and size is
    reported. With an argument, the reported information is written to an
    output stream. By default, the standard output is used for reporting.
    </p>

    <syntax>
    axs:list
    axs:list <em>file</em>
    </syntax>

    <example>
    (axs) axs:list
    </example>
  </control>

  <!-- =================================================================== -->
  <!-- = view control                                                    = -->
  <!-- =================================================================== -->

  <control nameset="axs">
    <name>view</name>

    <p>
    The <code>axs:view</code> command display the sheet
    contents by using the cell literal representation. Without
    argument, the entire tale is reported. With one integer argument
    as the report size, only the specified number of elements is
    reported. A second integer argument that acts as a starting index
    can also be used.
    </p>

    <syntax>
    axs:view
    axs:view <em>length</em>
    axs:view <em>length start</em>
    </syntax>

    <example>
    (axs) axs:view
    </example>
  </control>
</appendix>
