PageRenderTime 45ms CodeModel.GetById 16ms RepoModel.GetById 1ms app.codeStats 0ms

/www/tags/NOV_07_2009/htdocs/42docs/users-guide/starting.xml

#
XML | 319 lines | 258 code | 2 blank | 59 comment | 0 complexity | 5c7bbae2ce774e8ed5e6f756f1b50b75 MD5 | raw file
Possible License(s): BSD-3-Clause, AGPL-1.0, Apache-2.0, LGPL-2.0, LGPL-3.0, GPL-2.0, CC-BY-SA-3.0, LGPL-2.1, GPL-3.0, MPL-2.0-no-copyleft-exception, IPL-1.0
  1. <!-- jEdit buffer-local properties: -->
  2. <!-- :tabSize=1:indentSize=1:noTabs=true: -->
  3. <!-- :xml.root=users-guide.xml: -->
  4. <chapter id="starting"><title>Starting jEdit</title>
  5. <!-- sect1 id="starting-any-os"><title>Platform-Independent Instructions</title -->
  6. <para>
  7. Exactly how jEdit is started depends on the operating system. For example, on Unix you can run <quote>jedit</quote> at the command line,
  8. or select jEdit from a menu; on Windows, you can double-click on the jEdit icon or select it from the <guimenu>Start</guimenu> menu.
  9. <!-- use the jEditLauncher package, which is documented in
  10. <xref linkend="starting-windows" />. -->
  11. </para>
  12. <para>
  13. If jEdit is started while another copy is already running, control is
  14. transferred to the running copy, and a second instance is not loaded.
  15. This saves time and memory if jEdit is started multiple times.
  16. Communication between instances of jEdit is implemented using
  17. TCP/IP sockets; the initial instance is known as the
  18. <firstterm>server</firstterm>, and subsequent invocations are
  19. <firstterm>clients</firstterm>.
  20. </para>
  21. <para>
  22. If you find yourself launching and exiting jEdit a lot, the startup time can get a bit bothersome.
  23. If the <userinput>-background</userinput> command line switch is specified,
  24. jEdit will continue running and waiting for client requests even
  25. after all editor windows are closed. When run in background mode,
  26. you can open and close jEdit any number of times, only having
  27. to wait for it to start the first time. The downside of this
  28. is increased memory usage.
  29. </para>
  30. <para>
  31. When running on MacOS X, the <userinput>-background</userinput> command-line switch is active by default, so that jEdit conforms to the platform convention that programs should stay open until the <guimenuitem>Quit</guimenuitem> command is explicitly invoked by the user, even if all windows are closed. To disable background mode on MacOS X, use the <userinput>-nobackground</userinput> switch.
  32. </para>
  33. <para>
  34. For more information about command line switches that control the
  35. server feature, see <xref linkend="cli-usage" />.
  36. <!-- Note that if you are using <application>jEditLauncher</application>
  37. to start jEdit on Windows, this switch cannot be specified on the
  38. MS-DOS prompt command line when starting jEdit; it must be set as described
  39. in <xref linkend="launcher-starting" />. -->
  40. </para>
  41. <para>
  42. jEdit remembers open buffers, views and split window configurations between editing sessions, so you can get back to work immediately after starting jEdit. This feature can be
  43. disabled in the <guibutton>General</guibutton> pane of the
  44. <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
  45. dialog box see <xref linkend="general-pane" />.
  46. </para>
  47. <sidebar><title>The edit server and security</title>
  48. <para>
  49. Since Java does not provide any interprocess communication facility other than TCP/IP, jEdit takes extra precautions to prevent remote attacks.
  50. </para>
  51. <para>
  52. Not only does the edit server pick a random TCP port number on startup,
  53. it also requires that clients provide an <firstterm>authorization
  54. key</firstterm>; a randomly-generated number only accessible to
  55. processes running on the local machine.
  56. So not only will <quote>bad guys</quote> have to guess a 64-bit integer,
  57. they will need to get it right on the first try; the edit server
  58. shuts itself off upon receiving an invalid packet.
  59. </para>
  60. <para>
  61. In environments that demand absolute security, the edit server can be
  62. disabled by specifying the <userinput>-noserver</userinput> command line switch.
  63. </para>
  64. </sidebar>
  65. <!-- /sect1 -->
  66. <!-- sect1 id="starting-windows"><title>Starting jEdit on Windows</title>
  67. <para>
  68. jEdit bundles the <emphasis>jEditLauncher</emphasis> package and automatically installs it on Windows. jEditLauncher is a set of components that make it easy to start jEdit, manage its command
  69. line settings, and launch files and macro scripts.
  70. </para>
  71. <para>
  72. The jEditLauncher package installs three shortcuts for running jEdit: one at the top-level of the <guilabel>Start</guilabel> menu, another in the <guilabel>Programs</guilabel> submenu, and a third on your desktop. Any of these may be deleted or moved without
  73. affecting jEdit's operation. To launch jEdit, simply double-click one of these shortcuts
  74. as you would for any Windows application.
  75. </para>
  76. <para>
  77. The jEditLauncher package includes a utility for changing the command line
  78. parameters that are stored with jEditLauncher and used every time it runs jEdit.
  79. You can change the Java interpreter used to launch jEdit, the amount of heap memory,
  80. the working directory and other command line parameters. To make these changes,
  81. select <guilabel>Set jEdit Parameters</guilabel> from the jEdit group in
  82. the Programs menu, or run <userinput>jedit /p</userinput> from a command
  83. line that has jEdit's installation directory in its search path. A dialog
  84. will appear that allows you to change and save a new set of command line
  85. parameters.
  86. </para>
  87. <para>
  88. The package also adds menu items to the context or <quote>right-click</quote>
  89. menu displayed by the Windows shell when you click on a file item in the
  90. desktop window, a Windows Explorer window or a standard file selection dialog.
  91. The menu entries allow you to open selected files in jEdit, starting the
  92. application if necessary. It will also allow you to open all files in a
  93. directory with a given extension with a single menu selection. If a BeanShell
  94. macro script with a <filename>.bsh</filename> extension is selected, the menu
  95. includes the option of running that script within jEdit. If you have the
  96. <application>JDiff</application> plugin installed with jEdit, you can also
  97. select two files and have jEdit compare them in a side-by-side graphical display.
  98. </para>
  99. <para>
  100. For a more detailed description of all features found in
  101. the jEditLauncher package, see <xref linkend="launcher-guide"/>.
  102. </para>
  103. </sect1 -->
  104. <sect1 id="cli-usage"><title>Command Line Usage</title>
  105. <para>
  106. On operating systems that support a command line, jEdit can be passed
  107. various arguments to control its behavior.
  108. </para>
  109. <!-- para>
  110. If you are using <application>jEditLauncher</application>
  111. to start jEdit on Windows, only file names can be specified
  112. on the command line; the parameters documented below must be set as described
  113. in <xref linkend="launcher-starting" />.
  114. </para -->
  115. <para>
  116. When opening files from the command line, a line number or marker to
  117. position the caret on can be specified like so:
  118. </para>
  119. <screen><prompt>$ </prompt><userinput>jedit MyApplet.java +line:10</userinput>
  120. <prompt>$ </prompt><userinput>jedit thesis.tex +marker:c</userinput></screen>
  121. <para>
  122. Command-line switches begin with a "-". Some take a parameter. A file whose name
  123. begins with "-" can be opened like so:
  124. </para>
  125. <screen><prompt>$ </prompt><userinput>jedit -- -myfile</userinput></screen>
  126. <sect2><title>Miscellaneous Options</title>
  127. <informaltable>
  128. <tgroup cols="2">
  129. <colspec colnum="1" colwidth="1.5in" />
  130. <thead>
  131. <row><entry>Option</entry><entry>Effect</entry></row>
  132. </thead>
  133. <tbody>
  134. <row>
  135. <entry><userinput>-log=<replaceable>level</replaceable></userinput></entry>
  136. <entry>Set the minimum log level to an integer between 1 and 9. Default is 7.
  137. Has no effect when connecting to
  138. another instance via the edit server.</entry>
  139. </row>
  140. <row>
  141. <entry><userinput>-usage</userinput></entry>
  142. <entry>Show a brief command line usage message without starting
  143. jEdit.
  144. This message is also shown if an invalid switch was specified.</entry>
  145. </row>
  146. <row>
  147. <entry><userinput>-version</userinput></entry>
  148. <entry>Show the version number without starting jEdit.</entry>
  149. </row>
  150. <row>
  151. <entry><userinput>--</userinput></entry>
  152. <entry>Specifies the end of command-line processing. Further parameters are treated
  153. as file names, even if they begin with a dash.
  154. </entry>
  155. </row>
  156. </tbody>
  157. </tgroup>
  158. </informaltable>
  159. </sect2>
  160. <sect2><title>Configuration Options</title>
  161. <informaltable>
  162. <tgroup cols="2">
  163. <colspec colnum="1" colwidth="1.5in" />
  164. <thead>
  165. <row><entry>Option</entry><entry>Effect</entry></row>
  166. </thead>
  167. <tbody>
  168. <row>
  169. <entry><userinput>-plugins</userinput></entry>
  170. <entry>Enable loading of plugins. Has no effect
  171. when connecting to another instance via the edit server.
  172. See <xref linkend="using-plugins" />.</entry>
  173. </row>
  174. <row>
  175. <entry><userinput>-noplugins</userinput></entry>
  176. <entry>Disable loading of plugins. Has no effect
  177. when connecting to another instance via the edit server.</entry>
  178. </row>
  179. <row>
  180. <entry><userinput>-restore</userinput></entry>
  181. <entry>Restore previously open files on startup. This is the default.
  182. This feature can also be set permanently in the
  183. <guibutton>General</guibutton> pane of the
  184. <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
  185. dialog box; see <xref linkend="general-pane" />.
  186. </entry>
  187. </row>
  188. <row>
  189. <entry><userinput>-norestore</userinput></entry>
  190. <entry>Do not restore previously open files on startup.
  191. </entry>
  192. </row>
  193. <row>
  194. <entry><userinput>-run=<replaceable>script</replaceable></userinput></entry>
  195. <entry>Run the specified BeanShell script. There can only be one
  196. of these parameters on the command line. See
  197. <xref linkend="scripts-command-line" />.</entry>
  198. </row>
  199. <row>
  200. <entry><userinput>-settings=<replaceable>dir</replaceable></userinput></entry>
  201. <entry>Store user-specific settings in
  202. the directory named <replaceable>dir</replaceable>, instead of the
  203. default <filename><replaceable>user.home</replaceable>/.jedit</filename>.
  204. The directory will be created automatically if it does not exist. Has no
  205. effect when connecting to another instance via the edit server.
  206. See <xref linkend="settings-directory"/>.</entry>
  207. </row>
  208. <row>
  209. <entry><userinput>-nosettings</userinput></entry>
  210. <entry>Start jEdit without loading user-specific settings.</entry>
  211. </row>
  212. <row>
  213. <entry><userinput>-startupscripts</userinput></entry>
  214. <entry>Run startup scripts. This is the default.
  215. Has no effect
  216. when connecting to another instance via the edit server.
  217. See <xref linkend="startup-scripts" />.</entry>
  218. </row>
  219. <row>
  220. <entry><userinput>-nostartupscripts</userinput></entry>
  221. <entry>Disable startup scripts.
  222. Has no effect
  223. when connecting to another instance via the edit server.</entry>
  224. </row>
  225. </tbody>
  226. </tgroup>
  227. </informaltable>
  228. </sect2>
  229. <sect2><title>Edit Server Options</title>
  230. <para>
  231. See <xref linkend="starting" /> for a brief description of the edit server.
  232. </para>
  233. <informaltable>
  234. <tgroup cols="2">
  235. <colspec colnum="1" colwidth="1.5in" />
  236. <thead>
  237. <row><entry>Option</entry><entry>Effect</entry></row>
  238. </thead>
  239. <tbody>
  240. <row>
  241. <entry><userinput>-background</userinput></entry>
  242. <entry>Run jEdit in background mode. In background mode,
  243. the edit server will continue listening for
  244. client connections even after all views are closed. Has no effect
  245. when connecting to another instance via the edit server.</entry>
  246. </row>
  247. <row>
  248. <entry><userinput>-nobackground</userinput></entry>
  249. <entry>Disable background mode. This is the default.
  250. Has no effect when connecting to
  251. another instance via the edit server.</entry>
  252. </row>
  253. <row>
  254. <entry><userinput>-gui</userinput></entry>
  255. <entry>Open an initial view. This is the
  256. default. Has no effect when connecting to
  257. another instance via the edit server.
  258. </entry>
  259. </row>
  260. <row>
  261. <entry><userinput>-nogui</userinput></entry>
  262. <entry>Do not open an initial view, and instead only open one
  263. when the first client connects. Can only be used in combination with
  264. the <userinput>-background</userinput> switch. You can use this switch to
  265. <quote>pre-load</quote> jEdit when you log in to your computer, for
  266. example. Has no effect when connecting to
  267. another instance via the edit server.
  268. </entry>
  269. </row>
  270. <row>
  271. <entry><userinput>-newplainview</userinput></entry>
  272. <entry>Opens the specified files in a new plain view. For more information about views, see <xref linkend="views"/>.</entry>
  273. </row>
  274. <row>
  275. <entry><userinput>-newview</userinput></entry>
  276. <entry>Opens the specified files in a new view.</entry>
  277. </row>
  278. <row>
  279. <entry><userinput>-reuseview</userinput></entry>
  280. <entry>Opens the specified files in an existing view.</entry>
  281. </row>
  282. <row>
  283. <entry><userinput>-quit</userinput></entry>
  284. <entry>Exits the currently running editor instance.</entry>
  285. </row>
  286. <row>
  287. <entry><userinput>-server</userinput></entry>
  288. <entry>Store the server port info in the file named <filename>server</filename>
  289. inside the settings directory.</entry>
  290. </row>
  291. <row>
  292. <entry><userinput>-server=<replaceable>name</replaceable></userinput></entry>
  293. <entry>Store the server port info in the file named
  294. <replaceable>name</replaceable>. File names for this
  295. parameter are relative to the settings directory.</entry>
  296. </row>
  297. <row>
  298. <entry><userinput>-noserver</userinput></entry>
  299. <entry>Do not attempt to
  300. connect to a running edit server, and do not start one either.
  301. </entry>
  302. </row>
  303. <row>
  304. <entry><userinput>-wait</userinput></entry>
  305. <entry>Keeps the client open until the user closes the specified buffer in the server instance. Does nothing if passed to the initial jEdit instance. Use this switch if jEdit is being invoked by another program as an external editor; otherwise the client will exit immediately and the invoking program will assume you have finished editing the given file.
  306. </entry>
  307. </row>
  308. </tbody>
  309. </tgroup>
  310. </informaltable>
  311. </sect2>
  312. </sect1>
  313. </chapter>