Update vim-mkbuild blog post.

diff --git a/in/blog/vim-mkbuild.md b/in/blog/vim-mkbuild.md
index 8e0e8aaef8322d8f268fd41f47064b6096f3ba62..f3a6c7920b354a481ee9d2ad814f9b84db68e0ec 100644 (file)
--- a/in/blog/vim-mkbuild.md
+++ b/in/blog/vim-mkbuild.md
@@ -2,102 +2,102 @@ title: vim-mkbuild
 linktitle: vim-mkbuild
 parent: 2016-01
 ctime: 2016-01-18
-mtime: 2016-01-18
+mtime: 2016-03-03
 
 # vim-mkbuild
 
-vim-mkbuild is a vim plugin for supporting code navigation when using the
-[mkbuild] build system.  Builds in [mkbuild] are performed for a specific
-platform, with each successful build generating both a ctags tags file and a
-cscope database.  Vim users can leverage these references by using the
-vim-mkbuild plugin.  This plugin supports three principal use cases:
+[[vim-mkbuild]] is a vim plugin that enhances code navigation for projects using
+the [[mkbuild]] build system.  When building an application for a particular
+platform (embedded target), [[mkbuild]] generates platform specific ctags and
+cscope database files.  [[vim-mkbuild]] leverages these files to provide the
+following three features:
 
-* Identify which component implementations were selected for build of a given
-  platform, and
+* Activate cross reference databases for a compiled platform, selecting from the
+  list of available compiled platforms;
 
-* Browse the code base through identifiers rather than solely by file.
+* Open a file selected from only those source code files compiled when buildng
+  for the selected platform; or
 
-* Browse the code based on a file basis, either selecting from all project
-  files, or only those used in the build for a specific platform.
+* Open a file selected from all files within the application project, including
+  files from any external repositories referenced by the application's `extrefs`
+  file.
 
