<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY okteta "<application>Okteta</application>">
  <!ENTITY kappname "&okteta;" >
  <!ENTITY package "kdesdk">
  <!ENTITY Friedrich.Kossebau
"<personname><firstname>Friedrich</firstname><othername>W. H.</othername><surname>Kossebau</surname></personname>">
  <!ENTITY Friedrich.Kossebau.email "<email>kossebau@kde.org</email>">
  <!ENTITY Alex.Richardson
"<personname><firstname>Alex</firstname><surname>Richardson</surname></personname>">
  <!ENTITY Alex.Richardson.email "<email>alex.richardson@gmx.de</email>">
  <!ENTITY % English "INCLUDE">
  <!ENTITY % addindex "IGNORE">
]>

<book id="okteta" lang="&language;">

<bookinfo>
<title>The &okteta; Handbook</title>

<authorgroup>
    <author>
      <firstname>Friedrich</firstname><othername>W. H.</othername><surname>Kossebau</surname>
      <affiliation>
        <address>&Friedrich.Kossebau.email;</address>
      </affiliation>
    </author>
    <author>
      <firstname>Alex</firstname><surname>Richardson</surname>
      <affiliation>
        <address>&Alex.Richardson.email;</address>
      </affiliation>
    </author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>

<copyright>
<year>2008, 2010, 2011</year>
<holder>&Friedrich.Kossebau; and &Alex.Richardson;</holder>
</copyright>
<!--FIXME http://frinring.files.wordpress.com/2012/08/okteta-0-9-new-features.png-->
<legalnotice>&FDLNotice;</legalnotice>

<date>2012-08-20</date>
<releaseinfo>0.9.70 (&kde; 4.9)</releaseinfo>

<abstract>
  <para>&okteta; is a simple editor for the raw data of files. This type of program
  is also called hex editor or binary editor.</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>&package;</keyword>
<keyword>Okteta</keyword>
<keyword>view</keyword>
<keyword>edit</keyword>
<keyword>bits</keyword>
<keyword>bytes</keyword>
<keyword>binary</keyword>
<keyword>octal</keyword>
<keyword>hexadecimal</keyword>
<keyword>hex editor</keyword>
<keyword>raw data</keyword>
</keywordset>
</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<para>&okteta; is a simple editor for the raw data of files.</para>

<para>The data is displayed in two variants: as the numeric values of the bytes
and as the character assigned to the values. Values and characters can be shown
either in two columns (the traditional display in hex editors) or in rows with
the value on top of the character. Editing can be done both for the values and
for the characters.</para>

<para>Besides the usual editing capabilities &okteta; also brings a small set of
tools, like a table listing decodings into common simple data types, a table
listing all possible bytes with its' character and value equivalents, an info
view with a statistic, a checksum calculator, a filter tool and a string
extraction tool.</para>

<para>All modifications to the data loaded can be endlessly undone or redone.</para>

</chapter>

<chapter id="basics">
<title>Basics</title>

<sect1 id="starting-basics">
<title>Starting &okteta;</title>

    <para>Type <userinput><command>okteta</command></userinput> at a command
    prompt or select <guimenuitem>Hex Editor</guimenuitem> from the
    <menuchoice><guisubmenu>Applications</guisubmenu><guisubmenu>Utilities</guisubmenu>
    </menuchoice> group in the application launcher.</para>

    <para>The standard &Qt; and &kde; command line
    options are available, and can be listed by entering
    <userinput><command>okteta</command> <option>--help</option></userinput>.</para>

    <para>Command line options specific to &okteta; are:</para>

    <para><option><replaceable>&lt;&URL;(s)&gt;</replaceable></option> - open
    file(s) from the specified &URL;(s)</para>

<!--<para><option>- -offset</option>
<replaceable>&lt;offset&gt;</replaceable> jump to position
<replaceable>&lt;offset&gt;</replaceable> in the opened file.</para>-->
</sect1>

<sect1 id="usage-basics">
<title>Usage</title>

    <para>The main &okteta; window has the following components:
    a menu bar, a toolbar, a status bar, one or several sidebars with tools, and
    the main view with the tabbed data views.</para>

    <para>When a file is opened or a new byte array is created, the bytes
    contained are listed consecutively in lines with a given number of bytes
    per line. They are displayed in two variants: as the numeric values of the
    bytes and as the characters assigned to the values. Values and characters
    can be shown either separated in two columns or next to each other with the
    value on top of the character. On the left side the offsets of the first
    byte in each line are shown.</para>

    <para>The handling is similar to that of most text editors:
    the data can be edited, cut, copied, pasted, dragged and dropped much as
    text in these can. A cursor marks the current position. Pressing the
    <keycap>Insert</keycap> key toggles between the overwrite and insert modes.
    The overwrite mode is stricter than in text editors, as it doesn't allow any
    operation which changes the size of the byte array.</para>

    <para>Other than in text editors the content is displayed in two variants.
    Only one of these is active with regard to new input. There are two linked
    cursors shown for the value and the character display, the cursor of
    the active one is blinking. With the characters active, characters can be
    entered as known from text editors. With the values active, typing a digit
    will open a minimal editor to enter the rest of the value.</para>

    <para>The search dialog allows the user to search for a specific string of
    bytes, definable as values (hexadecimal, decimal, octal, binary) or text
    (current 8-bit encoding or UTF-8).</para>

    <para>Multiple byte arrays can be open at the same time, but only one can be
    active. Use the <guimenu>Windows</guimenu> menu to select which byte array will
    be active.</para>
</sect1>


</chapter>

<chapter id="tools">
  <title>Tools</title>

<!-- The tool Versions is not part of released versions,
just used for development, so no need to document it. -->

<sect1 id="tools-overview">

  <title>Overview</title>
  <para>&okteta; brings some tools, some to analyze and manipulate the byte arrays
  and some with more general purpose. These tools can be activated or deactivated from
  the <guimenu>Tools</guimenu> entry in the menu bar. Each tool has a small view,
  which docks either in one of the sidebars or freely floats as a window. You
  can dock, undock, rearrange and also stack the tool views with the mouse, by
  pressing the &LMB; on the title bar of a tool view, moving it as you like and
  releasing the &LMB; to complete the action, otherwise cancel it by pressing
  the &Esc; key.</para>

<sect2>
  <title>Analyzers and Manipulators</title>
