Today I want to talk about the concept of pages in GNU Emacs, how I use them, and why I use them. In my experience pages are often overlooked by Emacs users, most likely because they look ugly, but I will show you a package to deal with that. And along the way I will show you a package that I use to make it easier to navigate between pages.
A Crash Course Introduction to Pages
‘Pages’ in Emacs refers to text separated by the form-feed character, i.e. the
^L character, meaning Ctrl+L. We can type this character by pressing
C-q C-l. Using
C-q tells Emacs to directly insert whatever key you press next. Normally
C-l runs the
recenter-top-bottom command. And so we cannot simply type
C-l to get the form-feed character. But
C-q C-l tells Emacs to ignore any command bound to
C-l and thus inserts a literal
^L, the character we need to separate text into pages.
C-x [ and
C-x ] to move backward and forward through pages, respectively. Those keys, by default, invoke the
forward-page commands. By pressing
C-x C-p we can mark whatever page we are on.
And that’s pretty much it. Later I will come back to talk about some packages to help us navigate pages. But this is all we need to know in order to get started with pages.
Why Use Pages?
I like to use pages, particularly in programming, as a means to divide content into sections. For our game, my studio has recently created the Chance library. The source code has page-breaks dividing each section, although you won’t seem them on GitHub; they will appear as blank lines, e.g. line 228. But in Emacs that page-break line looks like this.
What turns those ugly
^L characters into those pretty horizontal lines? Steve Purcell’s terrific page-break-lines package.
The Chance library uses LDoc for generating its documentation—a form of Javadoc for Lua. In LDoc one can use the
@section markup to group the code into related chunks. I have a page-break directly above each comment block that creates a new
@section. Doing so divides the source code itself into the same sections by treating each section as a page in Emacs.
The result is that I can easily navigate through the source code per-section by using pages. I could use the aforementioned
C-x [ and
C-x ] commands for this navigation, but instead….
A Nicer Way to Navigate Pages
I like to use helm-pages to move between pages in a file. When I invoke
helm-pages in the Chance source code this is what I see. Since it shows the first line on each page this results in an easy, and in my opinion pretty, way to quickly move between sections of the code base. The test suite for Chance uses page-breaks in the same way, and again helm-pages works well since the first line on each page is a call to
describe() which indicates what part of the library that section tests—I use Busted for the unit tests.
A short article, I know, but honestly there’s nothing else to really say. Hopefully this demonstrates how using pages in Emacs can be a useful way to divide-up source code (or any kind of file) and easily navigate to those divisions as needed. If you have never used pages in Emacs then give it a try sometime because, like me, you may find it to be a useful tool for organizing a single file into nice, logical chunks which you can jump between quickly and easily.
Update (15 September 2015): I highly recommend reading info by Artur Balabarba on page-breaks.