editors: add editor integration tutorial

diff --git a/basis/editors/editors-docs.factor b/basis/editors/editors-docs.factor
index 1570bd7958cc4986a6e2370e757fa35140e44426..8baf4c2a105e757b5579e14d4f45fd92058901c2 100644 (file)
--- a/basis/editors/editors-docs.factor
+++ b/basis/editors/editors-docs.factor
@@ -1,5 +1,5 @@
 USING: help.markup help.syntax parser source-files
-source-files.errors vocabs.loader kernel ;
+source-files.errors vocabs.loader kernel editors.gedit ;
 IN: editors
 
 ARTICLE: "editor" "Editor integration"
@@ -12,7 +12,49 @@ $nl
 "Editor integration vocabularies store an object in a global variable when loaded:"
 { $subsections editor-class }
 "If a syntax error was thrown while loading a source file, you can jump to the location of the error in your editor:"
-{ $subsections :edit } ;
+{ $subsections :edit }
+"If your favourite editor is missing, you can add support for it. A tutorial is available at "
+{ $link "create-editor-integration" } "."
+;
+
+ARTICLE: "create-editor-integration" "Creating an editor integration"
+"First, let's start with creating a vocabulary for our editor:"
+{ $code "\"editors.foo\" scaffold-basis" }
+"Open it up in your favourite editor (or your second favourite.)"
+$nl
+"To create a new integration, we need to implement the editor protocol:"
+{ $list
+  { "Define a new class to represent your integration, set in " { $link editor-class } }
+  { "Define an " { $link editor-command } " method to construct a command that opens your editor" }
+  { "Define an " { $link editor-detached? } " method that denotes whether your editor should be run in "
+    "detached mode. This should return " { $link t } " for editors that run in a separate terminal." }
+  { "Define an " { $link editor-is-child? } " method that tells Factor whether it should be eun as "
+    "a child process." }
+}
+$nl
+"Every editor is required to reserve its own " { $link editor-class }  ". For example:"
+{ $code "SINGLETON: foo" }
+{ $link editor-class } " will be set to this singleton when Factor is set to use your editor of"
+" choice. Now, we will define words that will dispatch when the editor class is set to " 
+{ $snippet "foo" } "."
+$nl
+{ $link editor-command } " takes a file path and line number as strings. Your implementation should "
+"form a command that opens the editor to the given line. Many editors have a " { $snippet "+" } 
+" option for this. For a simple example of this word's implementation, we can look at "
+{ $vocab-link "editors.gedit" } ":"
+{ $code "M: gedit editor-command
+    [
+            gedit-path , number>string \"+\" prepend , ,
+    ] { } make ;" }
+"Here, " { $link gedit-path } " is a word that either pushes the location of " { $snippet "gedit" }
+" from PATH, or uses a user-defined path, set in a global."
+$nl
+"Finally, if your editor does not use a GUI, the " { $link editor-detached? } " method must be "
+"defined:"
+{ $code "M: foo editor-detached? t ;" }
+"If your editor has both GUI and TUI frontends, you may want to use more complex logic, or "
+"create a variable that the user can set."
+;
 
 ABOUT: "editor"