<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY GwenRename "<application>GwenRename 1.1-beta5</application>">
  <!ENTITY kappname "GwenRename"><!-- Do *not* replace kappname-->
  <!ENTITY package "playground-utils"><!-- kdebase, kdeadmin, etc -->
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE"><!-- change language only here -->
]>

<book lang="&language;">

<bookinfo>
<title>The GwenRename Handbook</title>

<authorgroup>
<author>
<firstname></firstname>
<othername></othername>
<surname>Spiros Georgaras</surname>
<affiliation>
<address><email>sng@hellug.gr</email></address>
</affiliation>
</author>
</authorgroup>

<copyright>
<year>2003</year>
<year>2009</year>
<holder>Spiros Georgaras</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>2009-07-05</date>
<releaseinfo>0.8</releaseinfo>

<abstract>
<para>
GwenRename is a batch renaming tool for <ulink url="http://gwenview.sourceforge.net/">GwenView</ulink>, <ulink url="http://dolphin.kde.org/">Dolphin</ulink> and  <ulink url="http://www.konqueror.org/">Konqueror</ulink>.
</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>GwenRename</keyword>
<keyword>gwenrename</keyword>
<keyword>GwenView</keyword>
<keyword>gwenview</keyword>
<keyword>rename</keyword>
</keywordset>

</bookinfo>

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

<para>
GwenRename is a batch renaming tool. It was created as an external tool for <ulink url="http://gwenview.sourceforge.net/">GwenView</ulink>, the image viewer for KDE, but can also be used from <ulink url="http://dolphin.kde.org/">Dolphin</ulink> and <ulink url="http://www.konqueror.org/">Konqueror</ulink>. As that, the files/folders to be renamed are passed to it as command line parameters.
</para>
<para>

</para>
<para>
The main goal is to have a batch renaming tool that's easy and light enough for every day use. If you are looking for a more compound and featured renaming tool, you should have a look at Dominik Seichter's <ulink url="http://www.krename.net">KRename</ulink>.
</para>


<sect1 id="GwenRename-how-it-works">
<title>How does it work?</title>
<para>
GwenRename has an easy to use interface (take a look at the <link linkend="main-window">main window</link>), where the user can adjust the renaming parameters.
</para>

<para>GwenRename accepts a number of command line parameters (the items to be renamed), and creates a new filename for each file passed to it, using the following scheme:</para>
<para><option>&lt;prefix&gt;&lt;name&gt;&lt;number&gt;&lt;suffix&gt;.&lt;extension&gt;</option></para>
<para>Each of these fields is user configurable.</para>

<para>
Special attention has been given so that there is no chance to overwrite or delete already existing files. All comparisons between existing filenames and filenames to be used for renaming are case in-sensitive, so it can be used even on a vfat filesystem.
</para>
</sect1>
</chapter>


<chapter id="using-GwenRename">
<title>Using GwenRename</title>

<para>
GwenRename has two modes of operation: file mode and folder mode.


<itemizedlist>
<listitem>
<para>file mode</para>
<para>In this mode only files can be selected for renaming</para></listitem>
<listitem>
<para>folder mode</para>
<para>In this mode only folders can be selected for renaming</para></listitem>
</itemizedlist>

</para>
<para>These two modes cannot be mixed (i.e. you can not rename files and folders at the same renaming session).</para>


<sect1 id="GwenRename-launch">
<title>Launching GwenRename</title>
<para>The program can be launched using any of the following ways:</para>

<itemizedlist>
<listitem><para><userinput>gwenrename <option>[list of files]</option></userinput> (refer to <link linkend="file-mode">File mode</link>)</para></listitem>
<listitem><para><userinput>gwenrename <option>[list of folders]</option></userinput> (refer to <link linkend="folder-mode">Folder mode</link>)</para></listitem>
<listitem><para><userinput>gwenrename <option>[folder]</option></userinput> (refer to <link linkend="mode-selection">Mode selection</link>)</para></listitem>
<listitem><para><userinput>gwenrename</userinput> (refer to <link linkend="input-folder-selection">Input folder selection</link>)</para></listitem>
</itemizedlist>

