Emacs boasts built-in documentation. What does it mean to be built-in? In this case, the documentation is tightly coupled with the code at a function granularity. This means that every time a function changes, the opportunity to update documentation arises.

Ink is better than the best memory. – Chinese proverb

This method facilitates up-to-date documentation for function specifics. But there are other types of documentation necessary. Categories of functionality, frequently used sets, or even user-defined are all ways to look at classes of commands.

How does a user learn what is available? For me, it is exploration.

Another engineer gave the following challenge: How to open a file into a new window (splitting) with C-x C-f.

Immediately, I knew that I would have to check the full feature set of find-file (usually bound to C-x C-f). Would there be an extra argument supplied by C-u? Or maybe a function wrapper was in order? I was also excited about the possibility of sharing how functions can be advised to perform additional tasks. Or maybe this is something that would fit into function hooks.

What I knew for sure is that the path started with C-x C-f. A quick trip to C-h k and I read the right documentation

Reading the documentation yielded nothing readily availble built into find-file.

What I do next is quickly scan the help text for any hyperlinks to additional documentation or files. I skipped Tramp as that wasn't what I wanted. I also skipped the links to file-file-wildcards and find-file-literally since they also seemed to be of little use.

The only other link is to files.el. Naturally, I took a peek. Open source always prides itself on the ability to share the implementation details.

Initially, I was looking to see how hard it would be to wrap find-files to split the window. I was then going to choose between writing a wrapper to rebind to C-x C-f or advising find-files.

Neither solution was necessary. Following find-files only a half-page down was find-file-other-window.

Reading the documentation string indicated that this was exactly the function I needed.

With my function in hand, all I had to do now was find any default bindings. If none existed, then I would have some decisions to make.

Again using the built-in documentation via C-h C-f, I found that it was in fact already bound. C-x 4 C-f or C-x 4 f will open a file in the other window splitting first if necessary.

In this case, the dynamic built-in documentation presented me with existing options.

I'm always interested if there is more on the topic. Once I had my function name, the know-it-all Google provided me with additional commentary on the function.

In the Emacs manual, section 18.2 talks of Visiting Files. Here is where I found my category of alike functions. Now I know how to quickly open a file read-only, in a different window, closing a buffer first or even in a separate frame.

I also know it is in my included Emacs manual through info.

This is positive story with a desired outcome. I wonder, though, how many new users would be able to do the same. I think they would find it difficult.

My next thoughts are how to enable them to find similar paths for their issues. What skills do they need? What trailheads can I give them? How can I help them from feeling lost?

What paths will they take?

Download the 32-bit version (this seems to be the default by other tools) and install it on your system. The binary ends up being somewhere like:

C:/Program Files/gs/gs9.14/bin

Add this location to your path ensuring that all programs can find gswin32c.exe.

One of the key insights is that dvipng does not support tikz, but imagemagick does. Or, more correctly, the convert.exe program will convert the pdf output into a regular image file.

The Imagemagick download page has instructions for installing the binaries and dealing with any issues.

The installer should also setup the path to the executables correctly.

This ended up being the trickiest part for figuring out what to set, but easy settings to make.

The first part sets up tikz as one of the default packages for LaTeX processing. Then, enable the tikzpicture environment for previewing.

(add-to-list 'org-latex-packages-alist
  '("" "tikz" t))

  (eval-after-load "preview"
  '(add-to-list 'preview-default-preamble "\\PreviewEnvironment{tikzpicture}" t))
  

Together those two pieces enable LaTeX to do its thing to make the picture. What is missing now is the processing of the pdf output into an image format.

The two options for images are dvipng or imagemagick. It turns out that the former cannot handle tikz, so we use imagemagick. Setting the default program here is simple too.

