updated jEdit plugin documentation

diff --git a/actions.xml b/actions.xml
index 6b7eaba5ded91314c67a37d852597a4ff6a4fa27..be5949b468a09aee16fdc38abf3e3d2fa05ddf0d 100644 (file)
--- a/actions.xml
+++ b/actions.xml
@@ -3,6 +3,22 @@
 <!DOCTYPE ACTIONS SYSTEM "actions.dtd">
 
 <ACTIONS>
+       <ACTION NAME="factor-keymap">
+               <CODE>
+                       {
+                               p = new Properties();
+                               p.load(factor.jedit.FactorPlugin.class
+                                       .getResourceAsStream(
+                                       "/factor.keymap"));
+                               e = p.entrySet().iterator();
+                               while(e.hasNext())
+                               {
+                                       a = e.next();
+                                       jEdit.setProperty(a.key,a.value);
+                               }
+                       }
+               </CODE>
+       </ACTION>
        <ACTION NAME="factor-listener">
                <CODE>
                        wm.addDockableWindow("console");

diff --git a/build.xml b/build.xml
index 522a576400fc31466d437756dd19863ee7ff6850..5ded1fd65efb8f7dd19c64e2fa3384106f9361bb 100644 (file)
--- a/build.xml
+++ b/build.xml
@@ -34,10 +34,11 @@
                                <include name="factor/**/*.bsh"/>
                                <include name="factor/**/*.txt"/>
                                <include name="*.xml"/>
-                               <include name="doc/**/*.html"/>
-                               <include name="doc/**/*.png"/>
+                               <include name="*.keymap"/>
                                <include name="library/**/*.png"/>
                                <include name="doc/*.html"/>
+                               <include name="doc/jedit/*.html"/>
+                               <include name="doc/jedit/*.png"/>
                        </fileset>
                </jar>
        </target>

diff --git a/doc/jedit/index.html b/doc/jedit/index.html
index 7ab259333f6d141f0f302eb5441cf032919a89ae..6ec2d63eceed203e88cc650cc62e6c820a0d9ebf 100644 (file)
--- a/doc/jedit/index.html
+++ b/doc/jedit/index.html
@@ -94,18 +94,44 @@ color: #666699;
 
 The <code>Factor.jar</code> file shipped with the Factor distribution can then be placed in <code>$HOME/.jedit/jars/</code> and loaded by jEdit.<p>
 
-<h2 class="fancy-heading">Communication with an external Factor instance</h2>
+<h2 class="fancy-heading">Getting started</h2>
 
-<p>The Factor plugin needs to communicate with a running instance of a Factor runtime for most features to work. To set up the external instance, go to <b>Plugins</b>&gt;<b>Plugin Options</b>&gt;<b>Factor</b>. You will need to supply a full path to the Factor runtime, as well as a path to the image file.</p>
+<h3>Hooking jEdit up with Factor</h3>
 
-<h2 class="fancy-heading">Embedded listener</h2>
+<p>The Factor plugin needs to communicate with a running Factor instance. This is configured in <b>Plugins</b>&gt;<b>Plugin Options</b>&gt;<b>Factor</b>. There are two options when it comes to setting up the external instance:</p>
 
-<p>The embedded listener can be accessed by selecting the <b>Factor</b> shell in the Console plugin. The <b>Run current file</b> and <b>Evaluate selection</b> commands can be used to send text from jEdit to the listener.<p>
+<ul>
+<li>The plugin can launch the Factor process itself. In this case, you supply a full path to the Factor runtime, as well as a path to the image file.</li>
+<li>The plugin can also connect to a Factor instance running on another machine. In this case, you will need to supply the host name and port number. Then you must launch Factor on the remote machine and enter the phrase following in the listener:</li>
+</ul>
 