<para>Depending on the way the program was launched, one of the following will occur:</para>

<sect2 id="file-mode">
<title>File mode</title>
<para>The <link linkend="main-window">main window</link> will be displayed, making the selected files available for renaming.</para>
</sect2>

<sect2 id="folder-mode">
<title>Folder mode</title>
<para>The <link linkend="main-window">main window</link> will be displayed, making the selected folders available for renaming.</para>
</sect2>

<sect2 id="mode-selection">
<title>Mode selection</title>
<para>Passing a single folder as a parameter, will make GwenRename display the Mode Selection window, shown bellow.</para>

<para>
<inlinemediaobject>
<imageobject>
<imagedata align="center" fileref="mode.png" format="PNG" />
</imageobject>
</inlinemediaobject>
</para>

<para>The user can now either click on:</para>

<itemizedlist>
<listitem><para><guibutton>Rename folder</guibutton> to rename the selected folder</para></listitem>
</itemizedlist>


<para>or</para>

<itemizedlist>
<listitem><para><guibutton>Rename files</guibutton> to rename the files contained in it</para></listitem>
</itemizedlist>


</sect2>

<sect2 id="input-folder-selection">
<title>Input folder selection</title>
<para>When no parameters are passed to the program, the folder selection dialog will be displayed.</para>

<para>
<inlinemediaobject>
<imageobject>
<imagedata align="center" fileref="inputdir.png" format="PNG" />
</imageobject>
</inlinemediaobject>
</para>

<para>The contents of the selected folder will be displayed in GwenRename list, so that the user can select the files/folders to rename.</para>
</sect2>

<sect2 id="launch-konqueror">
<title>Launching from Konqueror</title>
<para>Select desired files/folders, right click and select <guimenu>Actions</guimenu> / <guimenu>Rename with GwenRename</guimenu></para>
</sect2>

<sect2 id="launch-gwenview">
<title>Launching from GwenView</title>
<para>Select desired files/folders, right click and select <guimenu>External Tools</guimenu> / <guimenu>Rename with GwenRename</guimenu></para>
</sect2>

<sect2 id="launch-command-line">
<title>Launching from the Command Line</title>