<variablelist>
  <varlistentry>
    <!--FIXME not in 4.9?-->
    <term>Byte Table</term>
    <listitem><para>The table lists all possible byte values, both as character and
    numerical value.</para>
    <para>The selected value can be inserted at the cursor position for a
    defined number of bytes. This can be achieved by using the <guibutton>Insert</guibutton>
    button or double-clicking the line in the table.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term>Binary Filter</term>
    <listitem><para>The filter performs binary operations on the selected bytes.
    After choosing the operation (AND, OR, ROTATE..) the parameters,
    if any, can be set in the box below. The filter is executed on the use
    of the <guibutton>Filter</guibutton> button.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term>Strings</term>
    <listitem><para>This tool locates the strings in the selected bytes.
    After choosing the minimum string length, the strings are grepped for
    on the use of the <guibutton>Extract</guibutton> button.
    The list of the strings displayed can be narrowed by entering a
    filter term.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term>Statistics</term>
    <listitem><para>This tool builds a statistic for the selected bytes.
    The statistic gives the frequency of the occurrence of each byte value
    in the selection.
    It can be calculated by using the <guibutton>Build</guibutton>
    button.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term>Checksum</term>
    <listitem><para>This tool calculates various checksums or hashsums for the
    selected bytes. After choosing the algorithm and setting the parameter, if
    any, the sum is computed on the use of the <guibutton>Calculate</guibutton>
    button.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term>Decoding Table</term>
    <listitem><para>The table displays the values of the byte or the bytes
    starting at the cursor for some common simple data types like Integer or
    Float, but also UTF-8. Double-clicking on a line in the table opens an
    editor, so the value can be edited and changed.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term>Structures</term>
    <listitem><para>This tool enables investigating and editing of byte arrays
    based on user-creatable structure definitions. Detailed instructions are in
    an own <link linkend="tools-structures">section</link>.</para></listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2>
  <title>General tools</title>
<variablelist>
  <varlistentry>
    <term>Filesystem</term>
    <listitem><para>This tool offers an embedded file browser which
    can be used to select files to open.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term>Documents</term>
    <listitem><para>This tool shows all currently created or loaded files.
    Symbols mark the file with the currently active view and also show which
    files have unsaved changes or which storage copy has been modified by
    another program.</para></listitem>
  </varlistentry>

  <varlistentry>
    <term>Bookmarks</term>
    <listitem><para>This tool can be used to manage the bookmarks, alternatively
    to the <link linkend="bookmarks-menu"><guimenu>Bookmarks</guimenu></link> menu.
    <note><para>Bookmarks are currently only transient and not saved if you
    close a byte array or the whole program.</para></note></para></listitem>
  </varlistentry>

  <varlistentry>
    <term>File Info</term>
    <listitem><para>This tool displays some information about the current file,
    including its type, the location of storage and the size.</para></listitem>
  </varlistentry>
</variablelist>
</sect2>
<!--FIXME Terminal + Charset Conversion missing
http://frinring.wordpress.com/2011/07/31/all-new-okteta-features-for-kde-apps-4-7-in-a-picture/
-->
</sect1>


