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.
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.
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-regiontitlecase-linetitlecase-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-dwimdoesn’t operate on a region of text.titlecase-lineandtitlecase-sentenceare 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
nilto 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 andtitlecase-normalize-functionsto 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 symbolstyle, which will be replaced by the requested style of title capitalization.
- Function (default:
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 aftertitlecase-force-cap-after-punccharacters.
titlecase-downcase-sentences- When this option is set to
t, thesentencestyle of titlecasing will downcase words past the first one. The default (nil) will leave everything past the first word alone.
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)Title-casing has been attempted before in Emacs:
- Title Case in Emacs, Jason Blevins
Jason actually wrote another
titlecase.elthat shells out to a Perl program by John Gruber and Aristotle Pagaltzis. Users of Jason’stitlecase.elshould be able to use this one with no changes, aside from changing the value oftitlecase-commandfrom 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!
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.
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.
This package is licensed under the terms of the GNU General Public License, version 3. See LICENSE for the full text.