<itemizedlist>
<listitem><para>To rename all jpg files in folder /path/to/files, type</para><screen id="sc-cmd1"><userinput>gwenrename <option>/path/to/files/*.jpg</option></userinput></screen></listitem>
<listitem><para>To rename folders fold-1 and fold-4 in folder /path/to/files, type</para><screen id="sc-cmd2"><userinput>gwenrename <option>/path/to/files/fold-1 /path/to/files/fold-4</option></userinput></screen></listitem>
<listitem><para>To select either to rename my-files folder in /path/to/files or files/folders under /path/to/files/my-files , type</para><screen id="sc-cmd3"><userinput>gwenrename <option>/path/to/files/my-files</option></userinput></screen></listitem>
</itemizedlist>
</sect2>

</sect1>

</chapter>



<chapter id="main-window">
<title>GwenRename Main Window</title>

<screenshot>
<screeninfo>GwenRename Main Window</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="main-window.png" format="PNG" />
</imageobject>
</mediaobject>
</screenshot>

<para>GwenRename Main Window is divided in two parts</para>

<itemizedlist>
<listitem><para>The ListView part</para>
<para>It displays the items contained in the target folder,  and provides the ability to add or remove items to the <link linkend="items-management">Items List</link>.</para></listitem>
<listitem><para>The Renaming options adjustment part</para>
<para>It provides all necessary options to adjust the format of the new filename for each item in the <link linkend="items-management">Items List</link>.</para></listitem>
</itemizedlist>


<sect1 id="listview">
<title>The ListView part</title>

<para id="state-icon">Items to be renamed (members of the <link linkend="items-management">Items List</link>) are denoted by the existence of the Sate Icon, an icon present in the first column of the ListView, which displays the expected renaming result, given the current <link linkend="options">Renaming options</link>, as follows:</para>
<note><title></title>
<para>
<inlineequation>
<inlinemediaobject>
<imageobject>
<imagedata fileref="hi16-app-gwenrename.png"/>
</imageobject>
</inlinemediaobject>
</inlineequation> The item is expected to be renamed successfully
</para>

<para>
<inlineequation>
<inlinemediaobject>
<imageobject>
<imagedata fileref="gray16-app-gwenrename.png"/>
</imageobject>
</inlinemediaobject>
</inlineequation> The item will not be renamed, because the old and new filename is the same
</para>

<para>
<inlineequation>
<inlinemediaobject>
<imageobject>
<imagedata fileref="button_cancel.png"/>
</imageobject>
</inlinemediaobject>
</inlineequation> The item will not be renamed, because that would overwrite an existing item. In fact, renaming is disabled until this condition is resolved (by readjusting the <link linkend="options">Renaming options</link>).
This icon may vary as it depends on the active icon theme. 
</para>
</note>




<sect2 id="items-management">
<title>Managing items in GwenRename</title>

<para>
GwenRename works with two different sets of items (files or folders).
</para>


<itemizedlist>
<listitem>
<para>The Items List</para>
<para>These are the items (files or folders) to be renamed. They are marked by a state icon.</para>
<para>The Items List can be formed by passing the items' names as command line parameters to GwenRename, by double clicking an item in the ListView, or by using the ListView context menu.</para>
</listitem>
<listitem>
<para>The Selection List</para>
<para>These are the selected items in the ListView. They can be added or removed from the Items List, used to create a new Items List, etc.</para>
<para>A selection can be formed as usual (click to select a single item, Shift-Click to select items in a row, Cntrl-Click to add a single item to the selection), or by using the ListView context menu.</para>

</listitem>
</itemizedlist>

<sect3 id="context-menu"><title>Context menu</title>
<para>By right clicking on the Items List, the context menu is available to the user. When <guimenu>Show all items</guimenu> is not checked, a reduced version of the menu is displayed.</para>
<mediaobject>
<imageobject>
<imagedata fileref="contextmenu.png" format="PNG" />
</imageobject>
</mediaobject>

<para>The functions available through the context menu are:</para>

<sect4 id="lm3"><title>List management</title>
<para>These menu entries modify the current <link linkend="items-management">Items List</link></para>
<itemizedlist>
<listitem>
<para><guimenu>Add to list</guimenu></para>
<para>Adds the selectded items (items in the Selection List) to the Items List</para>
</listitem>
<listitem>
<para><guimenu>Remove from list</guimenu></para>
<para>Removes the selectded items (items in the Selection List) from the Items List</para>
</listitem>
<listitem>
<para><guimenu>Invert list</guimenu></para>
<para>Removes from the Items List all items that were contained within, and inserts all items that were not.</para>
<para>If the target folder contains files and sub-folders, a type inversion accrues when all items of one type are selected. For example, when all folders are already in the Items List, they will be removed after its execution, and all files will be inserted to the it.</para>
</listitem>
<listitem>
<para><guimenu>Create list from selection</guimenu></para>
<para>Replaces the Items List with the selected items (items in the Selection List)</para>
</listitem>
</itemizedlist>

</sect4>
<sect4 id="sel3"><title>Selection management</title>
<para>These menu entries modify the current <link linkend="items-management">Selection List</link></para>
<itemizedlist>
<listitem>
<para><guimenu>All items</guimenu></para>
<para>Selects all items</para>
</listitem>
<listitem>
<para><guimenu>All items of selected type</guimenu></para>
<para>Selects all items of selected type, that is all files or all folders</para>
</listitem>
<listitem>
<para><guimenu>Invert current selection</guimenu></para>
<para>Selects all items that were not selected previously, and deselects all items that were</para>
</listitem>
<listitem>
<para><guimenu>Create selection from list</guimenu></para>
<para>Selects all items contained in the Items List</para>
</listitem>
<listitem>
<para><guimenu>Items containing a string</guimenu></para>
<para>Selects items based on a search string. It uses the <ulink url="search-window.html">Items Selection Window</ulink> </para>
</listitem>
</itemizedlist>

</sect4>
<sect4 id="help3"><title>Help</title>
<itemizedlist>
<listitem>
<para><guimenu>Show help</guimenu></para>
</listitem>
</itemizedlist>
</sect4>

</sect3>
</sect2>
</sect1>


<sect1 id="options">
<title>Renaming options</title>
<para></para>

<sect2 id="option-name">
<title>Name</title>
<para>The user can select between using the original filename or defining a new one.</para>

<para> When the original filename is used, it can be converted to lowercase or uppercase. In addition, the first letter of the filename or every "starting" letter can be capitalized (in this case the filename is first converted to lowercase). When none of the above is selected, the original filename is used unmodified.</para>

<para>"Starting" letters are: the first letter and every letter which follows a white space.</para>
</sect2>

<sect2 id="option-prefix-suffix">
<title>Prefix &amp; Suffix</title>
<para>User defined preffix and suffix using <link linkend="time-stamping-window">Time-stamping</link>.</para>
</sect2>


<sect2 id="option-misc">
<title>Miscellaneous</title>
<para>These are options that could not be grouped anywhere else.</para>


<sect3 id="option-numeric">
<title>Use numeric sorting</title>
<para>When this option is enabled, the original names are sorted taking into account their numeric value (when possible).</para>
<para>The following table demonstrates this function, using GwenRename's default profile.</para>

<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry><para>Original name</para><para>(Normal sorting)</para></entry>
<entry><para>Original name</para><para>(Numeric sorting)</para></entry>
<entry><para>New name</para><para>(Both cases)</para></entry>
</row>
</thead>
<tbody>
<row>
<entry>1.jpg</entry>
<entry>1.jpg</entry>
<entry>001.jpg</entry>
</row>
<row>
<entry>10.jpg</entry>
<entry>2.jpg</entry>
<entry>002.jpg</entry>
</row>
<row>
<entry>2.jpg</entry>
<entry>3.jpg</entry>
<entry>003.jpg</entry>
</row>
<row>
<entry>3.jpg</entry>
<entry>4.jpg</entry>
<entry>004.jpg</entry>
</row>
<row>
<entry>4.jpg</entry>
<entry>5.jpg</entry>
<entry>005.jpg</entry>
</row>
<row>
<entry>5.jpg</entry>
<entry>6.jpg</entry>
<entry>006.jpg</entry>
</row>
<row>
<entry>6.jpg</entry>
<entry>7.jpg</entry>
<entry>007.jpg</entry>
</row>
<row>
<entry>7.jpg</entry>
<entry>8.jpg</entry>
<entry>008.jpg</entry>
</row>
<row>
<entry>8.jpg</entry>
<entry>9.jpg</entry>
<entry>009.jpg</entry>
</row>
<row>
<entry>9.jpg</entry>
<entry>10.jpg</entry>
<entry>010.jpg</entry>
</row>
</tbody>
</tgroup>
</informaltable>

<para>It's clear from this table that the new name assigned to each of the input files, depends on whether this function is enabled (and can successfully be applied) or not.</para>

</sect3>

<sect3 id="option-shuffle">
<title>Shuffle folders</title>
<para>When in folder mode, the new name assigned to each of the input files can be shuffled. This is a requested feature.</para>
</sect3>
</sect2>


<sect2 id="option-space">
<title>Space manipulation</title>
<para>In this section spaces existing in the new name can be converted to underline or dash characters.</para>
<para>For convenience, the reverse function is also available.</para>
</sect2>

<sect2 id="option-counter">
<title>Counter</title>
<para>The counter used to create the series of new filenames. The starting value, the step, and the number of digits to be used are user defined.</para>

<sect3 id="option-counter-digits">
<title>Same number of digits</title>
<para>The counter will produce zero padded numbers, in such a way that all the numbers in the series have the same number of digits. This means that the resulting numbers may have more digits than the user defined.</para>
</sect3>

<sect3 id="option-counter-relaxed">
<title>Use 'relaxed' numbering</title>
<para>When this option is enabled, the program will find the files that match the renaming cretiria but are not selected for renaming, and adjust the starting value of the counter so that the resulting filenames will follow the last existing file. This means that the starting value of the counter may be different than the one defined by the user.</para>
</sect3>
</sect2>

<sect2 id="option-extension">
<title>Extension</title>
<para>The user can either use the original file extension (converted to lowercase or uppercase), or insert a new file extension.</para>

<para>Note: The extension field is available in file mode only.</para>

<sect3 id="option-extension-compound">
<title>Use compound extensions</title>
<para>GwenRename treats the characters that follow the last dot character of the file name as an extension. This may not always be desirable, and that's why compound extensions have been introduced to GwenRename.</para>

<para>A compound extension is an extension which contains at least one dot character. For example "tar.gz" is a compound extension.</para>

<para>Compounds extensions used by the program can easily be managed (created, edited and deleted) using the relevant icons.</para>
</sect3>

<!---->
</sect2>

<sect2 id="option-profiles">
<title>Profiles</title>
<para>As of version 0.9.3, GwenRename supports profiles.</para>

<sect3 id="option-profiles-what-is-it">
<title>What is a profile?</title>
<para>A profile is a set of data that describes all the renaming options of GwenRename, that will be used with a special set of files (e.g. images from a digital camera or images downloaded from the net). A profile can be saved and retrieved at any time, renamed (and deleted), used as is or become a base setting for a new profile etc.</para>
</sect3>



<sect3 id="option-profiles-how-it-works">
<title>How does it work?</title>
<para>GwenRename comes with a predefined profile (called "GwenRename") which cannot be renamed or deleted. This is also the default profile (the profile that's loaded at program start-up). From then on the user can define his own profiles, name, rename and delete them at will, and set a different default profile.</para>

<para>Changing a parameter (or more) of a given profile does not affect the profile itself, until the "save" button is clicked. This is also true for a new profile. If another profile is loaded before the "save" button is clicked, the modifications are lost.</para>
</sect3>
</sect2>

</sect1>

<sect1 id="lower-resolution-screen">

<title>Working with lower resolution screens</title>

<para>Having all the features of the program presented on the main window is handy indeed, but it does have a disadvantage; the main window may become too big, even bigger than the screen size if one uses a low resolution screen.</para>

<para>This is the case with GwenRename and screen heights less than 800px.</para>

<para>In order to deal with this problem, the option's layout of the main window has been separated to three rows and a ON/OFF switches have been added to each row. This way each row can be switched off, leaving more space for the files list (higher screen resolution) or permitting smaller main window height (lower screen resolution).</para>

<screenshot>
<screeninfo>Main Window in lower resolution screen</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="main-window-low.png" format="PNG" />
</imageobject>
</mediaobject>
</screenshot>

<para>In lower resolution screens (height less than 800px), the second row will be switched off and the main window height will be reduced (as seen in the above image) so that hopefully the program will fit the screen. Furthermore, the height of the window can be reduced even more - using the mouse.</para>

<para>At any time, one of the three rows will be switched off, so that the overall window height remains the same. For example, when the <guimenu>Miscellaneous / Counter</guimenu> widgets are switched back on, the <guimenu>Extension / Profiles</guimenu> widgets will be automatically switched off.</para>

</sect1>

</chapter>


<chapter id="time-stamping-window">
<title>Time-stamping Window</title>

<screenshot>
<screeninfo>Time-stamping Window</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="timestamp-window.png" format="PNG" />
</imageobject>
</mediaobject>
</screenshot>

<para>As of version 0.9 both the prefix and suffix fields of the GwenRename main window can be used to insert file's time-stamping info to the new filename. A valid time-stamping format for these fields follows the scheme:</para>

<para>&lt;prefix&gt;:&lt;command&gt;:&lt;suffix&gt;</para>

<para>where:</para>
<itemizedlist>
<listitem>
<para>prefix: the field's prefix (normal text)</para></listitem>
<listitem>
<para>command: file's timestamping code. It must be enclosed in ":"</para></listitem>
<listitem>
<para>suffix: the field's suffix (normal text)</para></listitem>
</itemizedlist>
<para>The command field can be inserted (at the cursor possition) using the time-stamping window of GwenRename, by clicking the "clock" button, next to the prefix/suffix field. It provides the ability to choose the date type (creation, last modified, last read) and the actual date format, using predefined or user specified formats.</para>
<para>As of version 0.9.1, file's timestamping supports Exif data. The Exif fields that can be inserted are: the creation date, the last modified date and the last read date.</para>
<para>When Exif data are requested but not available (no Exif data in the file), the coresponding time-stamping info is used. e.g if the Exif creation date is requested but not available, the file's creation date, as reported by the filesystem, is used.</para>
</chapter>

<chapter id="search-window">
<title>Items Selection Window</title>

<screenshot>
<screeninfo>Items Selection Window</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="search.png" format="PNG" />
</imageobject>
</mediaobject>
</screenshot>

<para>This window manages the current <link linkend="items-management">Selection List</link>, by searching for a user defined string, and adding or removing the matching items from it.</para>
<para>Available options are:</para>

<itemizedlist>
<listitem>
<para><guimenu>Case sensitive search</guimenu></para></listitem>
<listitem>
<para><guimenu>Invert selection in item list</guimenu></para>
<para>If checked, items not matching the search string will be selected.</para></listitem>
<listitem>
<para><guimenu>Add to current selection</guimenu></para>
<para>If checked, items matching the search string will added to the current selection. If <guimenu>Invert selection in item list</guimenu> is checked, items matching the search string will removed from the current selection.</para></listitem>
<listitem>
<para><guimenu>Regular expression</guimenu></para>
<para>The search string is a regular expression. It can be edited in <ulink url="help:/KRegExpEditor/index.html">KRegExp</ulink>, when available.</para></listitem>
</itemizedlist>


</chapter>


<chapter id="credits">

<title>Credits and License</title>

<para>
&GwenRename;
</para>
<para>
Program copyright 2003, 2009 Spiros Georgaras <email>sng@hellug.gr</email>
</para>
<para>
Special thanks to:
<itemizedlist>
<listitem><para>Aurelien Gateau</para></listitem>
<listitem><para>Jan Schubert</para></listitem>
<listitem><para>Charles Barcza</para></listitem>
<listitem><para>Sidlovsky Yaroslav</para></listitem>
<listitem><para>Gerardo Bueno</para></listitem>
<listitem><para>Gunther Zilz</para></listitem>
<listitem><para>John Bee</para></listitem>
</itemizedlist>
</para>

<para>
Documentation copyright 2009 Spiros Georgaras <email>sng@hellug.gr</email>
</para>


&underFDL;               <!-- FDL: do not remove -->

&underGPL;        	 <!-- GPL License -->

</chapter>



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

<sect1 id="getting-GwenRename">
<title>How to obtain GwenRename</title>

<!-- This first entity contains boiler plate for applications that are
part of KDE CVS.  You should remove it if you are releasing your
application --> 

<para>
GwenRename can be found at The GwenRename <ulink url="http://members.hellug.gr/sng/gwenrename/download.html">download page</ulink>, and at its <ulink
url="http://www.kde-apps.org/content/show.php?content=11844">KDE apps</ulink> page.
</para>
<para>
You can find a list of changes at GwenRename page at <ulink
url="http://www.kde-apps.org/content/show.php?content=11844">KDE apps</ulink>.
</para>
</sect1>

<sect1 id="requirements">
<title>Requirements</title>

<para>
In order to successfully use GwenRename, you need &kde; 4.x.
</para>

</sect1>

<sect1 id="compilation">
<title>Compilation and Installation</title>

&install.compile.documentation;

</sect1>

</appendix>

&documentation.index;
</book>