<sect1 id="tools-structures">

    <title>Structures Tool</title>

    <sect2>
      <title>General</title>

      <para>The Structures tool enables analyzing and editing of byte arrays
      based on user-creatable structure definitions, which can be built from
      arrays, unions, primitive types and enum values.</para>
     <!-- explain/link what these types are? probably not, since most user will be programmers? -->
      <para>It has an own settings dialog, which can be reached by using the
      <guibutton>Settings</guibutton> button. There are various options that can be
      configured, like the style (decimal, hexadecimal or binary) in which the
      values are displayed. Moreover it is possible to choose which structure
      definitions get loaded and which structures are shown in the view.</para>
      <para>Structures are defined in &okteta; Structure Definition files (based
      on &XML;, with the file extension <literal role="extension">.osd</literal>).
      Additionally a <literal role="extension">.desktop</literal> file contains
      metadata about that structure description file, such as author, homepage
      and license.</para>
      <para>Currently there is no built-in support for creating or editing
      structure definitions, therefore this must be done manually as
      described in the next sections.</para>
    </sect2>

    <sect2>
      <title>Installing structure definitions</title>

      <sect3>
        <title>Installing using KNewStuff</title>
        <para>The easiest way of installing new structure definitions is by using the built-in
        KNewStuff support in &okteta;. To install an existing structure open the settings dialog of the
        Structures tool. There select the <guilabel>Structures Management</guilabel> tab and press the
        <guibutton>Get New Structures...</guibutton> button. The dialog that shows up now allows you to
        install and uninstall structures.</para>
      </sect3>
      <sect3>
        <title>Installing structure definitions manually</title>
        <para>The Structures tool looks for structure descriptions in the
          subdirectory <filename class="directory">share/apps/okteta/structures/</filename>
          of the user's directory for program data (find that by executing
          <userinput><command>kde4-config</command> <option>--localprefix</option></userinput>).
          You may need to create this directory if there are no structure
          definitions installed yet.</para>
          <para>Two files exist for every structure definition: One file for the actual definition and a
          <literal role="extension">.desktop</literal> file for the metadata (author, version, etc.).</para>
          <para>In that directory there is a subdirectory for each structure
          definition, which contains both the <literal role="extension">.desktop</literal>
          file and the <literal role="extension">.osd</literal> or
          <filename>main.js</filename> file of that definition.</para>
          <para>For example, with the program data directory <filename class="directory">.kde</filename>
          and a structure definition named ExampleStructure there is the directory
          <filename class="directory">.kde/share/apps/okteta/structures/ExampleStructure</filename>,
          which contains a file <filename>ExampleStructure.desktop</filename> and a
          file <filename>ExampleStructure.osd</filename>.</para>
      </sect3>
      <sect3>
        <title>Using the newly installed structures</title>
        <para>After having installed a new structure definition you need to restart &okteta;
        before you can use it.
        Once &okteta; has started, open the settings dialog of the Structures tool. There select the
        <guilabel>Structures Management</guilabel> tab and make sure the relevant
        structure definition is checked. Then switch to the <guilabel>Structures</guilabel> tab and
        make sure the desired element is listed on the right-hand side.</para>
      </sect3>
    </sect2>

    <sect2>
      <title>Sharing structure definitions</title>
      <para>For common structures you may not need to create a definition yourself,
      but instead can reuse an already existing definition from places like
      <ulink url="http://kde-files.org/index.php?xcontentmode=691">kde-files.org</ulink>.</para>
      <para>You also may want to share a definition yourself. To do so, create a
      file archive (&eg; a zipped tar archive, <literal role="extension">.tar.gz</literal>)
      containing just the subdirectory with the <literal role="extension">.desktop</literal>
      file and the structure definition file. Looking at the example in the last section this
      would be the directory <filename class="directory">ExampleStructure</filename> with all its contents.
      Using this format for sharing the structure definitions allows installing them inside &okteta; and
      requires no manual installation.</para>
    </sect2>


    <sect2>
      <title>Creating structure definitions</title>
      <para>There are two different ways of creating structure definitions. The first is writing the
      definition in &XML; the other is using JavaScript<!-- Markup??-->. The JavaScript approach allows you
      to create more complex structures with features like e.g. validating the structure. Using &XML; gives you
      less features but if a static structure is all you need this may be the easiest approach. If you need a dynamic
      structure i.e. where array lengths depend on other values in the structure or the structure layout is different when
      some member value changes, then you will have to write the structure definition in JavaScript.
      There is one exception to that rule: if you have an array where the length is supposed to be
      <emphasis role="bold">exactly</emphasis> the same as another value in the structure, then you can use &XML;.
      But if it is something like <emphasis>length - 1</emphasis> it has to be JavaScript.</para>
    </sect2>


    <sect2>
      <title>Structure definition &XML; file format</title>
      <para>
      <!-- TODO xml schema -->
      The <literal role="extension">.osd</literal> &XML; file has one root element: <emphasis>&lt;data&gt;</emphasis> with no
      attributes. Inside this element there must be one of the following elements:</para>
      <!-- TODO markup, though better than nothing this way-->
      <variablelist>
          <varlistentry>
            <term><emphasis role="bold"><emphasis>&lt;primitive&gt;</emphasis></emphasis></term>
            <listitem><para>To create a primitive data types like e.g. <emphasis>int</emphasis> and
              <emphasis>float</emphasis>. This element accepts no subelements and can have the following attributes:</para>
              <variablelist>
                <varlistentry>
                <term><emphasis role="bold">type</emphasis></term>
                <listitem>
                  <para>The type of this primitive type. It must be one of the following:</para>
                  <itemizedlist>
                    <listitem><para><emphasis>char</emphasis> for a 8 bit ASCII character</para></listitem>
                    <listitem><para><emphasis>int8, int16, int32, int64</emphasis> for a signed integer of that size</para></listitem>
                    <listitem><para><emphasis>uint8, uint16, uint32, uint64</emphasis> for an unsigned integer of that size</para></listitem>
                    <listitem><para><emphasis>bool8, bool16, bool32, bool64</emphasis> for an unsigned boolean (0 = false, any other value = true) of that size</para></listitem>
                    <listitem><para><emphasis>float</emphasis> for a 32 bit IEEE754 floating point number</para></listitem>
                    <listitem><para><emphasis>double</emphasis> for a 64 bit IEEE754 floating point number</para></listitem>
                  </itemizedlist>
                </listitem>
                </varlistentry>
              </variablelist>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold"><emphasis>&lt;bitfield&gt;</emphasis></emphasis></term>
            <listitem><para>To create a bitfield. This element accepts no subelements and can have the following
              attributes:</para>
              <variablelist>
                <varlistentry>
                  <term><emphasis role="bold">width</emphasis></term>
                  <listitem><para>The number of bits used by this bitfield. Must be between 1 and 64.</para></listitem>
                </varlistentry>
                <varlistentry>
                  <term><emphasis role="bold">type</emphasis></term>
                  <listitem>
                    <para>The type of this bitfield. It must be one of the following:</para>
                    <itemizedlist>
                      <listitem><para><emphasis>unsigned</emphasis> for a bitfield where the value will be interpreted as
                      an unsigned value (value range from 0 to 2<superscript>width</superscript> - 1)</para></listitem>
                      <listitem><para><emphasis>signed</emphasis> for a bitfield where the value will be interpreted as a
                      signed value (value range from -2<superscript>width - 1</superscript> to
                      2<superscript>width - 1</superscript> - 1)</para></listitem>
                      <listitem><para><emphasis>bool</emphasis> for a bitfield where the value will be interpreted as a
                      boolean value</para></listitem>
                  </itemizedlist>
                  <note><para>Always remember to add padding after a <emphasis>&lt;bitfield&gt;</emphasis>, since otherwise
                  the next element (except for strings and arrays, since they add padding automatically) will start in the
                  middle of a byte. Obviously padding is not necessary if you want this behavior.</para></note>
                  </listitem>
                </varlistentry>
              </variablelist>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold"><emphasis>&lt;enum&gt;</emphasis></emphasis></term>
            <listitem><para>To create a primitive type, but where the values are displayed as members of an enumeration if
              possible. This element accepts no subelements (however you will need an <emphasis>&lt;enumDef&gt;</emphasis>
              tag in the file to reference it). It has the following attributes:</para>
              <variablelist>
                <varlistentry>
                  <term><emphasis role="bold">enum</emphasis></term>
                  <listitem><para>The underlying enum for this value. Must match the <emphasis>name</emphasis> attribute of
                  one of the <emphasis>&lt;enumDef&gt;</emphasis> tags in this file.</para></listitem>
                </varlistentry>
                <varlistentry>
                  <term><emphasis role="bold">type</emphasis></term>
                  <listitem>
                    <para>The type of this enum. See type attribute of <emphasis>&lt;primitive&gt;</emphasis>.
                    Only difference is that <emphasis>Double</emphasis> and <emphasis>Float</emphasis> make no sense.</para>
                  </listitem>
                </varlistentry>
              </variablelist>
            </listitem>
          </varlistentry>


          <varlistentry>
            <term><emphasis role="bold"><emphasis>&lt;flags&gt;</emphasis></emphasis></term>
            <listitem><para>This is the same as <emphasis>&lt;enum&gt;</emphasis> with the only difference being
            that values are represented as a <emphasis>bitwise-or</emphasis> of all the values of the enumeration.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold"><emphasis>&lt;struct&gt;</emphasis></emphasis></term>
            <listitem><para>To create a structure. All other elements (including <emphasis>&lt;struct&gt;</emphasis>) can
            be a child of this and will then be part of the resulting structure</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold"><emphasis>&lt;union&gt;</emphasis></emphasis></term>
            <listitem><para>To create a union. Basically the same as <emphasis>&lt;struct&gt;</emphasis> except for the fact
            that all child elements will start from the same offset. Useful for interpreting the same sequence of bytes in
            various ways.</para></listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold"><emphasis>&lt;array&gt;</emphasis></emphasis></term>
            <listitem><para>To create an array. This element accepts exactly one child (the underlying type of the array),
            which can be any of the elements, even <emphasis>&lt;array&gt;</emphasis> itself. It also has the following
            attributes:</para>
              <variablelist>
                <varlistentry>
                  <term><emphasis role="bold">length</emphasis></term>
                  <listitem><para>The number of elements in this array as a decimal number.
                  Alternatively it can also be a string which matches the name attribute of a previously defined
                  <emphasis>&lt;primitive&gt;</emphasis>, <emphasis>&lt;enum&gt;</emphasis> or <emphasis>&lt;flags&gt;</emphasis>
                  element. Then the length will be the value of that element.
                  Currently it is limited to 10000, because larger arrays would use too much memory and slow down the tool
                  too much.
                  </para></listitem>
                </varlistentry>
              </variablelist>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold"><emphasis>&lt;string&gt;</emphasis></emphasis></term>
            <listitem><para>To create a string in various encodings. By default you get a <emphasis>NULL</emphasis>-
            terminated C-style string. However different types of string can be created with the following attributes:</para>
              <variablelist>
                <varlistentry>
                  <term><emphasis role="bold">terminatedBy</emphasis></term>
                  <listitem><para>This attribute determines what unicode codepoint the string is terminated by. It must be a
                  hexadecimal number (optionally with leading <emphasis>0x</emphasis>). When encoding is ASCII, only values
                  up to 0x7f are meaningful. If neither this nor <emphasis>maxCharCount</emphasis> nor <emphasis>maxByteCount</emphasis>
                  are set, this is assumed to be set to 0 (C-style string)
                  </para></listitem>
                </varlistentry>
                <varlistentry>
                  <term><emphasis role="bold">maxCharCount</emphasis></term>
                  <listitem><para>The maximum number of chars this string can have. If <emphasis>terminatedBy</emphasis> is
                  set too then whatever is reached first terminates the string. This is mutually exclusive with
                  <emphasis>maxByteCount</emphasis></para></listitem>
                </varlistentry>
                <varlistentry>
                  <term><emphasis role="bold">maxByteCount</emphasis></term>
                  <listitem><para>The maximum number of bytes this string can be long. If <emphasis>terminatedBy</emphasis>
                  is set too then whatever is reached first terminates the string. This is mutually exclusive with
                  <emphasis>maxCharCount</emphasis>. With encodings like <emphasis>ASCII</emphasis> this is the same as
                  <emphasis>maxCharCount</emphasis>.</para></listitem>
                </varlistentry>
                <varlistentry>
                  <term><emphasis role="bold">type</emphasis></term>
                  <listitem><para>The encoding of this string. Can be one of the following:</para>
                    <itemizedlist>
                      <listitem><para><emphasis>ASCII</emphasis></para></listitem>
                      <listitem><para><emphasis>LATIN-1</emphasis></para></listitem>
                      <listitem><para><emphasis>UTF-8</emphasis></para></listitem>
                      <listitem><para><emphasis>UTF-16-LE</emphasis> or <emphasis>UTF-16-BE</emphasis>. If neither
                      <emphasis>-LE</emphasis> or <emphasis>-BE</emphasis> suffix is given, little endian is assumed.
                      </para></listitem>
                      <listitem><para><emphasis>UTF-32-LE</emphasis> or <emphasis>UTF-32-BE</emphasis>. If neither
                      <emphasis>-LE</emphasis> or <emphasis>-BE</emphasis> suffix is given, little endian is assumed.
                      </para></listitem>
                    </itemizedlist>
                  </listitem>
                </varlistentry>
              </variablelist>
            </listitem>
          </varlistentry>
      </variablelist>
      <para>
      Every element also accepts an attribute <emphasis>name</emphasis> which is then visible in the structures view.
      </para>
    </sect2>

    <sect2>
      <title>An example structure definition in both &XML; and JavaScript</title>
      <sect3>
        <title>The common step shared by both approaches</title>
        <para>
        Our metadata file looks like this:
        <screen>
        [Desktop Entry]
        Encoding=UTF-8
        Icon=arrow-up<co id="icon" />
        Type=Service
        ServiceTypes=KPluginInfo

        Name=Simple test structure
        Comment=A very simple test structure containing only two items

        X-KDE-PluginInfo-Author=Alex Richardson
        X-KDE-PluginInfo-Email=foo.bar@email.org
        X-KDE-PluginInfo-Name=simplestruct
        X-KDE-PluginInfo-Version=1.0
        X-KDE-PluginInfo-Website=http://www.plugin.org/
        X-KDE-PluginInfo-Category=structure
        X-KDE-PluginInfo-License=LGPL
        X-KDE-PluginInfo-EnabledByDefault=false
        </screen>
        <calloutlist>
          <callout arearefs="icon">
          <para>The icon displayed in &okteta; for this structure can be anything found by executing
          <userinput><command>kdialog</command> <option>--geticon</option></userinput> or a path to an icon</para>
          </callout>
        </calloutlist>

          These fields should all be pretty much self-explanatory, except for
          <literal>X-KDE-PluginInfo-Name</literal>. The value of this field must match the name of the directory containing the file as well as the name of the <literal role="extension">.desktop</literal> file. When creating &XML; structure definitions the name of the <literal role="extension">.osd</literal> file must also match the name. </para>

        <para>In this example we would have a directory named <filename>simplestruct</filename>
        containing the file <filename>simplestruct.desktop</filename>. When defining structures in &XML;
        the directory would also contain a file named <filename>simplestruct.osd</filename>. Using JavaScript we would have a file named <filename>main.js</filename> instead.</para>
      </sect3>
      <sect3>
        <title>A simple &XML; structure definition</title>
        <para>
          To start we create a definition for a very simple test structure
          containing only integral data types (one char, one 32-bit signed integer, and a bitfield).
          This would be expressed in C/C++ as:
          <screen>
          struct simple {
            char aChar;
            int anInt;
            bool bitFlag :1;
            unsigned padding :7;
          };
          </screen>
          The first step is writing the <literal role="extension">.osd</literal> file according to the file format defined
          in the previous section. We will call <filename>simplestruct.osd</filename>:
          <screen><markup>
          &lt;?xml version="1.0" encoding="UTF-8"?&gt;
          &lt;data&gt;
            &lt;struct name="simple"&gt;
              &lt;primitive name="aChar" type="Char"/&gt;
              &lt;primitive name="anInt" type="Int32"/&gt;
              &lt;bitfield name="bitFlag" type="bool" width="1"/&gt;
              &lt;bitfield name="padding" type="unsigned" width="7"/&gt;
            &lt;/struct&gt;
          &lt;/data&gt;
          </markup></screen>
          which is fairly similar to the C/C++ definition.
          </para>
          <para>Now create a directory <filename class="directory">simplestruct</filename>
          inside the structure installation directory (see manually installing structure definitions) <!-- markup TODO-->
          and copy the two files to this directory. Now you can restart &okteta; and use the new structure.</para>
      </sect3>
      <sect3>
        <title>The simple structure in JavaScript</title>
        <para>
        To implement the structure above in JavaScript, create a file named <filename>main.js</filename> instead of <filename>simplestruct.osd</filename>.
        The contents of that file should be:
        <screen>
        function init() {
          var structure = struct({
            aChar : char(),
            anInt : int32(),
            bitFlag : bitfield("bool", 1),
            padding : bitfield("unsigned", 7),
          })
          return structure;
        }
        </screen>
        The structure displayed by &okteta; is always the return value of the <literal>init</literal> function.</para>
        <para>
        The following functions can be called to create a primitive type:
        <itemizedlist>
          <listitem><para>char()</para></listitem>
          <listitem><para>int8(), int16(), int32() or int64()</para></listitem>
          <listitem><para>uint8(), uint16(), uint32() or uint64()</para></listitem>
          <listitem><para>bool8(), bool16(), bool32() or bool64()</para></listitem>
          <listitem><para>float()</para></listitem>
          <listitem><para>double()</para></listitem>
        </itemizedlist>
        The bitfield function takes two parameters, the first being a string consisting of
        <literal>bool</literal>, <literal>signed</literal> or <literal>unsigned</literal>. The second parameter is an integer which sets the width in bits.
        </para>
      </sect3>
      <sect3>
        <title>More complex structures</title>
        <para>
        Next we create a definition of a more complex structure which we will
        call "complex" and save in a file named <filename>complex.osd</filename>.
        This structure will contain two arrays (one with fixed length and one
        where the length is determined at runtime) as well as a nested structure
        and a union.
        <screen><markup>
          &lt;?xml version="1.0" encoding="UTF-8"?&gt;
          &lt;data&gt;
            &lt;struct name="complex"&gt;
              &lt;primitive name="size" type="UInt8" /&gt;
              &lt;union name="aUnion"&gt;
                &lt;array name="fourBytes" length="4"&gt;
                  &lt;primitive type="Int8" /&gt;
                &lt;/array&gt;
              &lt;/union&gt;
              &lt;struct name="nested"&gt;
                &lt;array name="string" length="size"&gt; &lt;!-- references the field size above --&gt;
                  &lt;primitive type="Char" /&gt;
                &lt;/array&gt;
              &lt;/struct&gt;
            &lt;/struct&gt;
          &lt;/data&gt;
          </markup></screen>
          This would correspond to the following in pseudo-C/C++
          <screen>
          struct complex {
            uint8_t size;
            union aUnion {
              int8_t fourBytes[4];
            };
            struct nested {
              char string[size] //not valid C++, references value of the uint8 size
            };
          };
          </screen>
          </para>
          <note><para>You can obviously only have dynamic length arrays
          reference fields before the array.</para></note>
          <para>Next we create the <filename>complex.desktop</filename> file just as
          in the example before (make sure you set <literal>X-KDE-PluginInfo-Name</literal>
          correctly) and also do the same to install both files.</para>
      </sect3>
      <sect3>
        <title>Further information</title>
        <para>
          A few example structure definitions can be found <ulink url="http://websvn.kde.org/branches/KDE/4.9/kdesdk/okteta/kasten/controllers/view/structures/examples/">here.</ulink>
          This includes for example the file header for PNG files and the ELF file header.
          An &XML; schema describing the structure of the <literal role="extension">.osd</literal> file can be found  <ulink url="http://websvn.kde.org/branches/KDE/4.9/kdesdk/okteta/kasten/controllers/view/structures/schema/">here.</ulink>
          If more information is needed feel free to contact me at &Alex.Richardson.email;
        </para>
      </sect3>
    </sect2>