(setq org-latex-create-formula-image-program 'imagemagick)
  

After you complete these steps, a simple C-c C-x C-l will preview the sections. And a C-c C-c will turn them back to the source text.

• Installing a TeX system
• Adding LaTeX header options

The export step is really quite easy. Just do a C-c C-e followed by h H for HTML export into a new buffer. The nice touch is that this is also added to the clipboard.

For my purposes, I keep several meetings in one project file. Before exporting, I narrow the tree to just the agenda or minutes that I want to send. Then, I export the narrowed scope.

I keep meeting entries like the following example.

* TODO WW01 Awesome Meeting
  ** Awesome Agenda
  - foo
  - foo
  - foo
  ** Awesome Minutes
  - bar
  - bar
  - bar
  

Most of my communication work happens through Outlook (2013). That means that if I wanted, I could send a HTML email to preserve any formatting from org-export.

And that is just what I do. The following VBA code gets added to Outlook first.

Sub AppendClipboardHTML()
  Dim email As Outlook.MailItem
  Dim cBoard As DataObject

  Set email = Application.ActiveInspector.CurrentItem
  Set cBoard = New DataObject


  cBoard.GetFromClipboard
  email.HTMLBody = email.HTMLBody + cBoard.GetText

  Set cBoard = Nothing
  Set email = Nothing

  End Sub
  

To add to Outlook, hit Alt-F11 to bring up the VBA editor. In there, I just add a new module and copy in the function from above.

This function only makes sense in context of an email. To enable it there, I add it to the quick access toolbar at the top. Press Alt-S-m to open up a new email. Then select the little down arrow for "Customize Quick Access Toolbar" and select "More Commands".

The next window will have a dropdown box to select the command source. Choose Macros to see a list of your macros within outlook.

Now, simply click on the Add >> button to put it into the list of commands available at the top of emails. The Modify… button will allow you to change the icon or command name.

Now clicking on that button will copy clipboard contents into the email as html. Our raw HTML exported from Orgmode gets inserted nicely and we gain the formatting desired.

The other bonus (or maybe the main point) is that now you can also use a built-in shorcut for the Quick Access Toolbar commands to run this one. By pressing Alt, you can see a number by your command.

For me, it is 1 so Alt-1 will run this command for me. I can keep my meetings organized in Emacs and still use Outlook for communication.

M-` is very cool for navigating Emacs menus.

Emacs always has a few surprises left for me. I typically run in a minimal mode with scrollbars, the toolbar and the menu turned off. I also find my self working in a non-windowed (terminal) version of emacs often.

However, I do find it useful to see what menu options are available for given mode. These options can point to commands that I never knew existed and get me one step more integrated into the environment.

Because I run in a simplified viewing environment, turning on the menu to see the options has been, well, a process. Ahh… If only Emacs had a "Text Mode Menu Bar".

It does. And it has a default global key, M-`, which runs tmm-menubar. From there, the interface is easy enough to understand (it also tells you how to interact).

Now I have an easy, built-in way to navigate menus without cluttering up my visuals.

Now a note-taker in the meeting faces the issue of tracking all of the comments and issues given by the reviewers. This can be a tedious task. First, get the line with the issue, capture the issue and assign a priority. All of this goes into a list for the author to consider when fixing the codebase.

Org-mode makes this task much easier with its ability to capture issues quickly and with context. With a keystroke, a scribe can more easily fill in the details given and assign a priority. The following code sets up some templates to use for the review. The bugs have a priority and fall under the "Issues" heading while the questions get put under the "Questions" heading.

(org-remember-insinuate)
  (define-key global-map "\C-cr" 'org-remember)
  (setq org-remember-templates
  '(("Code Review High" ?h "* TODO [#A] %?\n  %i\n  %a" "~/Review.org" "Issues")
  ("Code Review Medium" ?m "* TODO [#B] %?\n  %i\n  %a" "~/Review.org" "Issues")
  ("Code Review Low" ?l "* TODO [#C] %?\n  %i\n  %a" "~/Review.org" "Issues")
  ("Code Review Question" ?? "* TODO %?\n  %i\n  %a" "~/Review.org" "Questions")))
  

Note that I used org-remember (instead of org-capture) because my coworkers are on emacs 23.2 so I had to be compatible wit the default version of org-mode for that emacs version.

There is one additional sticking point to discuss for this solution. The links produced are really a search string within the file. That means that if there are two lines with the same content, the link would find only the first occurrence of the line. The main concern is that a comment on a later line could link (accidentally) to an earlier line. There are two ways to look at this. First, you may feel that the issue is the same regardless of the line (if they are the same lines), so linking to one over the other is a minor detail. Or, you may feel that the exact line is the important item to capture and, in that case, you would need a line number.

There is a way to link using only line numbers. Use the code shown below to create the file search string from the line number.

(defun my/linenum()
  "Use line number as the file linking item"
  ;; Optionally, predicate this technique to
  ;; only certain modes
  ;; e.g.
  ;; (when (eq major-mode 'cperl-mode) ...
  (number-to-string (org-current-line)))
  (add-hook 'org-create-file-search-functions
  'my/linenum)
  

As indicated by the comments, this linking stragety can also predicate on the major mode used for finer control.

Once setup is complete, simply follow along in the source code. When an issue or question comes up, hit C-c r and select the proper template. Fill in the details and complete the entry. You will be back in the source code buffer ready to consider the next issue.

After the review, you can easily sort the issues by priority. Go to the header for the issues and hit C-c ^. A prompt will ask you how to sort. In this case, select priority and the list sorts correctly.

The TODO items make it easy for the author to track the progress against the review tasks.

The templates themselves could provide more information about the given issues in the review.