Titlecase.el

It turns out, capitalizing titles is Hard. This library only does it in English, and even then, it’s pretty jankily put-together. It’s due, mostly, to the fact that many words can mean many different things, depending, and I don’t want to put a whole dictionary in this package just to make capitalizing headings a little easier. Thus, titlecase is the best-effort attempt at capitalizing titles, in English, in Emacs.

By no means is this a panacea! Make sure to copy-edit your writing before you publish it. Remember, computers are stupid.

Installation

Make sure both titlecase.el and titlecase-data.el are in your load-path, and require as per usual. If you use a package manager like package.el or straight.el, that should be done for you.

Note that you will need a package manager that can pull from arbitrary git repositories at the moment (like straight.el), since this package is not currently in any elpa-style repositories.

Use and Customization

titlecase.el exposes four functions for interactive use. Of those, three are fairly self-explanatory, title-casing the region of the buffer in their names:

• titlecase-region
• titlecase-line
• titlecase-sentence

The fourth, titlecase-dwim, will title-case the region, if that’s active, or it’ll call titlecase-dwim-non-region-function, which by default title-cases the current line. You could change that value to titlecase-sentence to have it title-case the sentence around point, of course.

Speaking of customization, here are the current customization options. They are all exposed in the titlecase group, which is a sub-group of text in Emacs’s Customization interface. Do note that the utility of customizing many of these variables is dubious at best, and the titlecase library has been written with the best efforts to keep with well-accepted title-casing styles.

titlecase-dwim-non-region-function

What function to call when titlecase-dwim doesn’t operate on a region of text. titlecase-line and titlecase-sentence are good choices, but this can be any function.

titlecase-force-cap-after-punc

This is a regular expression that will force the next word in the title to be capitalized. It defaults to the common punctuation marks of all the styles.

titlecase-normalize-functions

A list of functions to call before title-casing a region in order to normalize its text. The default value converts a region in ALL-CAPS to lowercase before processing, but you could set this variable to nil to avoid that, or even add more pre-processing functions.

titlecase-skip-words-regexps

A list of regexps to skip completely when title-casing. Defaults to words in all-capitals and URLs (as defined by browse-url-button-regexp). Of course, all-capital words in an all-capital region will be downcased in the default normalization step, but of course you can add whatever you want to this list and titlecase-normalize-functions to remedy that. These regexps are combined by separating them with \| in the implementation.

titlecase-command

What command to use for title-casing logic. It can be a function, a string, or a list of strings.

Function (default: titlecase--region-with-style)

An Emacs Lisp function will be called with three arguments: the beginning and end of the region to title-case, and the desired style as a symbol.

String

A string will be interpreted as the path to an external shell command. The text to title-case will be passed to this command as standard input, and replaced with the command’s standard output. If the command fails for some reason, the bell will ring and the text will remain unchanged.

List of strings

If you have a complex command-line to title-case a string, you can pass a list of strings of the form ("<COMMAND>" ["<ARG>" 'style]...) where <COMMAND> is the name of the command, and the rest of the list is either <ARG> command-line arguments or the symbol style, which will be replaced by the requested style of title capitalization.

titlecase-style

The style of title-casing to use. See Notes.md for a longer discussion of how hard title-casing can be. As of this writing, the following styles are available:

Chicago Manual of Style

Used heavily in journalism, and widely used elsewhere.

APA Style Guide

The American Psychological Association’s style guide is used in academic papers in the social sciences.

MLA Handbook

The Modern Language Association publishes a handbook for literary criticism and analysis.

The Associated Press Stylebook

As one of the foremost institutions in American journalism, the AP’s style is used by many journalists.

The Bluebook

The Bluebook is the name for the exhaustive law citation guide used by lawyers.

AMA Manual of Style

The American Medical Association’s citation and title capitalization rules are used by many in the scientific community.

New York Times Manual of Style and Usage

Designed for the New York Times, this style is also used widely throughout journalism.

Wikipedia Manual of Style

These are the rules agreed upon by the myriad Wikipedia editors for articles on “The World’s Largest Encyclopedia.” Because of the free ideals of Wikipedia, this is titlecase.el’s default style.

Sentence case

The preferred style of the author, sentence casing simply capitalizes titles like written English sentences. Due to the implementation of titlecase-region-with-style-impl, and due to my tastes, sentence style will still capitalize words after titlecase-force-cap-after-punc characters.

titlecase-downcase-sentences

When this option is set to t, the sentence style of titlecasing will downcase words past the first one. The default (nil) will leave everything past the first word alone.

Integration with other packages

Embark

Omar Antolin’s excellent Embark package works well with titlecase. You can bind titlecase-line to embark-heading-map:

(define-key embark-heading-map "T" #'titlecase-line)

Or you can bind titlecase-region to embark-region-map:

(define-key embark-region-map "T" #'titlecase-region)

References & Prior Art

Title-casing has been attempted before in Emacs:

• Title Case in Emacs, Jason Blevins

  Jason actually wrote another titlecase.el that shells out to a Perl program by John Gruber and Aristotle Pagaltzis. Users of Jason’s titlecase.el should be able to use this one with no changes, aside from changing the value of titlecase-command from the new default to "titlecase".

• Emacs: Change to Title Case, Xah Lee
• Implementing Proper English Title Capitalization With Emacs Elisp, Karl Voit
• auto-capitalize.el, Yuta Yamada
• The Programmer’s Way to Write in Title Case Using Emacs Lisp, Hung Yi
• and I’m sure others

This package aims to be different by being more comprehensive and providing mechanisms to choose between capitalization styles. The following resources have been valuable to accessing and parsing the various style’s arcane capitalization rules:

• Title Case Converter
• Capitalize My Title
• and others, including those linked in the comments to this Reddit post.

There is an open issue to add a titlecase-endpoint function to this package, so if web-based title-casing is your bag, please contribute!

Contributing & Hacking

Please contribute! This is a herculean effort, so feel free to open issues, pull requests, whatever. I’m excited to hear from you!

To add another style to titlecase-styles, you’ll want to look at titlecase-data.el.

Thanks

Big big thanks to ideasman42, for all of your testing and ideas. I really appreciate it! Thanks also to everyone who’s contributed issues, code, and suggestions to this package.

License

This package is licensed under the terms of the GNU General Public License, version 3. See LICENSE for the full text.