</sect1>
<!--FIXME missing 
Extended structures definitions 
  Structures Script Console-->
</chapter>

<chapter id="menu-commands">
<title>Menu Entries</title>

<para>Note that most menu commands also have a keyboard shortcut.</para>

<sect1 id="file-menu">
<title>File Menu</title>

<variablelist>
    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
    </shortcut>
    <guimenu>File</guimenu>
    <guimenuitem>New</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Create a new byte array...</action></para>
    <itemizedlist>
    <listitem><para><guimenuitem>Empty</guimenuitem>: ... as Empty one.</para>
    </listitem>
    <listitem><para><guimenuitem>From Clipboard</guimenuitem>: ... by the current
    content of the clipboard.</para></listitem>
    <listitem><para><guimenuitem>Pattern...</guimenuitem>: ... with a given pattern.</para>
    </listitem>
    <listitem><para><guimenuitem>Random Data...</guimenuitem>: ...with random data.</para></listitem>
    <listitem><para><guimenuitem>Sequence</guimenuitem>: ... with all the bytes
    from 0 to 255.</para></listitem>
    </itemizedlist>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo>
    </shortcut>
    <guimenu>File</guimenu>
    <guimenuitem>Open...</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Open an existing file.</action></para></listitem>
    </varlistentry>

    <!--<varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;<keycap>I</keycap></keycombo>
    </shortcut>
    <guimenu>File</guimenu>
    <guimenuitem>Insert...</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Insert an exiting file in the current
    document.</action></para></listitem>
    </varlistentry>-->

    <varlistentry>
    <term><menuchoice>
    <guimenu>File</guimenu>
    <guisubmenu>Open Recent</guisubmenu>
    </menuchoice></term>
    <listitem><para><action>Choose from a list of the last opened
    files.</action></para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo>
    </shortcut>
    <guimenu>File</guimenu>
    <guimenuitem>Save</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Save byte array to the assigned file.</action></para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <guimenu>File</guimenu>
    <guimenuitem>Save As...</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Save byte array to another file with a new name.</action></para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <guimenu>File</guimenu>
    <guisubmenu>Export</guisubmenu>
    </menuchoice></term>
    <listitem><para>Export the selected bytes to a file...</para>
    <itemizedlist>
    <listitem><para><guimenuitem>Values</guimenuitem>: ... encoded as byte values.</para>
    </listitem>
    <listitem><para><guimenuitem>Plain Text</guimenuitem>: ... encoded as characters.
    </para></listitem>
    <listitem><para><guimenuitem>Base64</guimenuitem>: ... encoded in the Base64
    format.</para></listitem>
    <listitem><para><guimenuitem>C array</guimenuitem>: ... defined as
    an array in the programming language C.</para></listitem>
    <listitem><para><guimenuitem>View in Plain Text</guimenuitem>: ... as in the data view with offset, byte values and characters. </para></listitem>
    </itemizedlist>
    </listitem>
    <!--FIXME missing: Characters, Base32, Ascii85, Uuencoding, Xxencoding, Intel Hex, S-Record-->
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut><keycap>F5</keycap></shortcut>
    <guimenu>File</guimenu>
    <guimenuitem>Reload</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Discards all changes and reloads the byte array from
    the file.</action></para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo>
    </shortcut>
    <guimenu>File</guimenu>
    <guimenuitem>Print...</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Print the current byte array.</action></para></listitem>
    </varlistentry>

