Using Page-Breaks in GNU Emacs

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.

We use C-x [ and C-x ] to move backward and forward through pages, respectively. Those keys, by default, invoke the backward-page and 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.

Conclusion

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.

Advertisements

5 thoughts on “Using Page-Breaks in GNU Emacs

  1. Pages are great, and useful in lots of places. Here’s one example: Emacs is my IRC client (using the erc library), so I run the following in erc-mode-hook so that I can easily navigate between days:


    (setq-local page-delimiter ;; e.g. [Fri Jan 5 2013]
    (rx (sequence
    "[" (or "Mon" "Tue" "Wed" "Thu" "Fri" "Sat" "Sun")
    " " (or "Jan" "Feb" "Mar" "Apr" "May" "Jun"
    "Jul" "Aug" "Sep" "Oct" "Nov" "Dec")
    " " (optional " ") (repeat 1 2 digit)
    " " (= 4 digit) "]")))

  2. This is interesting, thanks for sharing. If I weren’t already using outline-minor-mode and outshine, I might consider using these packages, but I really love outline-minor-mode for coding in Emacs. It allows you to divide any file into sections using org-mode headings by putting them on lines that start with a comment character. The sections are font-locked using org-mode font settings, so they display just like they do in org-mode. I have them using non-monospaced fonts, usually bold, and in different colors, so they visually stand out from code very well. The sections can also be collapsed just like org-mode subtrees, and they can be navigated to using functions like helm-semantic-or-imenu. And you can even add language-specific code to outline-minor-mode’s regexps to turn things like function/class definitions into headlines, allowing you to collapse classes and functions as well.

    So it lets you get an overview of a file, drill down into sections just like org subtrees, and navigate through the file easily. And the headings are just comments in the file, so they don’t interfere with other editors. I highly recommend looking into it if you haven’t already. :)

Add Your Thoughts

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s