PageRenderTime 11ms CodeModel.GetById 2ms app.highlight 3ms RepoModel.GetById 1ms app.codeStats 0ms

/jEdit/tags/jedit-4-5-pre1/doc/users-guide/launcher-guide.xml

#
XML | 537 lines | 474 code | 54 blank | 9 comment | 0 complexity | d24070dadf23fc314a02223e08f2d89c MD5 | raw file
  1<?xml version="1.0" encoding="UTF-8"?>
  2<!-- :xml.root=users-guide.xml:                               -->
  3<appendix id="launcher-guide">
  4    <title>jEditLauncher for Windows</title>
  5    <!-- jEdit buffer-local properties:                           -->
  6    <!-- :tabSize=2:indentSize=1:noTabs=true:maxLineLen=72:       -->
  7    <!-- jEditLauncher 4.0 (R2) Quick Guide                       -->
  8    <!-- Copyright (C) 2001, 2002 John Gellene                    -->
  9    <!-- $Id: launcher-guide.xml 16181 2009-09-08 19:26:57Z ezust $
 10-->
 11    <section id="launcher-intro">
 12        <title>Introduction</title>
 13
 14        <para>The jEditLauncher package is a set of lightweight components for
 15        running jEdit under the Windows group of operating systems. The package
 16        is designed to run on Windows 95, Windows 98, Windows Me, Windows NT
 17        (versions 4.0 and greater), Windows 2000 and Windows XP.</para>
 18
 19        <para>While jEdit does not make available a component-type interface, it
 20        does contains an <quote>EditServer</quote> that listens on a socket for
 21        requests to load scripts written in the BeanShell scripting language.
 22        When the server activates, it writes the server port number and a
 23        pseudo-random, numeric authorization key to a text file. By default, the
 24        file is named <filename>server</filename> and is located in the settings
 25        directory (see <xref linkend="settings-directory" />).</para>
 26
 27        <para>The jEditLauncher component locates and reads this file, opens a
 28        socket and attempts to connect to the indicated port. If successful, it
 29        transmits the appropriate BeanShell script to the server. If
 30        unsuccessful, it attempts to start jEdit and repeats the socket
 31        transmission once it can obtain the port and key information. The
 32        component will abandon the effort to connect roughly twenty seconds
 33        after it launches the application.</para>
 34    </section>
 35
 36    <section id="launcher-starting">
 37        <title>Starting jEdit</title>
 38
 39        <para>The main component of the jEditLauncher package is a client
 40        application entitled <command>jedit.exe</command>. It may be executed
 41        either from either Windows Explorer, a shortcut icon or the command
 42        line. It uses the jEditLauncher COM component to open files in jEdit
 43        that are listed as command line parameters. It supports Windows and UNC
 44        file specifications as well as wild cards. If called without parameters,
 45        it will launch jEdit. If jEdit is already running<!--  and has an active
 46      EditServer -->, it will simply open a new, empty buffer.</para>
 47
 48        <para><command>jedit.exe</command> supports five command-line options.
 49        Except for the <userinput>/1</userinput> option, if any of these options
 50        are invoked correctly, the application will not load files or execute
 51        jEdit.</para>
 52
 53        <itemizedlist>
 54            <listitem>
 55                <para>The option <userinput>/h</userinput> causes a window to be
 56                displayed with a brief description of the application and its
 57                various options.</para>
 58            </listitem>
 59
 60            <listitem>
 61                <para>The option <userinput>/p</userinput> will activate a
 62                dialog window displaying the command-line parameters to be used
 63                when calling jEdit. This option can also be triggered by
 64                selecting <guilabel>Set jEdit Parameters</guilabel> from the
 65                <guilabel>jEdit</guilabel> section of the Windows Programs menu,
 66                or by running the utility program
 67                <command>jedinit.exe</command></para>
 68
 69                <para>Using the dialog, you can change parameters specifying the
 70                executable for the Java application loader (either
 71                <filename>java.exe</filename> or
 72                <filename>javaw.exe</filename>), the location of the jEdit
 73                archive file, <filename>jedit.jar</filename>, and command line
 74                options for both. <itemizedlist>
 75                        <listitem>
 76                            <para>The input fields for Java options and jEdit
 77                            options are separate. If you insert an option in the
 78                            wrong place it will not be properly executed.</para>
 79                        </listitem>
 80
 81                        <listitem>
 82                            <para>If the <userinput>-jar</userinput> option is
 83                            not used with the Java application loader the
 84                            principal jEdit class of
 85                            <classname>org.gjt.sp.jedit.jEdit</classname> is set
 86                            as fixed data.</para>
 87                        </listitem>
 88
 89                        <listitem>
 90                            <para>The working directory for the Java
 91                            interpreter's process can also be specified.</para>
 92                        </listitem>
 93                    </itemizedlist> A read-only window at the bottom of the
 94                dialog displays the full command line that jEditLauncher will
 95                invoke.</para>
 96
 97                <para>Before committing changes to the command line parameters,
 98                <command>jedit.exe</command> validates the paths for the Java
 99                and jEdit targets as well as the working directory. It will