<!--    <varlistentry>
    <term><menuchoice>
    <guimenu>File</guimenu>
    <guimenuitem>Export...</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Export the selected document or a portion of
    it.</action></para><para>Opens a dialog box with these options:</para>
    <variablelist>
    <varlistentry>
    <term><guilabel>Format</guilabel></term>
    <listitem><para>Plain text, &HTML; table, rich text
    format, C array.  Use the <guilabel>Options</guilabel> tab to select
    details for a C array or an &HTML; table.</para></listitem>
    </varlistentry>
    <varlistentry>
    <term><guilabel>Destination</guilabel></term>
    <listitem><para>The file to which the data will be
    exported</para></listitem>
    </varlistentry>
    <varlistentry>
    <term><guilabel>Export Range</guilabel></term>
    <listitem><para>Selects which data will be exported - - the entire document, the
    selected portion or the range between two specified
    offsets.</para></listitem>
    </varlistentry>
    </variablelist>
    </listitem></varlistentry>-->

    <!--<varlistentry>
    <term><menuchoice>
    <guimenu>File</guimenu>
    <guimenuitem>Cancel Operation</guimenuitem>
    </menuchoice></term>
    <listitem><para>Stop the current operation</para></listitem>
    </varlistentry>-->

    <varlistentry>
    <term><menuchoice>
    <guimenu>File</guimenu>
    <guimenuitem>Permissions</guimenuitem>
    </menuchoice></term>
    <listitem><para>Set modification privileges:</para>
    <variablelist>

    <varlistentry>
    <term><guilabel>Set Read-only</guilabel></term>
    <listitem><para>When set, changes may not be made to the loaded
    byte array.</para></listitem>
    </varlistentry>
    <!--<varlistentry>
    <term><guilabel>Allow Resize</guilabel></term>
    <listitem><para>When off, individual bytes may be edited but the total number of
    bytes may not be changed.</para></listitem>
    </varlistentry>-->
    </variablelist>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;<keycap>W</keycap></keycombo>
    </shortcut>
    <guimenu>File</guimenu>
    <guimenuitem>Close</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Close the current byte array.</action></para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <guimenu>File</guimenu>
    <guimenuitem>Close All</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Close all byte arrays.</action></para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <guimenu>File</guimenu>
    <guimenuitem>Close All Other</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Close all besides the current byte array.</action></para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo>
    </shortcut>
    <guimenu>File</guimenu>
    <guimenuitem>Quit</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Close the</action> &okteta;
    window.</para></listitem>
    </varlistentry>