-<img class="nice-box" src="listener.png">
+<pre class="nice-box">USE: telnetd
+9999 telnetd</pre>
+
+<p>If you want to use a port number other than 9999, you must specify it above.</p>
+
+<h3>Keyboard shortcuts</h3>
+
+<p>You can install a set of keyboard shortcuts for the various commands provided by the Factor plugin by invoking <b>Plugins</b>&gt;<b>Factor</b>&gt;<b>Install default keymap</b>. These shortcuts are all prefixed with <b>A+</b>. While they are not set by the default, the remainder of the guide refers to these shortcuts.</p>
 
 <h2 class="fancy-heading">Live environment</h2>
 
+<h3>The listener</h3>
+
+<p>The plugin embeds a Factor listener in the Console for quick testing of code snippets while editing. The listener supports styled text and hyperlinks; for example when using the <code>see</code> word to look at a word definition.</p>
+
+<p>The embedded listener can be accessed by selecting the <b>Factor</b> shell in the Console plugin. The following commands can be used to send text from jEdit to the listener:</p>
+
+<ul>
+<li><b>Run current file (A+f f)</b></li>
+<li><b>Evaluate selection (A+f e s)</b></li>
+<li><b>Evaluate word definition (A+f e e)</b></li>
+</ul>
+
+<img class="nice-box" src="listener.png">
+
+<h3>Instant parsing</h3>
+
 <p>Factor files are parsed in a background thread and checked for errors, using the framework provided by the SideKick plugin. Errors are underlined in the text area (and listed in the <b>ErrorList</b> plugin window). Words are looked up in the external Factor instance, and you are notified of typos immediately.</p>
 
 <img class="nice-box" src="error.png">
@@ -118,7 +144,13 @@ The <code>Factor.jar</code> file shipped with the Factor distribution can then b
 
 <img class="nice-box" src="word-list.png">
 
-<p>The <b>Edit word</b> command opens a dialog box where the name of a word can be typed -- while the word is being typed, the possible completions is instantly updated, and selecting one opens the source file containing the definition of that word:</p>
+<h2 class="fancy-heading">Code comprehension</h2>
+
+<h3>Navigation</h3>
+
+<p>The navigation features enable you to move around in a project and locate definitions.</p>
+
+<p>The <b>Edit word (A+f g)</b> command opens a dialog box where the name of a word can be typed -- while the word is being typed, the possible completions is instantly updated, and selecting one opens the source file containing the definition of that word:</p>
 
 <img class="nice-box" src="edit-word.png">
 
@@ -127,13 +159,15 @@ The <code>Factor.jar</code> file shipped with the Factor distribution can then b
 <pre class="nice-box"><SPAN CLASS="syntax13">&quot;</SPAN><SPAN CLASS="syntax13">/home/slava/Factor/</SPAN><SPAN CLASS="syntax13">&quot;</SPAN> <SPAN CLASS="syntax13">&quot;</SPAN><SPAN CLASS="syntax13">resource-path</SPAN><SPAN CLASS="syntax13">&quot;</SPAN> set
 </PRE>
 
-<h2 class="fancy-heading">Browsing</h2>
+<p>The <b>Edit word at caret (A+f j)</b> command opens the source file containing the definition of the word at the caret.</p>
 
-<p>The <b>See word at caret</b> command displays a popup word definition.</p>
+<p>The <b>See word at caret (A+f w)</b> command displays a popup word definition.</p>
 
 <img class="nice-box" src="see.png">
 
-<p>The <b>Word usages at caret</b> command displays a list of words that use a word.</p>
+<h3>Cross-referencing</h3>
+
+<p>The <b>Word usages at caret (A+f u)</b> command displays a list of words that use a word.</p>
 
 <img class="nice-box" src="usages.png">
 
@@ -145,15 +179,15 @@ The <code>Factor.jar</code> file shipped with the Factor distribution can then b
 
 <img class="nice-box" src="usages-see.png">
 
-<p>The <b>Edit word at caret</b> command opens the source file containing the definition of the word at the caret.</p>
-
-<p>The <b>Infer word at caret</b> command shows a popup with the inferred stack effect. Note that not all words have an inferred stack effect. This command is great for debugging!</p>
+<p>The <b>Infer word at caret (A+f i i)</b> command shows a popup with the inferred stack effect. Note that not all words have an inferred stack effect. This command is great for debugging!</p>
 
 <img class="nice-box" src="infer.png">
 
 <h2 class="fancy-heading">Coding time-savers</h2>
 
