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.
Starting a path
Another engineer gave the following challenge: How to open a file
into a new window (splitting) with
Immediately, I knew that I would have to check the full feature set
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
Taking a stroll
Reading the documentation yielded nothing readily availble built
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
find-file-literally since they also seemed to be of little
The only other link is to
files.el. Naturally, I took a
peek. Open source always prides itself on the ability to share the
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
Neither solution was necessary. Following
find-files only a
half-page down was
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
Making a Map
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?