Highlight portions of your Text in Emacs

Have you ever run across a text document that has an obvious structure but is not an AsciiDoc¹, a reStructuredText¹, a Markdown¹ or an Org-mode¹ or one of the many other text markups¹ that is widely used?  In that case, you might have been frustrated with the lack of highlighting based on syntax.  It is understandable that Emacs cannot provide syntax highlighting for ad-hoc files whose structure is solely determined by someone’s whim.   However, it provides a tool called hi-lock-mode¹ that can come to your aid.

For example, consider the file etc/DEVEL.HUMOR¹.  This document has a clear structure, which is evident even to a casual observer.

The screenshots below show the above file, before and after highlighting.  It is needless to say, that you would find the text with highlighting much more comprehensible than the one without any highlighting.

In this article, you will learn how to achieve the above highlighting.

Step 1: Install a custom menu

Copy the Emacs Lisp snippet¹ below to your .emacs and restart your Emacs.  This snippet adds a submenu named Customize Regexp Highlighting to the Edit menu.

(easy-menu-define my-hi-lock-menu nil "Menu for customizing regexp highlighting."
  `("Customize Regexp Highlighting"
    ["Global Hi Lock Mode"
     (progn
       (customize-set-variable 'global-hi-lock-mode
                   (not global-hi-lock-mode))
       (customize-save-variable 'global-hi-lock-mode global-hi-lock-mode))
     :style toggle :selected global-hi-lock-mode :help "Toggle Hi-Lock mode in all buffers"]
    ["Hi Lock Mode" hi-lock-mode :style toggle :selected hi-lock-mode :help "Toggle selective highlighting of patterns"]
    ["Auto Select Face"
     (customize-save-variable 'hi-lock-auto-select-face
                  (not hi-lock-auto-select-face))
     :style toggle :selected hi-lock-auto-select-face :enable
     (featurep 'hi-lock)
     :help "\"Non-nil means highlighting commands do not prompt for the face to use.\nInstead, each hi-lock command will cycle through the faces in\n`hi-lock-face-defaults'.\""]
    "--"
    ["Customize"
     (customize-group 'hi-lock)]))

(easy-menu-add-item menu-bar-edit-menu nil my-hi-lock-menu)

(with-eval-after-load 'hi-lock
  (define-key-after hi-lock-menu
    [unhighlight-regexp-all]
    `(menu-item "Remove All Highlighting"
        (lambda nil
          (interactive)
          (unhighlight-regexp t))
        :enable hi-lock-interactive-patterns :help ,(documentation 'unhighlight-regexp))
    'unhighlight-regexp))

Step 2: Enable global-hi-lock-mode

Step 3:  Specify text patterns / regexps that you want to highlight

Open DEVEL.HUMOR and tell Emacs that you want to highlight some text patterns, in a specific face.

Pattern / Regexp	Face	What the patterns means
^--.*--$	font-lock-comment-face	Lines that begin and end with two dashes
^-+$	underline	Lines that is made up solely of dashes
^[ \t]+--.*$	font-lock-constant-face	Lines, that are indented which start with two dashes

The screenshot below takes you through the sequence of steps you need to follow for applying the first of the above three patterns.

Once you have added the above 3 patterns for highlighting, you would see that the buffer is highlighted as below.

Step 4: Optionally, save the patterns to buffer

Note that the highlights you created above holds so long as you don’t kill the buffer.  So, if you want to have this file highlighted whenever you re-open the file, then you need to write the patterns and their faces to the file as below.

Now save the file and kill the buffer.

Step 5:  Re-open the file

When you re-open the file, Emacs will ask you permission to highlight the patterns in the buffer.  Once you say y,  Emacs will proceed with required highlights.

Step 6: Further customizations

When you have saved your custom patterns  in a document, you almost always want those patterns to be highlighted whenever you visit the file.  In that case, you might want to customize hi-lock-file-patterns-policy and set it to (lambda (patterns) t) as below.

Step 7: A Gotcha in regard to where you save your patterns

If you are inclined to save the patterns towards the end of the file, simply because it tucks the Hi Lock clutter away from your eyes, you need to be aware that Emacs looks for the highlight patterns within the first 10,000 characters of the file.  So, for the saved highlights to work, you need to be write the patterns close to the beginning of your document.  For the first time this isn’t often a problem.  If the saved patterns aren’t close to the start of the document, Emacs will warn you with Inserted keywords not close enough to top of file and you can take a corrective action.  However, during the lifetime of your file, it is possible that the patterns get moved further away from  the start of the file and the custom highlights stop working.  In that case, you may get confused on why the patterns are not kicking in.  (If you have a keen eye, you would have noted that in the illustrations above you wrote the patterns towards the end of the file.  This is OK, because the file was small, and hopefully it would remain small.)

Concluding Words

In my decades of using Emacs, I never had a need to save text patterns in a file.  This is not because the saved patterns clutters the file and saved highlights are practically useless outside of Emacs.

That said, I find highlighting so much part of the work flow that I always have it on all the buffers.

Another limitation of the Hi Lock Mode, is that you need to be comfortable with Emacs regular expressions¹.  If you aren’t comfortable with regexps, then you may not be able to exploit the best of what this mode offers and be contented with Highlight Lines or Highlight Phrase commands.

In case, if you are a user who doesn’t need highlighting based on regular expressions, but wants highlighting on a case-by-case basis, much like in Office documents, then you may want to try Enriched Mode¹.  Remember, Enriched Mode, even when it is based on standards, is based on standards that hasn’t found any universal adoption.  So, as long as you (and friends that you exchange documents with) are Emacs users, then you wouldn’t have any complaints with Enriched Mode.   For a quick feel for what Enriched Mode has to offer, open the file Enriched.txt¹ that is part of GNU Emacs distribution.