-The plugin source is available [here](/gitweb/?p=vim-mkbuild.git;a=summary).
+[[vim-mkbuild]] presents lists of platforms and/or files to the developer using
+the excellent [Unite! plugin for vim](https://github.com/Shougo/unite.vim).  The
+[[vim-mkbuild]] plugin source is available
+[here](/gitweb/?p=vim-mkbuild.git;a=summary).
 
-## Selecting from available cross reference databses
+## Selecting a platform for cross reference databases
 
-Two of the three use cases above require the input of a platform, which has been
-built using mkbuild, for selection of the generated cross reference databases.
-This feature is provided by the custom Unite! source mkbuild/xref provided by
-vim-mkbuild.  An example of a mapping for its use:
+[[vim-mkbuild]] provides a Unite! source, `mkbuild/xref`, used to select cross
+reference databases for any platform for which the current application code has
+been built.  This source lists all such platforms, and selecting a platform
+loads its cross reference databases.  The mapping we use to run Unite! on the
+`mkbuild/xref` source is `<leader>x`, where x is a mnemonic for "cross
+reference".
 
     nnoremap <leader>x :<C-u>Unite -buffer-name=xrefs mkbuild/xref<cr>
 
-Invoking Unite! using the above mapping will open a vim split populated with all
-of the available platform build directories.  The developer will see in this
-list all platforms that have been compiled for the current application.
-Selecting one of the listed platforms will activate its cross reference
-databases.
+[[mkbuild]] cross references are based only on files actually compiled for the
+given platform.  All other project files are ignored.  This is quite useful for
+[[mkbuild]] based applications which tend to both target multiple platforms and
+use shared libraries containing code supporting many applications.
 
 ## Navigating code by identifier
 
-Once the cross reference databases are loaded, the standard vim ctags and cscope
-support becomes available.  For a simple example, typing:
+Once cross reference databases are selected using the platform selection feature
+of [[vim-mkbuild]], vim's full ctags and cscope support becomes usable.  For a
+simple example, typing
 
     :ta main
 
-Will open a buffer for the source code file containing the main() function's
-definition and move the cursor to that definition.  Similarly,
+will open a buffer for the source code file containing the main() function's
+definition, moving the cursor to that definition.  Often more productive, place
+the cursor on any identifier and use vim's "goto tag" function, which we map to
+`g]`, to navigate to the identifier's definition.  Similarly,
 
     :cs f c main
 
-will present a list of code locations where the main() function is called.  If
-there is only one such location, vim immediately jumps to that location.  BTW,
-`cs f c <token>` means (cs)cope (f)ind (c)ode.
+will use the cscope database to jump to the line in the code file containing the
+call to the `main` function.  This is the (cs)cope (f)ind (c)ode function.  It's
+often more productive to use a mapping to access this cscope feature.  The
+standard mapping for cscope find code is `<C-\>c` (control backslash, then c).
 
-The publicly available unite-tags plugin for vim provides a Unite! source that
-searches through the contents of the active tags file(s).  This is useful
-because the built-in tags search mechanisms in vim assume one knows some part of
-the identifier of interest starting at its first character.  Unite! and the
-unite-tags plugin offers a fuzzy search.  A useful mapping is:
+Plugins that extend vim's tag features, like unite-tags, work perfectly well
+with [[vim-mkbuild]].  We use unite-tags with the following mapping.  unite-tags
+can become slow on code bases of non-trivial size.
 
     nnoremap <leader>ut :<C-u>Unite -start-insert -buffer-name=tags tag<cr>
 
 ## Navigating code by source code unit
 
-vim-mkbuild also allows for navigating the application source code, including
-any referenced shared code repositories by providing two Unite! sources:
-mkbuild/file and mkbuild/file\_xref
-
-### mkbuild/file
-
-This source provides Unite! with a list of all files, regardless of whether they
-were used as part of a specific build.  This means this source is available
-whether or not a cross reference has been selected via the `mkbuild/xref` source.
-It also means the list of source files presented is unaffected by the
-cross reference selection.  A possible mapping for its use:
-
-    nnoremap <leader>E :<C-u>Unite -start-insert -buffer-name=files mkbuild/file<CR>
-
-Selecting a file through this source opens the file in vim.
-
-Another benefit of this source is that it includes all files, including those
-that aren't directly part of the compilation process.  An example is each
-component's import.mk file.
+[[vim-mkbuild]] allows for fast file select and open in vim through two custom
+Unite! sources: `mkbuild/file` and `mkbuild/file_xref`.  These sources define
+the list of files through which Unite! can search.  Unite!'s file search is very
+powerful; use it and you probably won't want to return to what you used before.
+See Unite!'s [github page](https://github.com/Shougo/unite.vim) for more
+information.
 
 ### mkbuild/file\_xref
 
-When a cross reference is not selected, this Unite! source falls back to working
-just like the `mkbuild/file` source.  However, if a cross reference is active,
-then only the files used for the selected platform are presented for searching.
-A possible mapping for its use:
+The `mkbuild/file_xref` Unite! source includes only the list of souce code
+files compiled when building the application for the selected platform.  We use
+the mapping `<leader>e` to use this Unite! source, as a mnemonic for "edit
+file".
 
     nnoremap <leader>e :<C-u>Unite -start-insert -buffer-name=files mkbuild/file_xref<CR>
 
-Selecting a file through this source opens the file in vim.
+If no platform has been selected, then `mkbuild/file_xref` behaves just like
+`mkbuild/file`, described below.
+
+### mkbuild/file
 
-This plugin is quite useful.  If, for example, a shared library has several
-implementations of the same logical component, only the source units of the
-implementation actually used by the compilation of the platform selected via the
-`mkbuild/xref` source will be available for searching.  The down-side of this
-method is that indirect files, such as platform .mk files, are not available via
-this method.
+This Unite! source provides the list of project files in the application
+directory, and those in any referenced repositories, independent of any platform
+selection via `mkbuild/xref`.  This includes files that are part of the project
+but never compiled, such as makefiles, documentation, etc.  We use the mapping
+`<leader>E` to use this Unite! source.  The mnenomic is "edit file", with the
+capitalized E indicating all files.
+
+    nnoremap <leader>E :<C-u>Unite -start-insert -buffer-name=files mkbuild/file<CR>