doc/docbook/GuideEditorsConfig.xml

   1 <?xml version="1.0" encoding="utf-8"?>\r
   2 <section id="GuideEditorsConfig">\r
   3   <title id="titleGuideEditorsConfig">External Editor Configuration</title>\r
   4   <para />\r
   5   <section id="EditorsConfigurationDialog">\r
   6     <title>Editor Configuration Dialog</title>\r
   7     <para>\r
   8       This dialog allows user to add new editors or modify the system ones. It is available in the menu\r
   9       <menuchoice>\r
  10         <guimenu>Edit</guimenu>\r
  11         <guimenuitem>Preferences</guimenuitem>\r
  12         <guimenuitem>Configure Editors</guimenuitem>\r
  13       </menuchoice>\r
  14       .\r
  15     </para>\r
  16     <para>\r
  17       The Editors dialog shows list of all relevant editors i.e. all installed desktop files that are designated either:\r
  18       <itemizedlist spacing="compact">\r
  19         >\r
  20         <listitem>\r
  21           <literal>Categories=Graphics</literal>\r
  22         </listitem>\r
  23         <listitem>\r
  24           <literal>Categories=X-Geeqie</literal>\r
  25         </listitem>\r
  26       </itemizedlist>\r
  27       <para />\r
  28       The list has the following columns:\r
  29     </para>\r
  30     <variablelist spacing="compact">\r
  31       <varlistentry>\r
  32         <term>\r
  33           <guilabel>Name</guilabel>\r
  34         </term>\r
  35         <listitem>\r
  36           <para>Editor name as specified in desktop file, and is the name displayed in menus.</para>\r
  37         </listitem>\r
  38       </varlistentry>\r
  39       <varlistentry>\r
  40         <term>\r
  41           <guilabel>Hidden</guilabel>\r
  42         </term>\r
  43         <listitem>\r
  44           An editor can be\r
  45           <emphasis>Hidden</emphasis>\r
  46           for one of these reasons:\r
  47           <itemizedlist>\r
  48             <listitem>\r
  49               the desktop file contains\r
  50               <literal>Hidden=TRUE</literal>\r
  51               or\r
  52               <literal>NoDisplay=TRUE</literal>\r
  53             </listitem>\r
  54             <listitem>\r
  55               <literal>TryExec</literal>\r
  56               binary was not found\r
  57             </listitem>\r
  58             <listitem>\r
  59               <literal>MimeType</literal>\r
  60               list does not contain images\r
  61             </listitem>\r
  62             <listitem>\r
  63               <literal>MimeType</literal>\r
  64               list is empty and\r
  65               <literal>Categories</literal>\r
  66               does not contain\r
  67               <literal>X-Geeqie</literal>\r
  68             </listitem>\r
  69           </itemizedlist>\r
  70         </listitem>\r
  71       </varlistentry>\r
  72     </variablelist>\r
  73     <variablelist spacing="compact">\r
  74       <varlistentry>\r
  75         <term>\r
  76           <guilabel>Desktop file</guilabel>\r
  77         </term>\r
  78         <listitem>\r
  79           Name of the desktop file, used as an identifier in\r
  80           <link linkend="GuideOptionsKeyboard" endterm="titleGuideOptionsKeyboard" />\r
  81           .\r
  82         </listitem>\r
  83       </varlistentry>\r
  84       <varlistentry>\r
  85         <term>\r
  86           <guilabel>Path</guilabel>\r
  87         </term>\r
  88         <listitem>Full path to the desktop file. Desktop files in user directories override the system ones with the same name.</listitem>\r
  89       </varlistentry>\r
  90     </variablelist>\r
  91   </section>\r
  92   <section id="Addingneweditor">\r
  93     <title>Adding new editor</title>\r
  94     <para>\r
  95       <code>\r
  96         <guibutton>\r
  97           <guiicon>\r
  98             <inlinegraphic fileref="document-new.png" />\r
  99           </guiicon>\r
 100           New\r
 101         </guibutton>\r
 102       </code>\r
 103       opens a text editor with a desktop file template. You must amend the line\r
 104       <programlisting>Exec=command %f</programlisting>\r
 105       to contain the command you wish to execute. If it is more than a single command, you must create a script file and call that. If the location of the script file is not in your $PATH environment variable, you must include the full pathname.\r
 106     </para>\r
 107     <para />\r
 108   </section>\r
 109   <section id="Modifyinganexistingeditor">\r
 110     <title>Modifying an existing editor</title>\r
 111     <para>\r
 112       <code>\r
 113         <guibutton>\r
 114           <guiicon>\r
 115             <inlinegraphic fileref="gtk-edit.png" />\r
 116           </guiicon>\r
 117           Edit\r
 118         </guibutton>\r
 119       </code>\r
 120       opens a text editor with existing desktop file. For desktop files that are not writable by user, it allows saving to a Geeqie specific directory, where it overrides the system file (but only for Geeqie).\r
 121     </para>\r
 122   </section>\r
 123   <section id="Deletinganeditor">\r
 124     <title>Deleting an editor</title>\r
 125     <para>\r
 126       <code>\r
 127         <guibutton>\r
 128           <guiicon>\r
 129             <inlinegraphic fileref="edit-delete.png" />\r
 130           </guiicon>\r
 131           Delete\r
 132         </guibutton>\r
 133       </code>\r
 134       can delete user writable desktop files. System desktop files can't be deleted directly, but it is possible to edit them and set\r
 135       <literal>Hidden=TRUE</literal>\r
 136       , see above.\r
 137     </para>\r
 138   </section>\r
 139   <section id="Specialeditors">\r
 140     <title>Special editors</title>\r
 141     <para>A desktop file with one of the following names has a special function. It will replace the corresponding internal command.</para>\r
 142     <para>\r
 143       <programlisting xml:space="preserve">\r
 144         geeqie-copy-command.desktop\r
 145         geeqie-move-command.desktop\r
 146         geeqie-rename-command.desktop\r
 147         geeqie-delete-command.desktop\r
 148         geeqie-folder-command.desktop\r
 149       </programlisting>\r
 150     </para>\r
 151     <para>This can be used for example for a custom trash command or for manipulation of files under version control.</para>\r
 152   </section>\r
 153   <section id="Geeqieextensions">\r
 154     <title>Geeqie desktop file keys</title>\r
 155     <para>\r
 156       A desktop file for use only by Geeqie should have the following entries:\r
 157       <programlisting>\r
 158         Categories=X-Geeqie;\r
 159         OnlyShowIn=X-Geeqie;\r
 160       </programlisting>\r
 161     </para>\r
 162     <para>\r
 163       A menu path where the editor will appear, instead of in the default\r
 164       <menuchoice>\r
 165         <guimenu>Edit</guimenu>\r
 166         <guimenuitem>External Editors</guimenuitem>\r
 167       </menuchoice>\r
 168       , can be set by including:\r
 169       <programlisting>X-Geeqie-Menu-Path=&lt;FileMenuPath&gt;</programlisting>\r
 170     </para>\r
 171     <para>\r
 172       Possible vales for\r
 173       <emphasis>FileMenuPath</emphasis>\r
 174       are:\r
 175       <programlisting xml:space="preserve">\r
 176         FileMenu\r
 177         FileMenu/OpenSection\r
 178         FileMenu/SearchSection\r
 179         FileMenu/PrintSection\r
 180         FileMenu/FileOpsSection\r
 181         FileMenu/QuitSection\r
 182         GoMenu\r
 183         SelectMenu\r
 184         SelectMenu/SelectSection\r
 185         SelectMenu/ClipboardSection\r
 186         SelectMenu/MarksSection\r
 187         SelectMenu/EditMenu\r
 188         SelectMenu/ExternalMenu\r
 189         SelectMenu/EditSection\r
 190         SelectMenu/OrientationMenu\r
 191         SelectMenu/PropertiesSection\r
 192         SelectMenu/PreferencesMenu\r
 193         SelectMenu/PreferencesSection\r
 194         ViewMenu\r
 195         ViewMenu/WindowSection\r
 196         ViewMenu/FileDirMenu\r
 197         ViewMenu/FileDirMenu/FolderSection\r
 198         ViewMenu/FileDirMenu/ListSection\r
 199         ViewMenu/DirSection\r
 200         ViewMenu/ZoomMenu\r
 201         ViewMenu/ZoomMenu/ConnectZoomMenu\r
 202         ViewMenu/SplitMenu\r
 203         ViewMenu/ColorMenu\r
 204         ViewMenu/OverlayMenu\r
 205         ViewMenu/ViewSection\r
 206         ViewMenu/ToolsSection\r
 207         ViewMenu/SlideShowSection\r
 208         HelpMenu\r
 209         HelpMenu/HelpSection\r
 210       </programlisting>\r
 211     </para>\r
 212     <para>\r
 213       If you want an editor to use a user-definable path, the following entry must be made in the desktop file:\r
 214       <programlisting>X-Geeqie-Filter=true</programlisting>\r
 215     </para>\r
 216     <para>\r
 217       When the external editor is executed, you are presented with a dialogue which enables a path to be selected. The path selected, appended by the filename currently being processed, is made available to the editor script either as an environment variable or via a call to geeqie --remote. The following code demonstrates the use of both methods:\r
 218       <programlisting xml:space="preserve">\r
 219         for file in "$@"\r
 220         do\r
 221         destination=$(geeqie --remote --get-destination:"$file")\r
 222         \r
 223         echo "$destination"\r
 224         echo $GEEQIE_DESTINATION\r
 225         done\r
 226       </programlisting>\r
 227     </para>\r
 228     <para>\r
 229       If you want to run an editor in full-screen mode and wish full-screen to be maintained, include the following entry in the desktop file:\r
 230       <programlisting>X-Geeqie-Keep-Fullscreen=true</programlisting>\r
 231     </para>\r
 232     <para>\r
 233       Any terminal output from the editor command can be displayed with the following command:\r
 234       <programlisting>X-Geeqie-Verbose=true</programlisting>\r
 235     </para>\r
 236     <para>\r
 237       The editor can be restricted to run on only certain file types, for example:\r
 238       <programlisting>X-Geeqie-File-Extensions=.jpg; .cr2</programlisting>\r
 239       The entries are case insensitive.\r
 240     </para>\r
 241     <para>\r
 242       <programlisting>X-Geeqie-Keep-Verbose-Multi=</programlisting>\r
 243       TBD\r
 244     </para>\r
 245     <para>\r
 246       The key or key combination to execute this function can be set with:\r
 247       <programlisting>X-Geeqie-Hotkey=</programlisting>\r
 248       Key combinations are of the form:\r
 249 \r
 250       <programlisting>X-Geeqie-Hotkey=&lt;control&gt;y</programlisting>\r
 251       <note>\r
 252         This value may conflict with a setting in\r
 253         <link linkend="GuideOptionsKeyboard" endterm="titleGuideOptionsKeyboard" />\r
 254       </note>\r
 255     </para>\r
 256   </section>\r
 257 </section>\r