1<chapter id="id_usermenu"> 2<title>User-Configurable Menu</title> 3 4<sect1 id="id_usermenu_configuration"> 5<title>Configuration</title> 6 7<para>&kile; supports a user-configurable menu, which will appear as a part of &kile;'s menu. This menu can be configured using &kile;'s configuration dialog with <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile</guisubmenu><guimenuitem>User Menu</guimenuitem></menuchoice>.</para> 8 9 <screenshot> 10 <screeninfo>Configure the user menu</screeninfo> 11 <mediaobject> 12 <imageobject> 13 <imagedata fileref="usermenu_01.png" format="PNG" /> 14 </imageobject> 15 <textobject> 16 <phrase>Configure the user menu</phrase> 17 </textobject> 18 </mediaobject> 19 </screenshot> 20 21<para>You have two options where to place this menu:</para> 22 23<itemizedlist> 24<listitem> 25<para>either the menu <guimenu>User Menu</guimenu> will appear in the main menu bar between the menus <guimenu>LaTeX</guimenu> and <guimenu>Wizard</guimenu> and the configuration wizard <guimenuitem>Edit User Menu</guimenuitem> in the <guimenu>Wizard</guimenu> menu</para> 26 27 <screenshot> 28 <screeninfo>User Menu is placed in the main menu</screeninfo> 29 <mediaobject> 30 <imageobject> 31 <imagedata fileref="usermenu_02.png" format="PNG" /> 32 </imageobject> 33 <textobject> 34 <phrase>User Menu is placed in the main menu</phrase> 35 </textobject> 36 </mediaobject> 37 </screenshot> 38</listitem> 39 40<listitem> 41<para>or both items will appear at the bottom of the <guimenu>LaTeX</guimenu> menu.</para> 42 43 <screenshot> 44 <screeninfo>User Menu as a part of the LaTeX menu</screeninfo> 45 <mediaobject> 46 <imageobject> 47 <imagedata fileref="usermenu_03.png" format="PNG" /> 48 </imageobject> 49 <textobject> 50 <phrase>User Menu as a part of the LaTeX menu</phrase> 51 </textobject> 52 </mediaobject> 53 </screenshot> 54</listitem> 55</itemizedlist> 56 57 58<para>Already existing user-defined tags from older versions of &kile; are automatically transformed into the new user-configurable menu. The tags are saved in a file called <filename>usertags.xml</filename> and like all menu definition files, they can be found in the local user menu directory of &kile;: <filename>KILE_APP_DIR/usermenu/</filename>, ⪚ <filename>/home/user/.kde/share/apps/kile/usermenu/</filename>.</para> 59 60<para>You can use different menu definition files for different tasks. Call the user menu wizard <menuchoice><guimenu>Wizard</guimenu><guisubmenu>Edit User Menu</guisubmenu></menuchoice> or <menuchoice><guimenu>LaTeX</guimenu><guisubmenu>Edit User Menu</guisubmenu></menuchoice> to install or edit a menu definition file.</para> 61 62</sect1> 63 64 65<sect1 id="id_usermenu_wizard"> 66<title>Wizard</title> 67 68<para>You can create new or change existing menus with a comfortable user menu configuration wizard found at <menuchoice><guimenu>Wizard</guimenu><guisubmenu>Edit User Menu</guisubmenu></menuchoice>.</para> 69 70 <screenshot> 71 <screeninfo>User Menu Wizard</screeninfo> 72 <mediaobject> 73 <imageobject> 74 <imagedata fileref="usermenu_04.png" format="PNG" /> 75 </imageobject> 76 <textobject> 77 <phrase>User Menu Wizard</phrase> 78 </textobject> 79 </mediaobject> 80 </screenshot> 81 82<para>On the left side you will see an existing menu-tree. Like a standard menu, three different kinds of menu items are available:</para> 83 84<itemizedlist> 85<listitem><para>standard menu entries, which are assigned to an action</para></listitem> 86<listitem><para>submenus, which contain more menu items</para></listitem> 87<listitem><para>separators, to get a visible structure of all entries.</para></listitem> 88</itemizedlist> 89 90<para>To modify this menu, use the six buttons on the left side. More possible actions are available in the context menu of already existing menu items.</para> 91 92 <screenshot> 93 <screeninfo>User-Defined Menutree</screeninfo> 94 <mediaobject> 95 <imageobject> 96 <imagedata fileref="usermenu_05.png" format="PNG" /> 97 </imageobject> 98 <textobject> 99 <phrase>User-Defined Menutree</phrase> 100 </textobject> 101 </mediaobject> 102 </screenshot> 103 104<para>Each standard menu item is assigned to one of three action types, where each of them has different attributes, which could be set:</para> 105 106<itemizedlist> 107<listitem><para><guilabel>Text:</guilabel> &kile; gives you the ability to make your own tags. A tag is similar to a shortcut that launches some command or writes frequently-used texts, ⪚ Joe Sixpack often uses the sentences <userinput>Hi, I have been inserted ...</userinput>. This tag will be inserted at the current cursor position, when this action is called (see above). Metachars are also available (see <xref linkend="id_usermenu_placeholders" role="select: title pageabbrv"/>).</para> 108</listitem> 109 110<listitem><para><guilabel>Insert file contents:</guilabel> Inserts the complete contents of a given file.</para> 111 112 <screenshot> 113 <screeninfo>Insert file contents</screeninfo> 114 <mediaobject> 115 <imageobject> 116 <imagedata fileref="usermenu_06a.png" format="PNG" /> 117 </imageobject> 118 <textobject> 119 <phrase>Insert file contents</phrase> 120 </textobject> 121 </mediaobject> 122 </screenshot> 123</listitem> 124 125 <listitem><para><guilabel>Execute an external program:</guilabel> The output of this program can be inserted into the opened document. Metachar <userinput>%M</userinput> is also possible in the command line of this program, as the selected text will be saved in a temporary file. Use <userinput>%M</userinput> for the filename of this temporary file.</para> 126 127 <screenshot> 128 <screeninfo>Execute an external program</screeninfo> 129 <mediaobject> 130 <imageobject> 131 <imagedata fileref="usermenu_06b.png" format="PNG" /> 132 </imageobject> 133 <textobject> 134 <phrase>Execute an external program</phrase> 135 </textobject> 136 </mediaobject> 137 </screenshot> 138</listitem> 139 140</itemizedlist> 141 142<para>If some important information for an action is missing, menu items are colored red. This may be a nonexisting file</para> 143 144 <screenshot> 145 <screeninfo>Nonexisting file</screeninfo> 146 <mediaobject> 147 <imageobject> 148 <imagedata fileref="usermenu_07a.png" format="PNG" /> 149 </imageobject> 150 <textobject> 151 <phrase>Nonexisting file</phrase> 152 </textobject> 153 </mediaobject> 154 </screenshot> 155 156<para>or a missing title for the menu entry, which will be shown with question marks as <userinput>???</userinput>.</para> 157 158 <screenshot> 159 <screeninfo>Missing title of a menu entry</screeninfo> 160 <mediaobject> 161 <imageobject> 162 <imagedata fileref="usermenu_07b.png" format="PNG" /> 163 </imageobject> 164 <textobject> 165 <phrase>Missing title of a menu entry</phrase> 166 </textobject> 167 </mediaobject> 168 </screenshot> 169 170<para>If you open the context menu of such a red colored menu item, you will get an additional option for more information concerning this error.</para> 171 172 <screenshot> 173 <screeninfo>Additional info</screeninfo> 174 <mediaobject> 175 <imageobject> 176 <imagedata fileref="usermenu_07c.png" format="PNG" /> 177 </imageobject> 178 <textobject> 179 <phrase>Additional info</phrase> 180 </textobject> 181 </mediaobject> 182 </screenshot> 183 184<para>More information may also be available using the <guilabel>What's this</guilabel> feature of most widgets.</para> 185 186</sect1> 187 188 189<sect1 id="id_usermenu_placeholders"> 190<title>Placeholders</title> 191 192<sect2 id="id_usermenu_placeholders_text"> 193<title>Insert Text</title> 194 195<para>There are some placeholders you can use in your user-defined tags: <userinput>%C</userinput>, <userinput>%B</userinput>, <userinput>%M</userinput>, <userinput>%E</userinput>, <userinput>%R</userinput> and <userinput>%T</userinput>.</para> 196 197<itemizedlist> 198<listitem> 199<para><userinput>%C</userinput>: this is where the cursor will be placed after the insertion of a user-defined tag.</para> 200 201 <screenshot> 202 <screeninfo>Cursor Position (%C)</screeninfo> 203 <mediaobject> 204 <imageobject> 205 <imagedata fileref="usermenu_08a.png" format="PNG" /> 206 </imageobject> 207 <textobject> 208 <phrase>Cursor Position (%C)</phrase> 209 </textobject> 210 </mediaobject> 211 </screenshot> 212</listitem> 213 214<listitem> 215<para><userinput>%B</userinput>: will be replaced by a bullet (see <xref linkend="editing_bullets" role="select: title pageabbrv"/>).</para> 216 217 <screenshot> 218 <screeninfo>Bullet (%B)</screeninfo> 219 <mediaobject> 220 <imageobject> 221 <imagedata fileref="usermenu_08b.png" format="PNG" /> 222 </imageobject> 223 <textobject> 224 <phrase>Bullet (%B)</phrase> 225 </textobject> 226 </mediaobject> 227 </screenshot> 228</listitem> 229 230<listitem> 231<para><userinput>%M</userinput>: will be replaced by the selected text.</para> 232 233 <screenshot> 234 <screeninfo>Selected Text (%M)</screeninfo> 235 <mediaobject> 236 <imageobject> 237 <imagedata fileref="usermenu_08c.png" format="PNG" /> 238 </imageobject> 239 <textobject> 240 <phrase>Selected Text (%M)</phrase> 241 </textobject> 242 </mediaobject> 243 </screenshot> 244</listitem> 245 246<listitem> 247<para><userinput>%E</userinput>: denotes the indentation depth of text inside an environment.</para> 248 249 <screenshot> 250 <screeninfo>Indentation of environment text (%E)</screeninfo> 251 <mediaobject> 252 <imageobject> 253 <imagedata fileref="usermenu_08d.png" format="PNG" /> 254 </imageobject> 255 <textobject> 256 <phrase>Indentation of environment text (%E)</phrase> 257 </textobject> 258 </mediaobject> 259 </screenshot> 260</listitem> 261 262<listitem> 263<para><userinput>%R</userinput>: will call a reference-dialog to choose a label which has already been defined. This can be used to refer to a predefined label, which you can choose from a drop-down list (see also <menuchoice><guimenu>LaTeX</guimenu><guimenuitem>References</guimenuitem><guimenuitem>ref</guimenuitem></menuchoice> or 264<menuchoice><guimenu>LaTeX</guimenu><guimenuitem>References</guimenuitem><guimenuitem>pageref</guimenuitem></menuchoice>).</para> 265 266 <screenshot> 267 <screeninfo>References (%R)</screeninfo> 268 <mediaobject> 269 <imageobject> 270 <imagedata fileref="usermenu_08e.png" format="PNG" /> 271 </imageobject> 272 <textobject> 273 <phrase>References (%R)</phrase> 274 </textobject> 275 </mediaobject> 276 </screenshot> 277</listitem> 278 279<listitem> 280<para><userinput>%T</userinput>: will call a citation-dialog to choose an already defined citation. The same as using <menuchoice><guimenu>LaTeX</guimenu><guimenuitem>References</guimenuitem><guimenuitem>cite</guimenuitem></menuchoice> a list with all the citation keys pops up.</para> 281 282 <screenshot> 283 <screeninfo>Citation Keys (%T)</screeninfo> 284 <mediaobject> 285 <imageobject> 286 <imagedata fileref="usermenu_08f.png" format="PNG" /> 287 </imageobject> 288 <textobject> 289 <phrase>Citation Keys (%T)</phrase> 290 </textobject> 291 </mediaobject> 292 </screenshot> 293</listitem> 294</itemizedlist> 295 296<para>Let's consider another example, with the following macro <userinput>\frac{%M}{%C}</userinput>. First, we select a number in our text, let's say <userinput>42</userinput>. 297Now we invoke this macro and obtain <userinput>\frac{42}{}</userinput> with the cursor located within the second pair of brackets.</para> 298 299</sect2> 300 301<sect2 id="id_usermenu_placeholders_file"> 302<title>Insert File Contents</title> 303 304<para>If you want to insert the contents of a text file, you could use the same placeholders.</para> 305 306</sect2> 307 308<sect2 id="id_usermenu_placeholders_program"> 309<title>Execute A Program</title> 310 311<para>If you want to execute an external program, only the <userinput>%M</userinput> for selected text is recognized in the command line. The selection will be saved in a temporary file and the placeholder <userinput>%M</userinput> is replaced with this filename.</para> 312 313 <screenshot> 314 <screeninfo>Execute an external program (%M)</screeninfo> 315 <mediaobject> 316 <imageobject> 317 <imagedata fileref="usermenu_09.png" format="PNG" /> 318 </imageobject> 319 <textobject> 320 <phrase>Execute an external program (%M)</phrase> 321 </textobject> 322 </mediaobject> 323 </screenshot> 324 325<para>Another placeholder is <userinput>%S</userinput>, which is replaced by the complete base name of the current document without the path. This base name consists of all characters in the file up to (but not including) the last '.' character.</para> 326 327</sect2> 328 329</sect1> 330 331 332<sect1 id="id_usermenu_parameter"> 333<title>Parameter</title> 334 335<para>Most menu entries may have additional self-explaining parameters, which may be checked. If some of these parameters are not available for some kind of action, they are disabled.</para> 336 337 <screenshot> 338 <screeninfo>User Menu Parameter</screeninfo> 339 <mediaobject> 340 <imageobject> 341 <imagedata fileref="usermenu_10.png" format="PNG" /> 342 </imageobject> 343 <textobject> 344 <phrase>User Menu Parameter</phrase> 345 </textobject> 346 </mediaobject> 347 </screenshot> 348 349<para>Here is one example for executing an external program:</para> 350 351 <screenshot> 352 <screeninfo>Parameter example</screeninfo> 353 <mediaobject> 354 <imageobject> 355 <imagedata fileref="usermenu_11.png" format="PNG" /> 356 </imageobject> 357 <textobject> 358 <phrase>Parameter example</phrase> 359 </textobject> 360 </mediaobject> 361 </screenshot> 362 363<para>You can see that a <userinput>perl</userinput> script is called, which should work with current selection. The <guilabel>Needs selected text</guilabel> parameter is checked to assure a selection. The output of this script will be inserted (<guilabel>Insert the output of the chosen program</guilabel>) and replace the current selection (<guilabel>Replace selected text</guilabel>), but not selected itself.</para> 364 365<para>Of course you can also call your own programs or scripts. For example select a list of numbers, separated by spaces, and call a script or Perl program, which transforms this selection into &latex; code for a matrix. Whatever your ideas may be, you can realize them using the following usermenu entry.</para> 366 367 <screenshot> 368 <screeninfo>Parameter example 2</screeninfo> 369 <mediaobject> 370 <imageobject> 371 <imagedata fileref="usermenu_11b.png" format="PNG" /> 372 </imageobject> 373 <textobject> 374 <phrase>Parameter example 2</phrase> 375 </textobject> 376 </mediaobject> 377 </screenshot> 378 379</sect1> 380 381 382<sect1 id="id_usermenu_files"> 383<title>Menu Definition Files</title> 384 385<para>You can install different menus at runtime for different tasks. When you call the user menu wizard, the current menu definition file is loaded. If you modify it and close the dialog with <guibutton>OK</guibutton>, your changes will be saved and installed as the new user menu. Closing the dialog with <guibutton>Cancel</guibutton> will discard all changes.</para> 386 387 <screenshot> 388 <screeninfo>Menu Definition Files</screeninfo> 389 <mediaobject> 390 <imageobject> 391 <imagedata fileref="usermenu_12.png" format="PNG" /> 392 </imageobject> 393 <textobject> 394 <phrase>Menu Definition Files</phrase> 395 </textobject> 396 </mediaobject> 397 </screenshot> 398 399 400<para>You are also free to save the modified file in the user menu directory or to load another menu definition file and install it. All user menu definition files must be saved in the local user menu directory of &kile;: <filename>KILE_APP_DIR/usermenu/</filename>.</para> 401 402<para>Look at the example menu definition file <userinput>example.xml</userinput> to see more menu entries with their parameters.</para> 403 404</sect1> 405 406</chapter> 407