</variablelist>
</sect1>

<sect1 id="edit-menu">
<title>Edit Menu</title>
<!--FIXME in 4.9 still true? change 4.4 to 4.9-->
<para>Currently in &kde; 4.4 simple copy and cut send data to the clipboard with the
mimetype "application/octetstream", &klipper; is not able to display this data.
And almost all other applications cannot handle this, too, as this is
simply raw data. So also see for the <guisubmenu>Copy as</guisubmenu> submenu.</para>
<variablelist>
    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;<keycap>Z</keycap></keycombo>
    </shortcut>
    <guimenu>Edit</guimenu>
    <guimenuitem>Undo</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Undo the last action.</action></para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;&Shift;<keycap>Z</keycap></keycombo>
    </shortcut>
    <guimenu>Edit</guimenu>
    <guimenuitem>Redo</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Redo the last undone action.</action></para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;<keycap>X</keycap></keycombo>
    </shortcut>
    <guimenu>Edit</guimenu>
    <guimenuitem>Cut</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Delete the selected bytes and copy them to the
    clipboard.</action></para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo>
    </shortcut>
    <guimenu>Edit</guimenu>
    <guimenuitem>Copy</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Copy the selected bytes to the
    clipboard.</action></para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;<keycap>V</keycap></keycombo>
    </shortcut>
    <guimenu>Edit</guimenu>
    <guimenuitem>Paste</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Insert the cut or copied bytes in the
    clipboard.</action></para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <guimenu>Edit</guimenu>
    <guisubmenu>Copy as</guisubmenu>
    </menuchoice></term>
    <listitem><para>Copy the selected bytes to the clipboard...</para>
    <itemizedlist>
    <listitem><para><guimenuitem>Values</guimenuitem>: ... encoded as byte values.</para>
    </listitem>
    <listitem><para><guimenuitem>Plain Text</guimenuitem>: ... encoded as characters.
    </para></listitem>
    <listitem><para><guimenuitem>Base64</guimenuitem>: ... encoded in the Base64
    format.</para></listitem>
    <listitem><para><guimenuitem>C array</guimenuitem>: ... defined as
    an array in the programming language C.</para></listitem>
    <listitem><para><guimenuitem>View in Plain Text</guimenuitem>: ... as in the data view with offset, byte values and characters. </para></listitem>
    </itemizedlist>
    </listitem>
    <!--FIXME missing: Characters, Base32, Ascii85, Uuencoding, Xxencoding, Intel Hex, S-Record, see also File export-->

    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <guimenu>Edit</guimenu>
    <guisubmenu>Insert</guisubmenu>
    </menuchoice></term>
    <listitem>
    <variablelist>
    <varlistentry>
    <term><menuchoice>
    <guimenuitem>Insert Pattern...</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Insert a specified string of bytes at the cursor.</action></para>
    <para>Options in the dialog box allow you to specify the number of insertion of the pattern
    and it's format (Hexadecimal, Decimal, Octal, Binary, Character(s) or UTF-8).</para>
    <!--para>If <guilabel>Repeat pattern</guilabel> is checked, the specified pattern
    will be inserted repeatedly to reach the length set in
    <guilabel>Size</guilabel>.</para--></listitem>
    <!--FIXME Random Data + Sequence - use cases?-->
    </varlistentry>
    </variablelist>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;<keycap>A</keycap></keycombo>
    </shortcut>
    <guimenu>Edit</guimenu>
    <guimenuitem>Select All</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Select the entire byte array.</action></para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;&Shift;<keycap>A</keycap></keycombo>
    </shortcut>
    <guimenu>Edit</guimenu>
    <guimenuitem>Deselect</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Deselect the current selection.</action></para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;<keycap>E</keycap></keycombo>
    </shortcut>
    <guimenu>Edit</guimenu>
    <guimenuitem>Select Range...</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Opens an embedded dialog to enter the range to
    select.</action></para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul"><keycap>Ins</keycap></keycombo>
    </shortcut>
    <guimenu>Edit</guimenu>
    <guimenuitem>Overwrite Mode</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Switch between Insert mode and Overwrite mode</action>.
    </para>
    <note><para>Overwrite mode is implemented to be very strict, it is not possible to
    change the size of the data (no appending or removing of bytes).</para></note>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;<keycap>F</keycap></keycombo>
    </shortcut>
    <guimenu>Edit</guimenu>
    <guimenuitem>Find...</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Find a specified pattern in the document.</action>
    Hexadecimal, decimal, octal, binary or text patterns can be searched for.</para>
    <para>Options in the dialog box allow you to specify the starting point,
    direction and range of the search.</para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul"><keycap>F3</keycap></keycombo>
    </shortcut>
    <guimenu>Edit</guimenu>
    <guimenuitem>Find Next</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Find the next instance</action> of the
    <guimenuitem>Find</guimenuitem> pattern.</para>
    <para>If there isn't a pattern specified, the dialog box will be shown.</para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Shift;<keycap>F3</keycap></keycombo>
    </shortcut>
    <guimenu>Edit</guimenu>
    <guimenuitem>Find Previous</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Find the previous instance</action> of the
    <guimenuitem>Find</guimenuitem> pattern.</para>
    <para>If there isn't a pattern specified, the dialog box will be shown.</para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;<keycap>R</keycap></keycombo>
    </shortcut>
    <guimenu>Edit</guimenu>
    <guimenuitem>Replace...</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Replace</action> the find pattern with a different
    pattern.</para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;<keycap>G</keycap></keycombo>
    </shortcut>
    <guimenu>Edit</guimenu>
    <guimenuitem>Goto Offset...</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Move the cursor to a specified
    offset.</action></para></listitem>
    </varlistentry>

