On Documentation in Emacs

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?