home *** CD-ROM | disk | FTP | other *** search
/ Freelog 65 / Freelog065.iso / BAS / Bureautique / Gnumeric / gnumeric-1.3.92-rc1.exe / files-saving.xml < prev    next >
Encoding:
Text File  |  2004-11-01  |  44.3 KB  |  1,307 lines

  1. <sect1 id="sect-file-save">
  2.   <title>Saving Files</title>
  3.  
  4. <!-- TODO: Sync with file-opening.xml for parallel structure. -->
  5.  
  6.   <para>
  7.     There are several ways to save a &gnum; workbook that is
  8.     currently open.
  9.   </para>
  10.  
  11.   <para>
  12.     Existing files can be saved directly but this process does not
  13.     allow a user to change any settings to the file creation process. 
  14.   </para>
  15.  
  16.   <tip>
  17.     <title>Saving files directly</title>
  18.     <para>
  19.       If the workbook has already been saved to a file
  20.       or if the workbook was opened from a file that already existed,
  21.       &gnum; will simply overwrite the file with the newer version.
  22.  
  23.       <variablelist>
  24.     <title>Three alternative ways to save a file directly</title>
  25.       <varlistentry>
  26.       <term>
  27.         <emphasis role="bold">Using the Menus</emphasis>
  28.       </term>
  29.       <listitem>
  30.         <para> 
  31.           Select, in the <guimenu><accel>F</accel>ile</guimenu> menu, the
  32.           <guimenuitem><accel>S</accel>ave</guimenuitem> menu item.
  33.          </para>
  34.       </listitem>
  35.     </varlistentry>
  36.     <varlistentry>
  37.       <term>
  38.         <emphasis role="bold">Using the Standard Toolbar</emphasis>
  39.       </term>
  40.       <listitem>
  41.         <para>
  42.           Click on the <guibutton>Save</guibutton> button:
  43.           <guiicon>
  44.         <inlinemediaobject>
  45.             <imageobject>
  46.               <imagedata fileref="figures/button-save.png" format="PNG" />
  47.             </imageobject>
  48.             <textobject>
  49.               <phrase>An image of the file save button.</phrase>
  50.             </textobject>
  51.            </inlinemediaobject>
  52.           </guiicon>
  53.         </para>
  54.       </listitem>
  55.     </varlistentry>
  56.     <varlistentry>
  57.       <term>
  58.         <emphasis role="bold">Using a Keyboard Shortcut</emphasis>
  59.       </term>
  60.       <listitem>
  61.         <para>
  62.           Type the combination
  63.           <keycombo>
  64.             <keysym>Ctrl</keysym><keysym>s</keysym>
  65.           </keycombo>,
  66.           typing both keys simultaneously.
  67.         </para>
  68. <!-- TODO: render hack, remove me. -->
  69.         <para>
  70.         </para>
  71.       </listitem>
  72.     </varlistentry>
  73.       </variablelist>
  74.  
  75.       Each of these approaches will save the file directly, allowing
  76.       no intervention on the part the user. If the file has been newly
  77.       created, &gnum; will automatically launch the <interface>Save
  78.       As...</interface> dialog asking the user for a file name and
  79.       other configuration options for the file, as is explained below.
  80.     </para>
  81.   </tip>
  82.  
  83.   <para>
  84.     Users wishing to save an existing file to a new file must invoke
  85.     the <interface>Save As...</interface> dialog. The <interface>Save
  86.     As...</interface> dialog can be invoked at any time to save the
  87.     current workbook to a new file with either a different name or a
  88.     different file format type. This dialog is automatically launched
  89.     when a user attempts to use one of the methods described above to
  90.     save a workbook which does not already have an existing file.
  91.     </para>
  92.  
  93.   <para>
  94.     The <interface>Save As...</interface>
  95.     dialog asks the user to provide a name for the file to be
  96.     created, to select a folder in which to place the new file, and to
  97.     select a file format type for the file.
  98.   </para>
  99.  
  100.   <tip>
  101.     <title>The steps required to save a file to a standard location.</title>
  102.  
  103.     <para></para>
  104. <!--TODO: render hack, remove me.  -->
  105.  
  106.     <orderedlist>
  107.       <listitem>
  108.         <para>
  109.       Launch the  <interface>File Save</interface> dialog.
  110.     </para>
  111.     <para>
  112.       In the <guimenu>File</guimenu> menu, select the
  113.       <guimenuitem>Save As</guimenuitem> menu item.
  114.     </para>
  115.       </listitem>
  116.       <listitem>
  117.         <para>
  118.       Name the file. Open the folder containing the desired file.
  119.     </para>
  120.     <para>
  121.       In the text entry area, enter the file name.
  122.     </para>
  123.       </listitem>
  124.       <listitem>
  125.         <para>
  126.       Select the desired folder in which to save the file.
  127.     </para>
  128.     <para>
  129.       Select one of the standard locations to open the file.
  130.     </para>
  131.       </listitem>
  132.       <listitem>
  133.         <para>
  134.       Specify a file format type.
  135.     </para>
  136.       </listitem>
  137.       <listitem>
  138.         <para>
  139.       Click on the <guibutton>Save</guibutton> button.
  140.     </para>
  141.       </listitem>
  142.     </orderedlist>
  143.  
  144.   </tip>
  145.  
  146.   <para>
  147.     The remainder of this section explains these steps in greater
  148.     detail, first, by describing the components in the <interface>File
  149.     Save</interface> dialog and, then, by explaining each of the steps
  150.     above in greater detail.
  151.   </para>
  152.  
  153.  
  154.   <sect2 id="sect-file-save-dialog">
  155.     <title>Using the <interface>File Save</interface> dialog.</title>
  156.  
  157.     <para>
  158.       Saving a workbook to a file can be a simple process, depending
  159.       on the folder in which the file is to be saved. If this folder
  160.       is in the predefined list of standard folders and user bookmark
  161.       folders, the file can be created with the compact
  162.       <interface>File Save</interface> dialog. The components of the
  163.       compact <interface>File Save</interface> dialog and the
  164.       procedure to save a workbook to a file in the predefined list of
  165.       folders are explained next.
  166.  
  167.     </para>
  168.  
  169.     <para>
  170.       However, when the workbook is to be saved to a file created in a
  171.       folder which is not in the preselected list, the expanded
  172.       <interface>File Save</interface> dialog will be required. The
  173.       components of the expanded <interface>File Save</interface>
  174.       dialog, the procedure for saving files in a different folder,
  175.       and an explanation of bookmark folders and their use are given
  176.       further below.
  177.     </para>
  178.  
  179.  
  180.     <sect3 id="sect-file-save-dialog-compact-components">
  181.       <title>
  182.         The components of the compact <interface>File Save</interface>
  183.         dialog. 
  184.       </title>
  185.  
  186.       <para>
  187.         The <interface>File Save</interface> dialog allows the user to
  188.         save a workbook into a new file but requires that the user
  189.         provide a name for the file, select the folder in which to
  190.         save the file, and select a file format type to use for this
  191.         file. This dialog also provides a way to navigate the folder
  192.         hierarchy as will be explained further below.
  193.       </para>
  194.  
  195.       <para>
  196.         The <interface>File Save</interface> dialog first opens in a
  197.         compact layout. The different areas of the dialog in this
  198.         compact layout are shown and labeled in <xref
  199.         linkend="fig-file-save-dialog-compact-components" />.
  200.       </para>
  201.       
  202.       <figure id="fig-file-save-dialog-compact-components">
  203.         <title>
  204.       The compact form of the <interface>File Save</interface>
  205.       dialog.
  206.     </title>
  207.     <screenshot>
  208.           <mediaobject> 
  209.         <imageobject> 
  210.           <imagedata fileref="figures/dialog-filesave-compact-withTags.png"
  211.                      format="PNG" />
  212.         </imageobject>
  213.         <textobject>
  214.           <para> 
  215.             This screenshot depicts the 'File Save' dialog in its
  216.             compact form with the different areas labeled.
  217.           </para>
  218.         </textobject>
  219.       </mediaobject>
  220.     </screenshot>
  221.     <!-- <caption></caption>  -->
  222.       </figure>
  223.  
  224.       <para>
  225.         The purpose of each labeled area will be explained below:
  226.  
  227.     <variablelist>
  228.       <title>The components of the compact  <interface>File
  229.       Save</interface> dialog</title>
  230.  
  231.       <varlistentry>
  232.         <term>
  233.           <emphasis role="bold">A</emphasis> - The naming area.
  234.  
  235.         </term>
  236.         <listitem>
  237.           <para>
  238.             This area is used to give the file its name. This is a
  239.         standard text entry area allowing all the basic
  240.         editing commands. The cursor can be moved left or
  241.         right using the keyboard arrow keys. The cursor can be
  242.         placed anywhere in the text by placing the mouse
  243.         pointer where the cursor should go and clicking with
  244.         the primary mouse button. The mouse can also select
  245.         part or all of the text with a click and drag. The
  246.         keyboard shortcuts for copying,
  247.         <keycombo><keysym>Ctrl</keysym><keysym>c</keysym></keycombo>,
  248.         cutting,
  249.         <keycombo><keysym>Ctrl</keysym><keysym>x</keysym></keycombo>,
  250.         or pasting,
  251.         <keycombo><keysym>Ctrl</keysym><keysym>x</keysym></keycombo>,
  252.         all work. The dialog uses filename matching to guess
  253.         file names based on the files already in the parent
  254.         folder.
  255. <!-- TODO: explain gnum system for adding extensions automatically. --> 
  256.           </para>
  257.         </listitem>
  258.           </varlistentry>
  259.  
  260.       <varlistentry>
  261.         <term>
  262.           <emphasis role="bold">B</emphasis> - The folder
  263.           selection area.
  264.         </term>
  265.         <listitem>
  266.           <para>
  267.             This area provides a drop down list of previously
  268.             selected folders including the standard folders and
  269.             the folders which have been bookmarked by the
  270.             user. The area will be disabled if area <emphasis
  271.             role="bold">D</emphasis> has been selected to expand
  272.             the dialog.
  273.           </para>
  274.           <para>
  275.             The desired folder can be selected by moving the mouse
  276.             pointer over the button, clicking and holding the
  277.             primary mouse button, dragging the mouse pointer onto
  278.             the name of the desired folder and releasing the mouse
  279.             button. The new folder name will appear on as the name
  280.             on the button.
  281.           </para>
  282.         </listitem>
  283.           </varlistentry>
  284.  
  285.       <varlistentry>
  286.         <term>
  287.           <emphasis role="bold">C</emphasis> - The file format type
  288.           selection area.
  289.         </term>
  290.         <listitem>
  291.           <para>
  292.             This area provides a drop down list of all the file
  293.             formats provided by the &gnum; program itself and by
  294.             all the currently active plugins.
  295.           </para>
  296.           <note>
  297.             <para>
  298.           If the file format type named "Text export
  299.           (configurable)" is opened, this will start the text
  300.           export procedure. <xref
  301.           linkend="sect-file-textExport"/> explains this
  302.           procedure in complete detail.
  303.         </para>
  304.           </note>
  305.         </listitem>
  306.           </varlistentry>
  307.  
  308.       <varlistentry>
  309.         <term>
  310.           <emphasis role="bold">D</emphasis> - The dialog
  311.           expansion area.
  312.         </term>
  313.         <listitem>
  314.           <para>
  315.             This area will alter the dialog to expand or collapse
  316.             it. When expanded the dialog provides a way to select
  317.             any folder accessible on the system, to create new
  318.             folders and to add and remove bookmark folders from
  319.             the user's bookmark folder list. When the dialog is
  320.             expanded, the small arrow will point downward, the
  321.             areas showing in <xref
  322.             linkend="fig-file-save-dialog-expanded-components"/>
  323.             will appear and area <emphasis
  324.             role="bold">B</emphasis> will be disabled.
  325.           </para>
  326.         </listitem>
  327.           </varlistentry>
  328.  
  329.       <varlistentry>
  330.         <term>
  331.           <emphasis role="bold">E</emphasis> - The button area.
  332.  
  333.         </term>
  334.         <listitem>
  335.           <para>
  336.            This area provides two buttons, the
  337.           <guibutton>Cancel</guibutton> and the
  338.           <guibutton>Save</guibutton> buttons. Clicking the
  339.           <guibutton>Cancel</guibutton> button will dismiss the dialog
  340.           and return the user to the worksheet. Clicking the
  341.           <guibutton>Save</guibutton> button will cause a file to
  342.           be created with the currently selected name, parent folder
  343.           and format. If the selected file already exists, &gnum;
  344.           will open a confirmation dialog since the command will
  345.           obliterate the previously existing file.
  346.           </para>
  347.         </listitem>
  348.           </varlistentry>
  349.  
  350.  
  351.  
  352.         </variablelist>
  353.  
  354.       </para>
  355.  
  356.  
  357.  
  358.       <para>
  359.         The procedure to save a file using this dialog in its compact
  360.         form is present next, in <xref
  361.         linkend="sect-file-save-dialog-quickintro" />. The
  362.         components of the dialog in its expanded layout, converted by
  363.         clicking in area <emphasis role="bold">D</emphasis> when the
  364.         <interface>File Save</interface> dialog is in its compact
  365.         form, will be explained further on, in <xref
  366.         linkend="sect-file-save-dialog-expanded-components" />,
  367.         followed by sections explaining the use of the dialog in this
  368.         expanded layout.
  369.       </para>
  370.  
  371.  
  372.     </sect3>
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.     <sect3 id="sect-file-save-dialog-quickintro">
  381.       <title>
  382.         The basic file saving procedure.
  383.       </title>
  384.  
  385.       <para>
  386.         Saving a workbook to a new file requires providing name the
  387.         file, selecting a folder in which the file will be placed, and
  388.         selecting a file format type.
  389.       </para>
  390.  
  391.       <para>
  392.         The default action, if a user simply opens the <interface>File
  393.         Save</interface> dialog and clicks on the
  394.         <guibutton>Save</guibutton> button, is to name the file
  395.         <filename>Book1.gnumeric</filename> incrementing the number
  396.         for each new file created, to save the file in the user's home
  397.         folder, and to create a file in the &gnum; file format.
  398.       </para>
  399.  
  400.       <warning>
  401.         <para>
  402.       If the user provides a name for the file to be saved which
  403.       is the same as the name of a file that already exists,
  404.       &gnum; will open up a confirmation dialog asking the user if
  405.       they really want to overwrite the existing file. If the user
  406.       then clicks on the <guibutton>Yes</guibutton> button, the
  407.       existing file will be destroyed and the new file created in
  408.       its place.
  409.     </para>
  410.       </warning>
  411.  
  412.       <procedure>
  413.         <title>The procedure to save a file.</title>
  414.  
  415.         <step>
  416.       <title>
  417.         Open the <interface>File Save</interface> dialog.
  418.       </title>
  419.       <para>
  420.         First, the dialog must be opened using either of the two
  421.       following methods:
  422.       </para>
  423.     
  424.       <variablelist>
  425.     <title>
  426.       Two alternative ways to open the <interface>File
  427.       Save</interface> dialog.
  428.     </title>
  429.  
  430.     <varlistentry>
  431.       <term>
  432.         <emphasis role="bold">Using the Menus</emphasis>
  433.       </term>
  434.       <listitem>
  435.         <para> 
  436.           Select, in the <guimenu><accel>F</accel>ile</guimenu>
  437.           menu, the 
  438.           <guimenuitem>S<accel>a</accel>ve as...</guimenuitem>
  439.           menu item.
  440.         </para>
  441.       </listitem>
  442.     </varlistentry>
  443.     <varlistentry>
  444.       <term>
  445.         <emphasis role="bold">Using a Keyboard Shortcut</emphasis>
  446.       </term>
  447.       <listitem>
  448.         <para>
  449.           Type the combination
  450.           <keycombo>
  451.             <keysym>Shift</keysym>
  452.         <keysym>Ctrl</keysym>
  453.         <keysym>s</keysym>
  454.           </keycombo>,
  455.           typing all three keys simultaneously.
  456.         </para>
  457.       </listitem>
  458.     </varlistentry>
  459.       </variablelist>
  460.  
  461.           <para>
  462.             Both methods will launch the <interface>File
  463.             Save</interface> dialog to allow the user to name the
  464.             file, select a folder (also called a directory) for the
  465.             file and choose a file format type. This dialog will also
  466.             open automatically the first time a new workbook is saved.
  467.           </para>
  468.  
  469.  
  470.     </step>
  471.  
  472.         <step>
  473.       <title>
  474.         Select a name for the file.
  475.       </title>
  476.       <para>
  477.         Next, a name must be given for the file. &gnum; provides a
  478.         default name but, when the dialog is first opened this
  479.         name is highlighted indicating that it is already
  480.         selected. Therefore, a user can simply start typing a new
  481.         name and the first character entered will delete the name
  482.         given by default. The file name field is presented as area
  483.         <emphasis role="bold">A</emphasis> in <xref
  484.         linkend="fig-file-save-dialog-compact-components"/>.
  485.       </para>
  486.       <note>
  487.         <para>
  488.           If typing a name does not have any effect, the 'focus'
  489.           was probably inadvertently changed from the text entry
  490.           area. Focus can be returned to the area by placing the
  491.           mouse pointer over the box and clicking the primary
  492.           mouse button. All the standard keyboard editing commands
  493.           work in this text area and the mouse can be used to
  494.           select text or to move the cursor location.
  495.         </para>
  496.       </note>
  497.     </step>
  498.  
  499.         <step>
  500.       <title>
  501.         Select a folder in which to save the file.
  502.       </title>
  503.       <para>
  504.         Then, the folder in which to save the file can be chosen
  505.         from the drop down list shown as area <emphasis
  506.         role="bold">B</emphasis> in <xref
  507.         linkend="fig-file-save-dialog-compact-components"/>.
  508.       </para>
  509.  
  510.       <para>
  511.         Using this list requires placing the mouse pointer above
  512.         the list button and clicking with the primary mouse button
  513.         to open the list. The desired folder can then be selected
  514.         by moving the pointer down the list and clicking again
  515.         with the primary mouse button. The second click will close
  516.         the drop down list and change the selected folder. Instead
  517.         of the two mouse clicks, the entire operation can be
  518.         replaced by a click-hold, drag and release, where the
  519.         first mouse click is replaced by the click-and-hold and
  520.         the second mouse click is replaced by the release.
  521.       </para>
  522.  
  523.       <para>
  524.         This list only provides a limited number of choices
  525.         including several standard folders and any bookmark
  526.         folders the user has previously added to the file
  527.         selector. Other folders can be chosen, new folders can be
  528.         created, and the list of bookmark folders available can
  529.         be changed, by clicking in area <emphasis
  530.         role="bold">D</emphasis> to change to the expanded dialog,
  531.         as will be explained further below, in <xref
  532.         linkend="sect-file-save-dialog-chdir" />, <xref
  533.         linkend="sect-file-save-dialog-mkdir" /> and <xref
  534.         linkend="sect-file-save-dialog-bookmarks" />.
  535.       </para>
  536.     </step>
  537.  
  538.         <step>
  539.       <title>
  540.         Select a file type.
  541.       </title>
  542.  
  543.       <para>
  544.         Next, the desired file type must be selected. Area
  545.         <emphasis role="bold">C</emphasis> in <xref
  546.         linkend="fig-file-save-dialog-compact-components"/>
  547.         provides a drop down list of file types. The process for
  548.         using this list is the same as was described in the
  549.         previous step. The file types are listed below in <xref
  550.         linkend="sect-file-save" /> and explained in
  551.         detail in <xref linkend="sect-file-formats" />.
  552.       </para>
  553.           <note>
  554.             <para>
  555.           If the file format type named "Text export
  556.           (configurable)" is opened, this will start the text
  557.           export procedure. <xref
  558.           linkend="sect-file-textExport"/> explains this
  559.           procedure in complete detail.
  560.         </para>
  561.           </note>
  562.  
  563.     </step> 
  564.  
  565.         <step>
  566.       <title>
  567.         Click the <guibutton>Save</guibutton> button.
  568.       </title>
  569.       <para>
  570.         Finally, the <guibutton>Save</guibutton> button must be
  571.         pressed by placing the mouse pointer over the button and
  572.         clicking with the primary mouse button.
  573.       </para>
  574.     </step>
  575.       </procedure>
  576.  
  577.  
  578.       <para>
  579.         This basic procedure does not allow a user to save the file
  580.         into folder other than one already provided. An expanded
  581.         procedure is needed to explain how to save a file into other
  582.         folders in the file system. The next section explains the
  583.         extra elements provided when the <interface>File
  584.         Save</interface> dialog is expanded and that section is
  585.         followed by a step-by-step procedure explaining how to use
  586.         this expanded dialog.
  587.       </para>
  588.  
  589.     </sect3>
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.     <sect3 id="sect-file-save-dialog-expanded-components">
  599.       <title>
  600.         The extra components in the expanded <interface>File Save</interface>
  601.         dialog. 
  602.       </title>
  603.  
  604.       <para>
  605.         In order to select folders other than those provided in the
  606.         drop down list shown as area <emphasis
  607.         role="bold">B</emphasis> in <xref
  608.         linkend="fig-file-save-dialog-compact-components"/>,
  609.         the <interface>File Save</interface> dialog must be expanded
  610.         by clicking in the area labeled <emphasis
  611.         role="bold">D</emphasis>. In the expanded form, the
  612.         <interface>File Save</interface> dialog allows a user to
  613.         select a new folder in which to save a file, to create new
  614.         folders, and to add bookmark folders to the list
  615.         provided in the area labeled <emphasis
  616.         role="bold">C</emphasis>.
  617.       </para>
  618.  
  619.       <para>
  620.         This section will explain the extra components of the
  621.         <interface>File Save</interface> dialog which are provided
  622.         when the dialog is expanded. <xref
  623.         linkend="fig-file-save-dialog-expanded-components" />
  624.         shows these different areas and adds a label to each.
  625.       </para>
  626.       
  627.  
  628.       <figure id="fig-file-save-dialog-expanded-components">
  629.         <title>
  630.       The expanded form of the <interface>File Save</interface>
  631.       dialog.
  632.     </title>
  633.     <screenshot>
  634.           <mediaobject> 
  635.         <imageobject> 
  636.           <imagedata fileref="figures/dialog-filesave-expanded-withTags.png"
  637.                      format="PNG" />
  638.         </imageobject>
  639.         <textobject>
  640.           <para> 
  641.             This screenshot depicts the 'File Save' dialog in its
  642.             expanded form with the different areas labeled.
  643.           </para>
  644.         </textobject>
  645.       </mediaobject>
  646.     </screenshot>
  647.     <!-- <caption></caption>  -->
  648.       </figure>
  649.  
  650.       <para>
  651.         The different parts of each panel of the <interface>File
  652.         Save</interface> dialog after it has been expanded have been
  653.         shaded with boxes of different colors and labeled with a
  654.         letter in <xref
  655.         linkend="fig-file-save-dialog-expanded-components"
  656.         />. Five of the labeled areas are the same as the areas in the
  657.         dialog when it is in a compact form; these areas were
  658.         explained above. The remaining areas are explained below:
  659.  
  660.     <variablelist>
  661.       <title>The extra components in the expanded version of the
  662.       <interface>File Save</interface> dialog</title>
  663.  
  664.       <varlistentry>
  665.         <term>
  666.           <emphasis role="bold">F</emphasis> - The 'relative root'
  667.           selection area.
  668.  
  669.         </term>
  670.         <listitem>
  671.           <para>
  672.             This area allows the user to select the starting
  673.             folder from which to navigate the folder
  674.             hierarchy. The navigation system only allows users to
  675.             select sub-folders of the currently selected 'relative
  676.             root' folder so the root folder selected in area
  677.             <emphasis role="bold">F</emphasis> must contain the
  678.             desired folder as a sub-folder.
  679.           </para>
  680.  
  681.           <para>
  682.             The folders listed in this area include the standard
  683.             folders provided by the system and a number of folders
  684.             added, as bookmark folders, by the user. The standard folders
  685.             provided by the system will vary for different
  686.             machines and system administrators may have disabled
  687.             access to certain areas. By default, the standard
  688.             folders provided include the user's 'Home' folder, the
  689.             user's 'Desktop' folder, a folder pointing to the root
  690.             of the filesystem tree and folders for each of the
  691.             removable storage devices attached to the
  692.             computer. The user's home folder, on GNU and other
  693.             UNIX like systems, this
  694.             folder is usually known as <literal>~</literal> or
  695.             <literal>~user_account_name</literal> where the
  696.             phrase <literal>user_account_name</literal>
  697.             represents the account name used by the current
  698.             user. This folder is often located at
  699.             <filename>/home/user_account_name/</filename> in the
  700.             filesystem. The 'Desktop' folder is the folder which
  701.             holds the files which are displayed in the background
  702.             of the user's window. The 'Filesystem' folder is the
  703.             top of the filesystem tree, which on GNU systems is
  704.             also known as <filename>/</filename>. The list also
  705.             presents peripheral or external devices. Below the
  706.             standard folders, area <emphasis
  707.             role="bold">F</emphasis> has a separator and the
  708.             bookmark folders selected by the user. In <xref
  709.             linkend="fig-file-save-dialog-expanded-components"
  710.             /> the folder <filename>currentWork</filename> is a
  711.             folder named by the user and added to the list of
  712.             bookmark folders. 
  713.           </para>
  714.         </listitem>
  715.           </varlistentry>
  716.  
  717.       <varlistentry>
  718.         <term>
  719.           <emphasis role="bold">G</emphasis> - The folder hierarchy area.
  720.         </term>
  721.         <listitem>
  722.           <para>
  723.             This area displays the folder hierarchy starting from
  724.             the starting folder selected in area <emphasis
  725.             role="bold">F</emphasis> and ending in the current
  726.             folder, the folder whose contents are displayed in
  727.             area <emphasis role="bold">I</emphasis>, while
  728.             displaying all the folders between the two. This area
  729.             changes dynamically as the user changes to new
  730.             folders. In the case shown in <xref
  731.             linkend="fig-file-save-dialog-expanded-components" />,
  732.             the user has selected the 'Home' folder as the
  733.             starting folder in area <emphasis
  734.             role="bold">F</emphasis> and has not navigated to any
  735.             sub-folders.
  736.           </para>
  737.         </listitem>
  738.           </varlistentry>
  739.  
  740.       <varlistentry>
  741.         <term>
  742.           <emphasis role="bold">H</emphasis> - The Folder Creation button.
  743.         </term>
  744.         <listitem>
  745.           <para>
  746.             This button allows the user to create a folder in the
  747.             directory listed in the rightmost part of the file
  748.             component area, area <emphasis
  749.             role="bold">G</emphasis>. When this button is clicked,
  750.             by placing the mouse pointer over the button and
  751.             clicking with the primary mouse button, a new folder
  752.             is added to the list in area <emphasis
  753.             role="bold">I</emphasis> with a temporary name of
  754.             '<filename>Type name of New Folder</filename>'
  755.             pre-selected and therefore ready to be edited into a
  756.             new name.
  757.           </para>
  758.         </listitem>
  759.           </varlistentry>
  760.  
  761.       <varlistentry>
  762.         <term>
  763.           <emphasis role="bold">I</emphasis> - The folder content area.
  764.  
  765.         </term>
  766.         <listitem>
  767.           <para>
  768.             This area displays the contents of the currently
  769.             selected folder which is the rightmost folder shown in
  770.             area <emphasis role="bold">G</emphasis>. 
  771.         
  772.         <warning>
  773.           <para>
  774.             Not all of the sub-folders and files present in
  775.             the folder area are shown.
  776.           </para>
  777.  
  778.           <para>
  779.             Firstly, hidden folders and files, those that
  780.             start with a leading period, are not displayed by
  781.             default. These can be shown by placing the mouse
  782.             pointer over area <emphasis
  783.             role="bold">I</emphasis>, clicking with one of the
  784.             secondary mouse buttons to raise the context menu,
  785.             moving the pointer onto the <guimenuitem>Show
  786.             hidden files</guimenuitem> menu entry, and
  787.             clicking with the primary mouse button. This step
  788.             will ensure that all the folders are displayed.
  789.           </para>
  790.  
  791.           <para>
  792.             Secondly, the filtering rule defined in
  793.                 area <emphasis role="bold">L</emphasis>
  794.                 will limit the files displayed based on the
  795.                 characteristics of these files. By default, a
  796.                 filtering rule is applied which causes only those
  797.                 files present that have an extension commonly used
  798.                 for spreadsheet files. The rule can be changed to
  799.                 display all the files regardless of their
  800.                 extension, except possibly for the hidden files.
  801. <!-- TODO: explain role of mime type in file dislpay filter. ibid  -opening. -->
  802.               </para>
  803.         </warning>
  804.           </para>
  805.         </listitem>
  806.           </varlistentry>
  807.  
  808.       <varlistentry>
  809.         <term>
  810.           <emphasis role="bold">J</emphasis> - The panel
  811.           rearrangement handles.
  812.  
  813.         </term>
  814.         <listitem>
  815.           <para>
  816.             These triple dots indicate that the mouse can be used
  817.             to change the shape and size of the different areas in
  818.             the dialog. These handles can be used by placing the
  819.             mouse pointer above a handle, clicking and holding
  820.             with the primary mouse button, then dragging the
  821.             handle to a new position, and then releasing the mouse
  822.             button.
  823.           </para>
  824.         </listitem>
  825.           </varlistentry>
  826.  
  827.       <varlistentry>
  828.         <term>
  829.           <emphasis role="bold">K</emphasis> - The bookmark
  830.           folder list modification buttons.
  831.  
  832.         </term>
  833.         <listitem>
  834.           <para>
  835.             These buttons will add or remove folders to or from
  836.             the list of bookmark folders in area <emphasis
  837.             role="bold">F</emphasis>. The
  838.             <guibutton>Add</guibutton> button will add the folder
  839.             currently selected in area <emphasis
  840.             role="bold">G</emphasis>. The
  841.             <guibutton>Remove</guibutton> button will remove any
  842.             bookmark folder that is selected in area <emphasis
  843.             role="bold">F</emphasis>.
  844.           </para>
  845.         </listitem>
  846.           </varlistentry>
  847.  
  848.       <varlistentry>
  849.         <term>
  850.           <emphasis role="bold">L</emphasis> - The filter
  851.           definition area.
  852.         </term>
  853.         <listitem>
  854.           <para>
  855.             This area contains a drop down menu with the different
  856.             filters defined by the application. &gnum; currently
  857.             defines two filters. The first filters out all files
  858.             that do not have an extension used by the spreadsheet
  859.             formats supported by gnumeric. The second filter,
  860.             labeled "All files", essentially disables any
  861.             filtering operation, and lists all the files in the
  862.             currently selected folder, except that files starting
  863.             with a leading period are not shown. 
  864.           </para>
  865.         </listitem>
  866.           </varlistentry>
  867.  
  868.  
  869.  
  870.         </variablelist>
  871.  
  872.       </para>
  873.  
  874.       <para>
  875.         The uses of the <interface>File Save</interface> dialog in its
  876.         expanded form is explained below.
  877.       </para>
  878.  
  879.     </sect3>
  880.  
  881.  
  882.  
  883.  
  884.     <sect3 id="sect-file-save-dialog-chdir">
  885.       <title>
  886.         Changing the currently selected folder.
  887.       </title>
  888.  
  889.       <para>
  890.         In order to save a file in a folder other than that provided
  891.         by default, it is necessary to change the default folder. The
  892.         note below explains briefly the notion of folders and the
  893.         procedure further down explains how to change folders.
  894.       </para>
  895.  
  896.       <note>
  897.         <title>Understanding the file organization system.</title>
  898.  
  899.         <para>
  900.       In order to understand how to change folders, it is first
  901.       necessary to understand the system by which documents are
  902.       stored. This system is called the 'filesystem'.
  903.     </para>
  904.  
  905.     <para>
  906.       All documents are stored in a folder. Folders can contain
  907.       files but can also contain other folders. Any folder
  908.       therefore can contain several sub-folders, each of which may
  909.       itself contain several sub-folders; the resulting structure
  910.       is called a nested 'tree' with the original folder being the
  911.       'relative root' of that tree.
  912.         </para>
  913.  
  914.     <para>
  915.       In GNU and UNIX systems, all of the files are stored in
  916.       folders organized in a single, unified filesystem tree with
  917.       a folder named '<filename>/</filename>' at the absolute root
  918.       of the tree. Every file is accessible from this absolute
  919.       root folder and, by default, this folder is provided as the
  920.       choice named <filename>Filesystem</filename> with an icon of
  921.       a disk drive in area <emphasis role="bold">F</emphasis> in
  922.       the <interface>File Save</interface> dialog.
  923.     </para>
  924.  
  925.     <para>
  926.       Navigating the directory tree from the single root folder
  927.       would quickly become burdensome and the <interface>File
  928.       Save</interface> dialog provides several other starting
  929.       points in area <emphasis role="bold">F</emphasis>. These
  930.       will be called, in this documentation, the 'relative root'
  931.       folders since each of these will act as the root of the
  932.       branching structure of sub-folders the relative root folder
  933.       contains. Two relative root folders which are commonly
  934.       provided are the 'Home' and 'Desktop' folders for the
  935.       current user.
  936.     </para>
  937.  
  938.     <para>
  939.       In a complex computer system, the absolute root folder may
  940.       be hidden from the user and only 'relative roots' will be
  941.       present. These should jointly provide some way to access all
  942.       the areas where the user can save files.
  943.     </para>
  944.  
  945.     <para>
  946.       The 'relative roots' are also necessary when several file
  947.       systems are available to the user. This will be the case
  948.       when filesystem on other machines are accessible over a
  949.       network or when &gnum; is running on operating systems whose
  950.       filesystems are not unified, such as the proprietary
  951.       operating systems sold by Microsoft in which each disk drive
  952.       has its own root named, for example,
  953.       <filename>C:\</filename> or <filename>D:\</filename>.
  954.     </para>
  955.       
  956.     <para>
  957.       Additional 'relative root' folders can be added as 'bookmark
  958.       folders' by the users themselves. These bookmark folders can
  959.       be used to access quickly folders which are commonly
  960.       used. The bookmark folders are listed, in area <emphasis
  961.       role="bold">F</emphasis>, under the thin horizontal
  962.       separator line. The creation and deletion of these bookmark
  963.       folders is explained below, in <xref
  964.       linkend="sect-file-save-dialog-bookmarks" />.
  965.     </para>
  966.  
  967.     <para>
  968.       
  969.  
  970.     </para>
  971.       </note>
  972.  
  973.       <para>
  974.         Changing folders involves selecting a 'relative root' folder,
  975.         then navigating into the appropriate sub-folder. When the
  976.         <guibutton>Save</guibutton> button is pressed, the file will be
  977.         saved in the folder listed as the right most button in area
  978.         <emphasis role="bold">G</emphasis> of <xref
  979.         linkend="fig-file-save-dialog-expanded-components" />
  980.         which also means that the file will be saved alongside the
  981.         folders and files listed in area <emphasis
  982.         role="bold">I</emphasis>.
  983.      </para>
  984.  
  985.       <procedure>
  986.         <title>
  987.       The procedure to change the currently selected folder.
  988.     </title>
  989.  
  990.     <para>
  991.       To select a new folder, one of the 'relative root' folders
  992.       which contains the desired folder must first be selected and
  993.       then the hierarchy must be navigated to find the desired
  994.       folder. As explained below, a user can move around the
  995.       hierarchy using as many changes as they need to choose the
  996.       folder in which to save their &gnum; file.
  997.     </para>
  998.  
  999.         <step>
  1000.       <title>
  1001.         Select a 'relative-root' folder in area <emphasis
  1002.         role="bold">F</emphasis>. 
  1003.       </title>
  1004.       <para>
  1005.         The first step in choosing a new folder requires
  1006.         selecting, in area <emphasis role="bold">F</emphasis>, a
  1007.         'relative root' folder which contains the desired
  1008.         folder. The new 'relative root' folder is chosen by placing the
  1009.         mouse pointer over the folder name and double clicking
  1010.         (click twice rapidly without moving the mouse) with the
  1011.         primary mouse button. This will change the leftmost button
  1012.         in  area <emphasis role="bold">G</emphasis> and change the
  1013.         folders and files listed in  area <emphasis
  1014.         role="bold">I</emphasis>.
  1015.       </para>
  1016.     </step>
  1017.  
  1018.         <step>
  1019.       <title>
  1020.         Navigate the filesystem to reach the desired
  1021.         folder using area <emphasis role="bold">I</emphasis>.
  1022.       </title>
  1023.       <para>
  1024.         The next step involves descending the folder tree to reach
  1025.         the desired folder. This requires double clicking the
  1026.         sub-folder of the 'relative root' folder which contains
  1027.         the desired folder and continuing through the whole
  1028.         hierarchy until the desired folder is reached. After each
  1029.         double click, the selected folder is added as the right
  1030.         most button in area <emphasis role="bold">G</emphasis> and
  1031.         the contents of the selected folder are shown in area
  1032.         <emphasis role="bold">I</emphasis>. Once the desired
  1033.         folder is reached, it must be opened in the same way, so
  1034.         that its contents are listed in area <emphasis
  1035.         role="bold">I</emphasis> and the file can then be saved
  1036.         into this folder by clicking on the
  1037.         <guibutton>Save</guibutton> button.
  1038.       </para>
  1039.     </step>
  1040.  
  1041.         <step>
  1042.       <title>
  1043.         Navigating back up the folder tree using area <emphasis
  1044.         role="bold">G</emphasis>. 
  1045.       </title>
  1046.       <para>
  1047.         If the sub-folder selected in area <emphasis
  1048.         role="bold">I</emphasis> does not contain the branch of
  1049.         the folder tree leading to the desired folder, the buttons
  1050.         in area <emphasis role="bold">G</emphasis> can be used to
  1051.         jump further up the folder tree but only as far as the
  1052.         'relative root' folder selected in area <emphasis
  1053.         role="bold">F</emphasis>. Area <emphasis
  1054.         role="bold">G</emphasis> provides a list of buttons with
  1055.         the names of all the folders between the 'relative root'
  1056.         listed in area <emphasis role="bold">F</emphasis> and the
  1057.         currently selected folder. By clicking on one of these
  1058.         buttons, that is by placing the mouse pointer over the
  1059.         button and clicking with the primary mouse button, the
  1060.         folder listed on the button will be opened in area
  1061.         <emphasis role="bold">I</emphasis> so that the selection
  1062.         process can restart from this branch.
  1063.       </para>
  1064.     </step>
  1065.  
  1066.       </procedure>
  1067.  
  1068.       <para>
  1069.         The process of exploration of the folder tree can continue as
  1070.         long as the user wishes. If the user desires it is also
  1071.         possible to create new folders as is explained next. 
  1072.       </para>
  1073.  
  1074.     </sect3>
  1075.  
  1076.  
  1077.     <sect3 id="sect-file-save-dialog-mkdir">
  1078.       <title>
  1079.         Adding a folder.
  1080.       </title>
  1081.  
  1082.       <para>
  1083.         Often the user wishes to save the &gnum; workbook by creating
  1084.         a file in a folder which does not yet exist. A new folder can
  1085.         be added to the folder tree by clicking on the
  1086.         <guibutton>Create Folder</guibutton> button, which is labeled
  1087.         as area <emphasis role="bold">H</emphasis> of <xref
  1088.         linkend="fig-file-save-dialog-expanded-components"
  1089.         />. The button can be clicked by placing the mouse pointer
  1090.         over the button and pressing the primary mouse button.
  1091.       </para>
  1092.  
  1093.       <para>
  1094.         When the <guibutton>Create Folder</guibutton> button is
  1095.         pressed, a folder will be added at the top of the list in area
  1096.         <emphasis role="bold">I</emphasis>, with its name,
  1097.         <filename>Type name of new folder</filename> already selected
  1098.         so that the user can simply start typing to give the folder a
  1099.         desired name. Once the name has been entered on the keyboard,
  1100.         typing the <keysym>Return</keysym> key (or the
  1101.         <keysym>Enter</keysym> key, depending on the keyboard) will
  1102.         change the folder name and open that folder. Area <emphasis
  1103.         role="bold">I</emphasis> will therefore be empty since the
  1104.         newly created folder has no contents.
  1105.       </para>
  1106.  
  1107.       <warning>
  1108.         <para>
  1109.       There is no way to delete folders once they have been
  1110.       created, just as there is no way for &gnum; to delete files
  1111.       it has created. Folders created by mistake must be deleted
  1112.       using a file browser such as
  1113.       <application>Nautilus</application> or using command line
  1114.       programs such as <application>rm</application>.
  1115.     </para>
  1116.       </warning>
  1117.  
  1118.     </sect3>
  1119.  
  1120.  
  1121.     <!-- Keep in sync with similar section in file-open-dialog. -->
  1122.     <sect3 id="sect-file-save-dialog-bookmarks">
  1123.       <title>
  1124.         Changing the list of bookmark folders.
  1125.       </title>
  1126.  
  1127.       <para>
  1128.         The list of 'relative root' folders shown in area <emphasis
  1129.         role="bold">F</emphasis> of <xref
  1130.         linkend="fig-file-save-dialog-expanded-components" /> may
  1131.         contain 'relative root' folders selected by the user. These
  1132.         folders are called 'bookmark folders' and are listed in area
  1133.         <emphasis role="bold">F</emphasis> below a thin horizontal
  1134.         separator line. For example, <xref
  1135.         linkend="fig-file-save-dialog-expanded-components" /> contains
  1136.         a folder named <filename>currentWork</filename> which is a
  1137.         bookmark folder selected by the user.
  1138.       </para>
  1139.  
  1140.       <para>
  1141.         These bookmark folders can be added in two ways. A folder
  1142.         which is selected in area <emphasis role="bold">I</emphasis>
  1143.         can be added as a bookmark by clicking on the
  1144.         <guibutton>Add</guibutton> button in area <emphasis
  1145.         role="bold">K</emphasis>.
  1146.       </para>
  1147.  
  1148.       <para>
  1149.     Alternatively, the folder can be dragged from area <emphasis
  1150.         role="bold">I</emphasis> into area <emphasis
  1151.         role="bold">K</emphasis>. The folder can be dragged by placing
  1152.         the mouse pointer over the folder name in area <emphasis
  1153.         role="bold">I</emphasis>, clicking and holding the primary
  1154.         mouse button, moving the mouse pointer to area <emphasis
  1155.         role="bold">F</emphasis> and releasing the mouse button. As
  1156.         the mouse pointer is moved from area <emphasis
  1157.         role="bold">I</emphasis> to area <emphasis
  1158.         role="bold">F</emphasis>, a small icon of the folder will move
  1159.         with the mouse pointer.
  1160.       </para>
  1161.  
  1162.       <para>
  1163.         Any bookmark folder can also be removed from the 'relative
  1164.         root' folders presented in area <emphasis
  1165.         role="bold">F</emphasis> (or in the drop down list labeled
  1166.         <emphasis role="bold">B</emphasis>). A bookmark folder can be
  1167.         removed by clicking on the folder name in area <emphasis
  1168.         role="bold">F</emphasis> and then clicking on the
  1169.         <guibutton>Remove</guibutton> in area <emphasis
  1170.         role="bold">K</emphasis>.
  1171.       </para>
  1172.  
  1173.  
  1174.     </sect3>
  1175.  
  1176.  
  1177.   </sect2>
  1178.  
  1179.  
  1180.  
  1181.  
  1182.  
  1183.  
  1184.  
  1185.   <!-- Formats for saving files *** keep // to sect in files-opening.xml  -->
  1186.  
  1187.   <sect2 id="file-format-save-formats">
  1188.     <title>The file formats which Gnumeric can write.</title>
  1189.  
  1190.     <para>
  1191.       &gnum; can write files in several formats used by other
  1192.       programs. The details of these formats are provided in <xref
  1193.       linkend="sect-file-formats"/> and the name of each file type in
  1194.       the table below skips to the appropriate section of <xref
  1195.       linkend="sect-file-formats"/>. The creation of files which
  1196.       consist of structured text is described in <xref
  1197.       linkend="sect-file-textExport" />. The creation of Postscript
  1198.       and Portable Document Format (PDF) files is done through the
  1199.       printing mechanism and is described in <xref
  1200.       linkend="chapter-printing" />.&gnum; can also export text data
  1201.       or HTML and XHTML tables through the clipboard mechanism, as is
  1202.       explained in <xref linkend="sect-movecopy-xclipboard"/>.
  1203.  
  1204. <!-- TODO: add link to other data ouput: e.g. direct database connect. -->
  1205.     </para> 
  1206.  
  1207.     <note>
  1208.       <para>
  1209.         Most of these formats are provided by plugins, which are
  1210.         independent, configurable modules. If a format described below
  1211.         does not appear in the <interface>File Save</interface>
  1212.         dialog, this may be because the appropriate plugin has not
  1213.         been configured or started. This can be verified by examining
  1214.         the list of plugins which are currently running in the
  1215.         <interface>Plugin Manager</interface> dialog.
  1216.       </para>
  1217.  
  1218.       <para>
  1219.         The <interface>Plugin Manager</interface> dialog lists the
  1220.         plugins which are currently in use and provides a way to start
  1221.         plugins which are currently disabled. The <interface>Plugin
  1222.         Manager</interface> can be started by selecting, in the
  1223.         <guimenu>Tools</guimenu> menu, the
  1224.         <guimenuitem>Plug-ins...</guimenuitem> menu item; see <xref
  1225.         linkend="sect-configuration-plugins" /> for more information.
  1226.       </para>
  1227.     </note>
  1228.  
  1229.  
  1230.  
  1231. <!--    TABLE    TABLE    TABLE    TABLE    TABLE    TABLE    -->
  1232. <table frame='all'><title>The file formats which &gnum; can create.</title>
  1233. <tgroup cols='2' align='left' colsep='1' rowsep='1'>
  1234.        
  1235.  
  1236. <thead>
  1237. <row>
  1238.   <entry align="left">Format</entry>
  1239.   <entry align="left">Extension</entry>
  1240. </row>
  1241. </thead>
  1242. <tbody>
  1243. <row>
  1244.   <entry><link linkend="file-format-gnumeric">Gnumeric</link></entry>
  1245.   <entry><literal>.gnumeric</literal> / <literal>.gnm</literal></entry> 
  1246. </row>
  1247. <row>
  1248.   <entry><link linkend="file-format-csv">Comma Separated Values</link></entry>
  1249.   <entry><literal>.csv</literal></entry> 
  1250. </row>
  1251. <row>
  1252.   <entry><link linkend="file-format-dif">Data Interchange Format</link></entry>
  1253.   <entry><literal>.dif</literal></entry> 
  1254. </row>
  1255. <row>
  1256.   <entry><link linkend="file-format-html">HTML</link></entry>
  1257.   <entry><literal>.html</literal> / <literal>.htm</literal></entry> 
  1258. </row>
  1259. <row>
  1260.   <entry><link linkend="file-format-latex">LaTeX</link></entry>
  1261.   <entry><literal>.tex</literal></entry> 
  1262. </row>
  1263. <row>
  1264.   <entry><link linkend="file-format-excel">Microsoft Excel</link></entry>
  1265.   <entry><literal>.xls</literal></entry> 
  1266. </row>
  1267. <row>
  1268.   <entry><link linkend="file-format-ooo">OpenOffice.Org / StarOffice</link></entry>
  1269.   <entry><literal>.sxc</literal></entry> 
  1270. </row>
  1271. <row>
  1272.   <entry><link linkend="file-format-ps">Postscript</link></entry>
  1273.   <entry><literal>.ps</literal> / <literal>.eps</literal></entry> 
  1274. </row>
  1275. <row>
  1276.   <entry><link linkend="file-format-pdf">PDF</link></entry>
  1277.   <entry><literal>.pdf</literal></entry> 
  1278. </row>
  1279. <row>
  1280.   <entry><link linkend="file-format-tab">Tab Separated Values</link></entry>
  1281.   <entry><literal>.tsv</literal> / <literal>.tab</literal></entry> 
  1282. </row>
  1283. <row>
  1284.   <entry><link linkend="file-format-text">Text Formats</link></entry>
  1285.   <entry><literal>.txt</literal> / <literal>.text</literal></entry> 
  1286. </row>
  1287. <row>
  1288.   <entry><link linkend="file-format-troff">TROFF</link></entry>
  1289.   <entry><literal>.me</literal></entry> 
  1290. </row>
  1291. <row>
  1292.   <entry><link linkend="file-format-xhtml">XHTML</link></entry>
  1293.   <entry><literal>.xhtml</literal> / <literal>.html</literal></entry> 
  1294. </row>
  1295. </tbody>
  1296. </tgroup>
  1297. </table>
  1298. <!--    TABLE    TABLE    TABLE    TABLE    TABLE    TABLE    -->
  1299.  
  1300.  
  1301.   </sect2>
  1302.  
  1303.  
  1304. </sect1>
  1305.  
  1306.  
  1307.