</variablelist>
</sect1>

<sect1 id="view-menu">
<title>View Menu</title>

<variablelist>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;<keycap>+</keycap></keycombo>
    </shortcut>
    <guimenu>View</guimenu>
    <guimenuitem>Zoom In</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Increase the size of the font.</action></para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;<keycap>-</keycap></keycombo>
    </shortcut>
    <guimenu>View</guimenu>
    <guimenuitem>Zoom Out</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Decrease the size of the font.</action></para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <guimenu>View</guimenu>
    <guimenuitem>Show Non-printing Chars</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Toggle display of non-printing chars on and
    off.</action> If the display is turned off, at the corresponding places in
    the character column a substitute char is shown instead.</para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycap>F11</keycap>
    </shortcut>
    <guimenu>View</guimenu>
    <guimenuitem>Show Line Offset</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Toggle display of the line offset on a pane to the left
    on and off.</action></para></listitem>
    </varlistentry>


    <varlistentry>
    <term><menuchoice>
    <guimenu>View</guimenu>
    <guisubmenu>Show Values or Chars</guisubmenu>
    </menuchoice></term>
    <listitem><para><action>Select which of the byte interpretations are shown.</action>
    Possible are:</para>
    <itemizedlist>
    <listitem><para><guimenuitem>Values</guimenuitem></para>
    </listitem>
    <listitem><para><guimenuitem>Chars</guimenuitem></para></listitem>
    <listitem><para><guimenuitem>Values and Chars</guimenuitem></para></listitem>
    </itemizedlist>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <guimenu>View</guimenu>
    <guisubmenu>Value Coding</guisubmenu>
    </menuchoice></term>
    <listitem><para><action>Select the coding of the values</action> from:</para>
    <itemizedlist>
    <listitem><para><guimenuitem>Hexadecimal</guimenuitem></para></listitem>
    <listitem><para><guimenuitem>Decimal</guimenuitem></para></listitem>
    <listitem><para><guimenuitem>Octal</guimenuitem></para></listitem>
    <listitem><para><guimenuitem>Binary</guimenuitem></para></listitem>
    </itemizedlist>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <guimenu>View</guimenu>
    <guisubmenu>Char Coding</guisubmenu>
    </menuchoice></term>
    <listitem><para><action>Select the coding of the chars</action>
    from the submenu.
    </para>
    </listitem>
    </varlistentry>
    <!--FIXME missing Set Bytes per Line, Set Bytes per Group-->
    <varlistentry>
    <term><menuchoice>
    <guimenu>View</guimenu>
    <guisubmenu>Dynamic Layout</guisubmenu>
    </menuchoice></term>
    <listitem><para><action>Set the rules for the layout of the data display.</action>
    This defines how many bytes are displayed per line, depending on the width of the
    view. Possible rules are:</para>
    <itemizedlist>
    <listitem><para><guimenuitem>Off</guimenuitem>: The layout is fixed to the
    current number of bytes per line and not adapted on the change of the view size.</para>
    </listitem>
    <listitem><para><guimenuitem>Wrap only complete byte groups</guimenuitem>: Puts as many bytes
    per line as possible, as long as groups of bytes are complete.
    </para></listitem>
    <listitem><para><guimenuitem>On</guimenuitem>: Same as previous,
    but allows also incomplete groups of bytes.</para></listitem>
    </itemizedlist>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <guimenu>View</guimenu>
    <guisubmenu>View Mode</guisubmenu>
    </menuchoice></term>
    <listitem><para><action>Select the layout for the view</action> from:</para>
    <itemizedlist>
    <listitem><para><guimenuitem>Columns</guimenuitem>: The values and chars
    interpretations are shown in the classic layout with each listed in a
    separate column.</para></listitem>
    <listitem><para><guimenuitem>Rows</guimenuitem>: The char
    interpretation of a byte is directly shown under the value interpretation.</para></listitem>
    </itemizedlist>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;&Shift;<keycap>T</keycap></keycombo>
    </shortcut>
    <guimenu>View</guimenu>
    <guimenuitem>Split Horizontal</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Split the view area with the currently focused view
    into two parts and add a copy of the current view to the new, lower area.</action></para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;&Shift;<keycap>L</keycap></keycombo>
    </shortcut>
    <guimenu>View</guimenu>
    <guimenuitem>Split Vertically</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Split the view area with the currently focused view
    into two parts and add a copy of the current view to the new, right area.</action></para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;&Shift;<keycap>R</keycap></keycombo>
    </shortcut>
    <guimenu>View</guimenu>
    <guimenuitem>Close View Area</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Close the view area with the currently focused view.</action></para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <guimenu>View</guimenu>
    <guimenuitem>View Profile</guimenuitem>
    </menuchoice></term>
    <listitem><para>View settings can be separately stored as view profiles.
    The currently selected profile can be updated directly from the current view
    settings, or a new one can be created from them. All view profiles can be
    managed in a dialog available from <menuchoice><guimenu>Settings</guimenu><guimenuitem>Manage View Profiles...</guimenuitem></menuchoice>.</para></listitem>
    </varlistentry>