-<p>Factor words are separated into vocabularies, and each source file must list which vocabularies it uses. A common error is a missing <code>USING:</code> declaration. The <b>Use word at caret</b> command searches for the word at the caret in all vocabularies, and adds a <code>USE:</code> declaration for the vocabulary to the start of the source file -- in this case, <code>ifte</code> is found in the <code>kernel</code> vocabulary, and the parse error instantly goes away:</p>
+<h3>Vocabularies</h3>
+
+<p>Factor words are separated into vocabularies, and each source file must list which vocabularies it uses. A common error is a missing <code>USING:</code> declaration. The <b>Use word at caret (A+f u)</b> command searches for the word at the caret in all vocabularies, and adds a <code>USE:</code> declaration for the vocabulary to the start of the source file -- in this case, <code>ifte</code> is found in the <code>kernel</code> vocabulary, and the parse error instantly goes away:</p>
 
 <img class="nice-box" src="word-use.png">
 
@@ -161,13 +195,15 @@ The <code>Factor.jar</code> file shipped with the Factor distribution can then b
 
 <img class="nice-box" src="complete.png">
 
+<h3>Automated factoring</h3>
+
 <p>The <b>Extract word</b> command can only be invoked if there is a selection. It asks for a new word name, replaces the selection with a call to the word, and adds a new colon definition directly above the current definition.</p>
 
 <p>Here, some text is selected:</p>
 
 <img class="nice-box" src="extract-before.png">
 
-<p>Now, <b>Extract word</b> is invoked, and a new word name is entered:</p>
+<p>Now, <b>Extract word (A+f x)</b> is invoked, and a new word name is entered:</p>
 
 <img class="nice-box" src="extract-after.png">
 

diff --git a/factor.keymap b/factor.keymap
new file mode 100644 (file)
index 0000000..20d2846
--- /dev/null
+++ b/factor.keymap
@@ -0,0 +1,18 @@
+factor-infer-effect.shortcut=A+f i i
+factor-run-file.shortcut=A+f f
+factor-eval-word-def.shortcut=A+f e e
+factor-listener.shortcut=A+f l
+factor-edit-dialog.shortcut=A+f g
+factor-extract-word.shortcut=A+f x
+factor-infer-effects.shortcut=A+f i a
+factor-compile.shortcut=A+f c c
+factor-apropos.shortcut=A+f a
+factor-balance.shortcut=A+f b
+factor-eval-selection.shortcut=A+f e s
+factor-compile-all.shortcut=A+f c a
+factor-float.shortcut=A+f n
+factor-edit.shortcut=A+f j
+factor.shortcut=A+f l
+factor-see.shortcut=A+f w
+factor-usages.shortcut=A+f s
+factor-insert-use.shortcut=A+f u

diff --git a/factor/jedit/FactorPlugin.props b/factor/jedit/FactorPlugin.props
index 170dd231ad709ef5d16e127d2cbfc3dd282de2d8..e57c42e450ff8b69ecf3adf53772a356bedd7e32 100644 (file)
--- a/factor/jedit/FactorPlugin.props
+++ b/factor/jedit/FactorPlugin.props
@@ -36,7 +36,9 @@ plugin.factor.jedit.FactorPlugin.menu=factor-listener \
        - \
        factor-extract-word \
        - \
-       factor-restart
+       factor-restart \
+       - \
+       factor-keymap
 
 factor-listener.label=Listener
 factor-run-file.label=Run current file
@@ -54,6 +56,7 @@ factor-infer-effects.label=Infer all words in buffer
 factor-compile.label=Compile word at caret
 factor-compile-all.label=Compile all words in buffer
 factor-restart.label=Restart Factor
+factor-keymap.label=Install default keymap
 
 # SideKick stuff
 sidekick.parser.factor.label=Factor