Add some docs for linter, comment, status

internal/config/settings.go

@@ -198,7 +198,7 @@ var defaultCommonSettings = map[string]interface{}{
 	"softwrap":       false,
 	"splitbottom":    true,
 	"splitright":     true,
-	"statusformatl":  "$(filename) $(modified)($(line),$(col)) | ft:$(opt:filetype) | $(opt:fileformat) | $(opt:encoding)",
+	"statusformatl":  "$(filename) $(modified)($(line),$(col)) $(status.paste)| ft:$(opt:filetype) | $(opt:fileformat) | $(opt:encoding)",
 	"statusformatr":  "$(bind:ToggleKeyMenu): bindings, $(bind:ToggleHelp): help",
 	"statusline":     true,
 	"syntax":         true,

runtime/help/options.md

@@ -218,8 +218,8 @@ Here are the available options:
    The `opt` and `bind` directives take either an option or an action afterward
    and fill in the value of the option or the key bound to the action.
 
-    default value: `$(filename) $(modified)($(line),$(col)) $(opt:filetype)
-                    $(opt:fileformat) $(opt:encoding)`
+    default value: `$(filename) $(modified)($(line),$(col)) $(status.paste)|
+                    ft:$(opt:filetype) | $(opt:fileformat) | $(opt:encoding)`
 
 * `statusformatr`: format string definition for the right-justified part of the
    statusline.

runtime/help/plugins.md

@@ -295,6 +295,9 @@ There are 6 default plugins that come pre-installed with micro. These are
 * `status`: provides some extensions to the status line (integration with
    Git and more).
 
+See `> help linter`, `> help comment`, and `> help status` for additional
+documentation specific to those plugins.
+
 These are good examples for many use-cases if you are looking to write
 your own plugins.
 

runtime/plugins/comment/comment.lua

@@ -107,4 +107,5 @@ end
 function init()
     config.MakeCommand("comment", "comment.comment", config.NoComplete)
     config.TryBindKey("Alt-/", "lua:comment.comment", false)
+    config.AddRuntimeFile("comment", config.RTHelp, "help/comment.md")
 end

runtime/plugins/comment/help/comment.md

@@ -0,0 +1,60 @@
+# Comment Plugin
+
+The comment plugin provides auto commenting/uncommenting.
+The default binding to comment/uncomment a line is `Alt-/`,
+but you can easily modify that in your `bindings.json` file:
+
+```json
+{
+    "Alt-g": "comment.comment"
+}
+```
+
+You can also execute a command which will do the same thing as
+the binding:
+
+```
+> comment
+```
+
+If you have a selection, the plugin will comment all the lines
+selected.
+
+The comment type will be auto detected based on the filetype,
+but it is only available for certain filetypes:
+
+* c: `// %s`
+* c++: `// %s`
+* d: `// %s`
+* go: `// %s`
+* html: `<!-- %s -->`
+* java: `// %s`
+* javascript: `// %s`
+* julia: `# %s`
+* lua: `-- %s`
+* perl: `# %s`
+* php: `// %s`
+* python: `# %s`
+* python3: `# %s`
+* ruby: `# %s`
+* rust: `// %s`
+* shell: `# %s`
+* swift: `// %s`
+
+If your filetype is not available here, you can simply modify
+the `commenttype` option:
+
+```
+set commenttype "/* %s */"
+```
+
+Or in your `settings.json`:
+
+```json
+{
+    "*.c": {
+        "commenttype": "/* %s */"
+    }
+}
+```
+

runtime/plugins/linter/help/linter.md

@@ -0,0 +1,80 @@
+# Linter
+
+The linter plugin runs a compiler or linter on your source code
+and parses the resulting output so that the messages and line numbers
+can be viewed from within micro. By default, the plugin supports the
+following filetypes and linters:
+
+* c: gcc
+* c++: g++
+* d: dmd
+* go: go build
+* java: javac
+* javascript: jshint
+* literate: lit
+* lua: luacheck
+* nim: nim
+* objective-c: clang
+* python: pyflakes
+* python: mypy
+* python: pylint
+* shell: shfmt
+* swift: swiftc
+* yaml: yamllint
+
+If the linter plugin is enabled and the file corresponds to one of
+these filetypes, each time the buffer is saved, or when the `> lint`
+command is executed, micro will run the corresponding utility in the
+background and display the messages when it completes.
+
+The linter plugin also allows users to extend the supported filetypes.
+From inside another micro plugin, the function `linter.makeLinter` can
+be called to register a new filetype. Here is the spec for the `makeLinter`
+function:
+
+* `linter.makeLinter(name, filetype, cmd, args, errorformat, os, whitelist, domatch, loffset, coffset, callback)`
+
+> name: name of the linter
+> filetype: filetype to check for to use linter
+> cmd: main linter process that is executed
+> args: arguments to pass to the linter process
+    use %f to refer to the current file name
+    use %d to refer to the current directory name
+> errorformat: how to parse the linter/compiler process output
+    %f: file, %l: line number, %m: error/warning message
+> os: list of OSs this linter is supported or unsupported on
+    optional param, default: {}
+> whitelist: should the OS list be a blacklist (do not run the linter for these OSs)
+           or a whitelist (only run the linter for these OSs)
+    optional param, default: false (should blacklist)
+> domatch: should the filetype be interpreted as a lua pattern to match with
+         the actual filetype, or should the linter only activate on an exact match
+    optional param, default: false (require exact match)
+> loffset: line offset will be added to the line number returned by the linter
+         useful if the linter returns 0-indexed lines
+    optional param, default: 0
+> coffset: column offset will be added to the col number returned by the linter
+         useful if the linter returns 0-indexed columns
+    optional param, default: 0
+> callback: function to call before executing the linter, if it returns
+          false the lint is canceled. The callback is passed the buf.
+    optional param, default: nil
+
+Below is an example for including a linter for any filetype using
+the `misspell` linter which checks for misspelled words in a file.
+
+```lua
+local config = import("micro/config")
+
+function init()
+    -- uses the default linter plugin
+    -- matches any filetype
+    linter.makeLinter("misspell", "", "misspell", {"%f"}, "%f:%l:%c: %m", {}, false, true, 0, 0, hasMisspell)
+
+    config.RegisterCommonOption("misspell", true)
+end
+
+function hasMisspell(buf)
+    return buf.Settings["misspell"]
+end
+```

runtime/plugins/linter/linter.lua

@@ -83,6 +83,7 @@ function init()
     makeLinter("yaml", "yaml", "yamllint", {"--format", "parsable", "%f"}, "%f:%l:%c:.+ %m")
 
     config.MakeCommand("lint", "linter.lintCmd", config.NoComplete)
+    config.AddRuntimeFile("linter", config.RTHelp, "help/linter.md")
 end
 
 function lintCmd(bp, args)

runtime/plugins/status/help/status.md

@@ -0,0 +1,15 @@
+# Status
+
+The status plugin provides some functions for modifying the status line.
+
+Using the `statusformatl` and `statusformatr` options, the exact contents
+of the status line can be modified. Please see the documentation for
+those options (`> help options`) for more information.
+
+This plugin provides the three functions that can be used in the status
+line format:
+
+* `status.branch`: returns the name of the current git branch.
+* `status.hash`: returns the hash of the current git commit.
+* `status.paste`: returns "" if the paste option is disabled and "PASTE"
+   if it is enabled.

runtime/plugins/status/status.lua

@@ -8,6 +8,7 @@ function init()
     micro.SetStatusInfoFn("status.branch")
     micro.SetStatusInfoFn("status.hash")
     micro.SetStatusInfoFn("status.paste")
+    config.AddRuntimeFile("status", config.RTHelp, "help/status.md")
 end
 
 function branch(b)
@@ -19,6 +20,7 @@ function branch(b)
         if err == nil then
             return strings.TrimSpace(branch)
         end
+        return ""
     end
 end
 
@@ -31,6 +33,7 @@ function hash(b)
         if err == nil then
             return strings.TrimSpace(hash)
         end
+        return ""
     end
 end