</variablelist>
</sect1>

<sect1 id="windows-menu">
<title>Windows Menu</title>

    <para>Provides a list of the current views. Select the active window.</para>

</sect1>

<sect1 id="bookmarks-menu">
<title>Bookmarks Menu</title>

    <para>Multiple bookmarks can be set for a single byte array. Each byte array
    has its own set of bookmarks, and the appropriate set is displayed at the
    bottom of the <guimenu>Bookmarks</guimenu> menu. Choose a bookmark
    from the menu to move the cursor and the view to it.
    <note><para>Bookmarks are currently only transient and not saved if you
    close a byte array or the whole program.</para></note></para>

<variablelist>
    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;<keycap>B</keycap></keycombo>
    </shortcut>
    <guimenu>Bookmarks</guimenu>
    <guimenuitem>Add Bookmark</guimenuitem>
    </menuchoice></term>
    <listitem><para>Bookmark a location within the byte array.</para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;&Shift;<keycap>B</keycap></keycombo>
    </shortcut>
    <guimenu>Bookmarks</guimenu>
    <guimenuitem>Remove Bookmark</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Remove the current bookmark.</action> This command
    is only available if the cursor is at a bookmarked location.</para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <guimenu>Bookmarks</guimenu>
    <guimenuitem>Remove All Bookmarks</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Clear the bookmark list.</action></para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Alt;<keycap>Up</keycap></keycombo>
    </shortcut>
    <guimenu>Bookmarks</guimenu>
    <guimenuitem>Goto Previous Bookmark</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Move the cursor to the previous
    bookmark.</action></para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Alt;<keycap>Down</keycap></keycombo>
    </shortcut>
    <guimenu>Bookmarks</guimenu>
    <guimenuitem>Go to Next Bookmark</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Move the cursor to the next
    bookmark.</action></para></listitem>
    </varlistentry>

</variablelist>
</sect1>

<sect1 id="tools-menu">
<title>Tools Menu</title>

    <para>Provides a list of installed tools. Toggle the display of each tools
    on or off. A detailed description of each tool you find in the <link linkend="tools">Tools</link> section.</para>
</sect1>

<sect1 id="settings-menu">
<title>Settings Menu</title>

<variablelist>
    <varlistentry>
    <term><menuchoice>
    <guimenu>Settings</guimenu>
    <guimenuitem>Manage View Profiles...</guimenuitem>
    </menuchoice></term>
    <listitem><para>Open a dialog to create, edit, delete and set a default view profile.</para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <guimenu>Settings</guimenu>
    <guimenuitem>Show Toolbar</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Toggle display of the toolbar below the
    menu bar.</action></para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <guimenu>Settings</guimenu>
    <guimenuitem>Show Statusbar</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Toggle display of the status bar.</action></para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <shortcut>
    <keycombo action="simul">&Ctrl;&Shift;<keycap>F</keycap></keycombo>
    </shortcut>
    <guimenu>Settings</guimenu>
    <guimenuitem>Full Screen Mode</guimenuitem>
    </menuchoice></term>
    <listitem><para><action>Toggle full screen mode on and off.</action></para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <guimenu>Settings</guimenu>
    <guimenuitem>Configure Shortcuts...</guimenuitem>
    </menuchoice></term>
    <listitem><para>Change program action shortcuts.</para></listitem>
    </varlistentry>

    <varlistentry>
    <term><menuchoice>
    <guimenu>Settings</guimenu>
    <guimenuitem>Configure Toolbars...</guimenuitem>
    </menuchoice></term>
    <listitem><para>Control the content of the toolbar.</para></listitem>
    </varlistentry>

</variablelist>

</sect1>

<sect1 id="help-menu">
<title>Help Menu</title>

    &help.menu.documentation;

</sect1>



<sect1 id="toolbar"><title>Toolbar</title>
    <para>The toolbar contains icons for the following commands:</para>

    <note><para>(All behave identically to the menu command.)</para></note>

    <itemizedlist>
    <listitem><para><guiicon>New</guiicon></para></listitem>
    <listitem><para><guiicon>Open</guiicon></para></listitem>
    <listitem><para><guiicon>Save</guiicon></para></listitem>
    <listitem><para><guiicon>Save As</guiicon></para></listitem>
    <listitem><para><guiicon>Undo</guiicon></para></listitem>
    <listitem><para><guiicon>Redo</guiicon></para></listitem>
    <listitem><para><guiicon>Cut</guiicon></para></listitem>
    <listitem><para><guiicon>Copy</guiicon></para></listitem>
    <listitem><para><guiicon>Paste</guiicon></para></listitem>
    <listitem><para><guiicon>Find</guiicon></para></listitem>
    <listitem><para><guiicon>Find Next</guiicon></para></listitem>
    </itemizedlist>

</sect1>

</chapter>

<chapter id="credits">
    <title>Credits and License</title>

    <para>
    &okteta;
    </para>

    <!--List all the copyright holders here-->
    <para>Program Copyright 2006-2012 &Friedrich.Kossebau;
    &Friedrich.Kossebau.email;</para>

    <para>Documentation Copyright 2008,2010 &Friedrich.Kossebau;
    &Friedrich.Kossebau.email;, &Alex.Richardson; &Alex.Richardson.email;</para>

    <!-- TRANS:CREDIT_FOR_TRANSLATORS -->

    &underFDL;
    &underGPL;

</chapter>

<!-- !!!do not change ANYTHING after this line!!!! -->

<appendix id="installation">
    <title>Installation</title>

    <sect1 id="getting-kapp">
        <title>How to obtain &okteta;</title>
        &install.intro.documentation;
    </sect1>

    <sect1 id="Compilation">
        <title>Compilation and Installation</title>
        &install.compile.documentation;
    </sect1>
</appendix>

&documentation.index;
</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-omittag:t
sgml-shorttag:t
sgml-namecase-general:t
sgml-always-quote-attributes:t
sgml-indent-step:0
sgml-indent-data:nil
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