100                complain if the paths are invalid. It will not validate command
101                line options, but it will warn you if it finds the
102                <userinput>-noserver</userinput> option used for jEdit, since
103                this will deactivate the edit server and make it impossible for
104                jEditLauncher to open files.</para>
105
106                <para>Note that due to the design of
107                <application>jEditLauncher</application>, platform-independent
108                command line options handled by jEdit itself (such as
109                <userinput>-background</userinput> and
110                <userinput>-norestore</userinput>) must be entered in the
111                <quote>Set jEdit Parameters</quote> dialog box, and cannot be
112                specified on the <command>jedit.exe</command> command line
113                directly. For information about platform-independent command
114                line options, see <xref linkend="cli-usage" />.</para>
115            </listitem>
116
117            <listitem>
118                <para>The option <userinput>/1</userinput> is intended for use
119                in circumstances where a single file name is passed to jEdit for
120                opening, and quotation marks cannot be used to delimit file
121                names containing whitespace. The launcher reads the entire
122                command line following the <userinput>/1</userinput> options as
123                a single file path, regardless of the presence of whitespace,
124                and passes the resulting string as a single file name parameter
125                to jEdit.</para>
126
127                <para>This option allows jEdit to be used with version 5 or
128                greater of Internet Explorer as an alternate text editor or as
129                the target of the <guimenuitem>View Source</guimenuitem>
130                command. Included with the jEditLauncher distribution is a file
131                named <filename>jEdit_IE.reg.txt</filename> containing an
132                example of a Window registry file that you can use to register
133                jEdit as a HTML editor with Internet Explorer. Instructions for
134                the file's use are included in the text.</para>
135
136                <para>The use of the <userinput>/1</userinput> option with
137                multiple file names or other parameters will lead to program
138                errors or unpredictable results.</para>
139            </listitem>
140
141            <listitem>
142                <para>The option <userinput>/i</userinput> is not mentioned in
143                the help window for <filename>jedit.exe</filename>. It is
144                intended primarily to be used in conjunction with jEdit's Java
145                installer, but it can also be used to install or reinstall
146                jEditLauncher manually. When accompanied by a second parameter
147                specifying the directory where your preferred Java interpreter
148                is located, jEditLauncher will install itself and set a
149                reasonable initial set of command line parameters for executing
150                jEdit. You can change these parameters later by running
151                <filename>jedinit.exe</filename> or
152                <filename>jedit.exe</filename> with the<userinput>/p</userinput>
153                option.</para>
154            </listitem>
155
156            <listitem>
157                <para>The option <userinput>/u</userinput> will cause
158                jEditLauncher to be uninstalled by removing its registry
159                entries. This option does not delete any jEditLauncher or jEdit
160                files.</para>
161            </listitem>
162        </itemizedlist>
163    </section>
164
165    <section id="launcher-menu">
166        <title>The Context Menu Handler</title>
167
168        <para>The jEditLauncher package also implements a context menu handler
169        for the Windows shell. It is intended to be be installed as a handler
170        available for any file. When you right-click on a file or shortcut icon,
171        the context menu that appears will include an item displaying the jEdit
172        icon and captioned <guilabel>Open with jEdit</guilabel>. If the file has
173        an extension, another item will appear captioned <guilabel>Open *.XXX
174        with jEdit</guilabel>, where XXX is the extension of the selected file.
175        Clicking this item will cause jEdit to load all files with the same
176        extension in the same directory as the selected file. Multiple file
177        selections are also supported; in this circumstance only the
178        <guilabel>Open with jEdit</guilabel> item appears.</para>
179
180        <para>If a single file with a <filename>.bsh</filename> extension is
181        selected, the menu will also contain an item captioned <guilabel>Run
182        script in jEdit</guilabel>. Selecting this item will cause jEditLauncher
183        to run the selected file as a BeanShell script.</para>
184
185        <para>If exactly two files are selected, the menu will contain an entry
186        for <guilabel>Show diff in jEdit</guilabel>. Selecting this item will
187        load the two files in jEdit and have them displayed side-by-side with
188        their differences highlighted by the <application>JDiff</application>
189        plugin. The file selected first will be treated as the base for
190        comparison purposes. If the plugin is not installed, an error message
191        will be displayed in jEdit. See <xref linkend="using-plugins" /> for
192        more information about installing plugins.</para>
193    </section>
194
195    <!-- open section -->
196
197    <section id="launcher-jedidiff">
198        <title>Using jEdit and jEditLauncher as a Diff Utility</title>
199
200        <para>As noted above, you can create a graphical diff display comparing
201        the contents of two text files by selecting the two files in an Explorer
202        window, right-clicking to produce a context menu, and selecting the
203        <guimenuitem>Show diff in jEdit</guimenuitem> menu item. The utility
204        <filename>jedidiff.exe</filename> allows you to perform this operation
205        from a command line. The command takes the two files to be compared as
206        parameters; they should be delimited by quotation marks if their paths
207        contain whitespace.</para>
208    </section>
209
210    <section id="launcher-uninstall">
211        <title>Uninstalling jEdit and jEditLauncher</title>
212
213        <para></para>
214
215        <para>There are three ways to uninstall jEdit and jEditLauncher.</para>
216
217        <itemizedlist>
218            <listitem>
219                <para>First, you can run <filename>unlaunch.exe</filename> in
220                the jEdit installation directory.</para>
221            </listitem>
222
223            <listitem>
224                <para>Second, you can choose <guilabel>Uninstall
225                jEdit</guilabel> from the <guilabel>jEdit</guilabel> section of
226                the Programs menu. <!-- This will
227        uninstall the <quote>primary</quote> version of jEdit (and will
228        designate a new primary version if any versions remain). --></para>
229            </listitem>
230
231            <listitem>
232                <para>Third, you can choose the uninstall option for jEdit in
233                the Control Panel's Add/Remove Programs applet. <!-- This allows you to specify
234        unambiguously the version of jEdit that you wish to remove. --></para>
235            </listitem>
236        </itemizedlist>
237
238        <para>Each of these options will deactivate jEditLauncher and delete all
239        files in jEdit's installation directory. As a safeguard, jEditLauncher
240        displays a warning window and requires the user to confirm an uninstall
241        operation. Because the user's settings directory can be set and changed
242        from one jEdit session to another, user settings files must be deleted
243        manually.</para>
244
245        <para>To deactivate jEditLauncher without deleting any files, run
246        <filename>jedit /u</filename> from any command prompt where the jEdit
247        installation directory is in the search path. This will remove the
248        entries for jEditLauncher from the Windows registry. It will also
249        disable the context menu handler and the automatic launching and
250        scripting capabilities. The package can reactivated by executing
251        <command>jedit.exe</command> again, and jEdit can be started in the same
252        manner as any other Java application on your system.</para>
253    </section>
254
255    <section id="launcher-interface">
256        <title>The jEditLauncher Interface</title>
257
258        <para>The core of the jEditLauncher package is a COM component that can
259        communicate with the EditServer, or open jEdit if it is not running or
260        is otherwise refusing a connection. The component supports both Windows
261        and UNC file specifications, including wild cards. It will resolve
262        shortcut links to identify and transmit the name of the underlying
263        file.</para>
264
265        <para>Because it is implemented with a <quote>dual interface</quote>,
266        the functions of jEditLauncher are available to scripting languages in
267        the Windows environment such as VBScript, JScript, Perl (using the
268        Win32::OLE package) and Python (using the win32com.client
269        package).</para>
270
271        <para>The scriptable interface consists of two read-only properties and
272        six functions:</para>
273
274        <para><emphasis>Properties</emphasis></para>
275
276        <itemizedlist>
277            <listitem>
278                <para><varname>ServerPort</varname> - a read-only property that
279                returns the port number found in jEdit's server file; the value
280                is not tested for authenticity. It returns zero if the server
281                information file cannot be located.</para>
282            </listitem>
283
284            <listitem>
285                <para><varname>ServerKey</varname> - a read-only property that
286                returns the numeric authorization key found in jEdit's server
287                file; the value is not tested for authenticity. It returns zero
288                if the server information file cannot be located.</para>
289            </listitem>
290        </itemizedlist>
291
292        <para><emphasis>Functions</emphasis></para>
293
294        <itemizedlist>
295            <listitem>
296                <para><function>OpenFile</function> - a method that takes a
297                single file name (with or without wild card characters) as a
298                parameter.</para>
299            </listitem>
300
301            <listitem>
302                <para><function>OpenFiles</function> - this method takes an
303                array of file names (with or without wild card characters) as a
304                parameter. The form of the array is that which is used for
305                arrays in the scripting environment. In JScript, for example the
306                data type of the <classname>VARIANT</classname> holding the
307                array is <classname>VT_DISPATCH</classname>; in VBScript, it is
308                <classname>VT_ARRAY | VT_VARIANT</classname>, with array members
309                having data type <classname>VT_BSTR</classname>.</para>
310            </listitem>
311
312            <listitem>
313                <para><function>Launch</function> - this method with no
314                parameters attempts to open jEdit without loading additional
315                files.</para>
316            </listitem>
317
318            <listitem>
319                <para><function>RunScript</function> - this method takes a file
320                name or full file path as a parameter and runs the referenced
321                file as a BeanShell script in jEdit. The predefined variables
322                <varname>view</varname>, <varname>editPane</varname>,
323                <varname>textArea</varname> and <varname>buffer</varname> are
324                available to the script. If more than one view is open, the
325                variable are initialized with reference to the earliest opened
326                view. If no path is given for the file it will use the working
327                directory of the calling process.</para>
328            </listitem>
329
330            <listitem>
331                <para><function>EvalScript</function> - this method takes a
332                string as a parameter containing one or more BeanShell
333                statements and runs the script in jEdit's BeanShell interpreter.
334                The predefined variables are available on the same basis as in
335                <function>RunScript</function>.</para>
336            </listitem>
337
338            <listitem>
339                <para><function>RunDiff</function> - this method takes two
340                strings representing file names as parameters. If the
341                <application>JDiff</application> plugin is installed, this
342                method will activate the JDiff plugin and display the two files
343                in the plugin's graphical <quote>dual diff</quote> format. The
344                first parameter is treated as the base for display purposes. If
345                the <application>JDiff</application> plugin is not installed, a
346                error message box will be displayed in jEdit.</para>
347            </listitem>
348        </itemizedlist>
349    </section>
350
351    <section id="launcher-examples">
352        <title>Scripting Examples</title>
353
354        <para>Here are some brief examples of scripts using jEditLauncher. The
355        first two will run under Windows Script Host, which is either installed
356        or available for download for 32-bit Windows operating systems. The next
357        example is written in Perl and requires the Win32::OLE package. The last
358        is written in Python and requires the win32gui and win32com.client
359        extensions.</para>
360
361        <para>If Windows Script Host is installed, you can run the first two
362        scripts by typing the name of the file containing the script at a
363        command prompt. In jEdit's <application>Console</application> plugin,
364        you can type <userinput>cmd /c
365        <replaceable>script_path</replaceable></userinput> or <userinput>wscript
366        <replaceable>script_path</replaceable></userinput>.</para>
367
368        <informalexample>
369            <programlisting>' Example VBScript using jEditLauncher interface
370dim launcher
371set launcher = CreateObject("JEdit.JEditLauncher")
372a = Array("I:\Source Code Files\shellext\jeditshell\*.h", _
373	"I:\Source Code Files\shellext\jeditshell\*.cpp")
374MsgBox "The server authorization code is " + _
375	FormatNumber(launcher.ServerKey, 0, 0, 0, 0) + ".", _
376	vbOKOnly + vbInformation, "jEditLauncher"
377launcher.openFiles(a)
378myScript = "jEdit.newFile(view); textArea.setSelectedText(" _
379  &amp; CHR(34) _
380  &amp; "Welcome to jEditLauncher." _
381  &amp; CHR(34) &amp; ");"
382launcher.evalScript(myScript)</programlisting>
383        </informalexample>
384
385        <informalexample>
386            <programlisting>/* Example JScript using jEditLauncher interface
387 * Note: in contrast to VBScript, JScript does not
388 * directly support message boxes outside a browser window
389 */
390var launcher = WScript.createObject("JEdit.JEditLauncher");
391var a = new Array("I:\\weather.html", "I:\\test.txt");
392b = "I:\\*.pl";
393launcher.openFiles(a);
394launcher.openFile(b);
395c = "G:\\Program Files\\jEdit\\macros\\Misc"
396  + "\\Properties\\System_properties.bsh";
397launcher.runScript(c);</programlisting>
398        </informalexample>
399
400        <informalexample>
401            <programlisting># Example Perl script using jEditLauncher interface
402use Win32::OLE;
403$launcher = Win32::OLE-&gt;new('JEdit.JEditLauncher') ||
404   die "JEditLauncher: not found !\n";
405@files = ();
406foreach $entry (@ARGV) {
407    @new = glob($entry);
408    push(@files,@new);
409}
410$launcher-&gt;openFiles(\@files);
411my($script) = "Macros.message(view, \"I found "
412    .(scalar @files)." files.\");";
413$launcher-&gt;evalScript($script);</programlisting>
414        </informalexample>
415
416        <informalexample>
417            <programlisting># Example Python script using jEditLauncher interface
418import win32gui
419import win32com.client
420o = win32com.client.Dispatch("JEdit.JEditLauncher")
421port = o.ServerPort
422if port == 0:
423  port = "inactive. We will now launch jEdit"
424win32gui.MessageBox(0, "The server port is %s." % port,
425    "jEditLauncher", 0)
426path = "C:\\WINNT\\Profiles\\Administrator\\Desktop\\"
427o.RunDiff(path + "Search.bsh", path + "Search2.bsh")
428</programlisting>
429        </informalexample>
430    </section>
431
432    <!-- open section -->
433
434    <section id="launcher-logging">
435        <title>jEditLauncher Logging</title>
436
437        <para>The jEditLauncher package has a logging facility that is separate
438        from jEdit's Activity Log to provide a record of events occurring
439        outside the Java virtual machine environment in which jEdit operates.
440        The logging facility maintains two log files:
441        <filename>jelaunch.log</filename> for events relating to starting jEdit,
442        loading files and running scripts, and <filename>install.log</filename>
443        for jEditLauncher installation activity. Both files are maintained in
444        the directory in which jEdit is installed. They are cumulative from
445        session to session, but may be manually deleted at any time without
446        affecting program execution.</para>
447    </section>
448
449    <!-- <section id="launcher-install"><title>Standalone Installation</title>
450    <para>
451      Installation of jEditLauncher occurs as part of the installation of the
452      jEdit package for Windows. If a full jEdit installation fails, you can
453      install jEditLauncher by placing the following files in the same
454      directory as <filename>jedit.jar</filename>, the archive containing the
455      Java application:
456    </para>
457    <itemizedlist>
458      <listitem>
459      <para>
460      <filename>jedit.exe</filename>
461        </para>
462      </listitem>
463      <listitem>
464      <para>
465        <filename>jedinit.exe</filename>
466      </para>
467      </listitem>
468      <listitem>
469      <para>
470        <filename>jeshlstb.dll</filename>
471      </para>
472      </listitem>
473      <listitem>
474      <para>
475        <filename>jedinstl.dll</filename>
476      </para>
477      </listitem>
478      <listitem>
479      <para>
480        <filename>jeditsvr.exe</filename>
481      </para>
482      </listitem>
483      <listitem>
484      <para>
485        <filename>jeservps.dll</filename>
486      </para>
487      </listitem>
488      <listitem>
489      <para>
490        <filename>unlaunch.exe</filename>
491      </para>
492      </listitem>
493    </itemizedlist>
494    <para>
495      Anytime <filename>jedit.exe</filename> is executed (either directly or
496      indirectly through a call to <filename>jedinit.exe</filename>),
497      jEditLauncher checks to see if it is properly installed. If it is not,
498      it will offer to install itself. If you agree, you will then be asked to
499      supply the path to a Java interpreter. The directory you choose should
500      contain <filename>javaw.exe</filename>, which the installer uses as a
501      default; you can change the interpreter later with a call to
502      <filename>jedinit.exe</filename>.
503    </para>
504</section> -->
505
506    <section id="launcher-legalnotice">
507        <title>Legal Notice</title>
508
509        <para>All source code and software distributed as the jEditLauncher
510        package in which the author holds the copyright is made available under
511        the GNU General Public License (<quote>GPL</quote>). A copy of the GPL
512        is included in the file <filename>COPYING.txt</filename> included with
513        jEdit.</para>
514
515        <para>Notwithstanding the terms of the General Public License, the
516        author grants permission to compile and link object code generated by
517        the compilation of this program with object code and libraries that are
518        not subject to the GNU General Public License, provided that the
519        executable output of such compilation shall be distributed with source
520        code on substantially the same basis as the jEditLauncher package of
521        which this source code and software is a part. By way of example, a
522        distribution would satisfy this condition if it included a working
523        Makefile for any freely available make utility that runs on the Windows
524        family of operating systems. This condition does not require a licensee
525        of this software to distribute any proprietary software (including
526        header files and libraries) that is licensed under terms prohibiting or
527        limiting redistribution to third parties.</para>
528
529        <para>The purpose of this specific permission is to allow a user to link
530        files contained or generated by the source code with library and other
531        files licensed to the user by Microsoft or other parties, whether or not
532        that license conforms to the requirements of the GPL. This permission
533        should not be construed to expand the terms of any license for any
534        source code or other materials used in the creation of
535        jEditLauncher.</para>
536    </section>
537</appendix>