titlecase.el

titlecase.el copied to clipboard

#+TITLE: Titlecase.el #+AUTHOR: Case Duckworth

[[https://melpa.org/#/titlecase][file:https://melpa.org/packages/titlecase-badge.svg]] [[https://stable.melpa.org/#/titlecase][file:https://stable.melpa.org/packages/titlecase-badge.svg]]

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:

  • [[https://www.chicagomanualofstyle.org/book/ed17/part2/ch08/toc.html][Chicago Manual of Style]] :: Used heavily in journalism, and widely used elsewhere.
  • [[https://blog.apastyle.org/apastyle/capitalization/][APA Style Guide]] :: The American Psychological Association's style guide is used in academic papers in the social sciences.
  • [[https://titlecaseconverter.com/rules/#MLA][MLA Handbook]] :: The Modern Language Association publishes a handbook for literary criticism and analysis.
  • [[https://titlecaseconverter.com/rules/#AP][The Associated Press Stylebook]] :: As one of the foremost institutions in American journalism, the AP's style is used by many journalists.
  • [[https://titlecaseconverter.com/rules/#BB][The Bluebook]] :: The Bluebook is the name for the exhaustive law citation guide used by lawyers.
  • [[https://titlecaseconverter.com/rules/#AMA][AMA Manual of Style]] :: The American Medical Association's citation and title capitalization rules are used by many in the scientific community.
  • [[https://www.nytimes.com/2018/03/22/insider/new-york-times-stylebook.html][New York Times Manual of Style and Usage]] :: Designed for the New York Times, this style is also used widely throughout journalism.
  • [[https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style/Titles][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.
  • [[https://en.wikipedia.org/wiki/Letter_case#Sentence_case][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

*** [[https://github.com/oantolin/embark][Embark]]

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

#+begin_src emacs-lisp (define-key embark-heading-map "T" #'titlecase-line) #+end_src

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

#+begin_src emacs-lisp (define-key embark-region-map "T" #'titlecase-region) #+end_src

• References & Prior Art

Title-casing has been attempted before in Emacs:

• [[https://jblevins.org/log/titlecase][Title Case in Emacs]], Jason Blevins

  Jason actually wrote another ~titlecase.el~ that shells out to a [[https://github.com/ap/titlecase][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"~.

• [[http://xahlee.info/emacs/emacs/elisp_title_case_text.html][Emacs: Change to Title Case]], Xah Lee

• [[https://karl-voit.at/2015/05/25/elisp-title-capitalization/][Implementing Proper English Title Capitalization With Emacs Elisp]], Karl Voit

• [[https://github.com/yuutayamada/auto-capitalize-el][auto-capitalize.el]], Yuta Yamada

• [[https://hungyi.net/posts/programmers-way-to-title-case/][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:

• [[https://titlecaseconverter.com/rules/][Title Case Converter]]
• [[https://capitalizemytitle.com/][Capitalize My Title]]
• and others, including those linked in the comments to [[https://old.reddit.com/r/emacs/comments/r1flpw/proper_english_title_case/][this Reddit post]].

There is an [[https://github.com/duckwork/titlecase.el/issues/6][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 [[https://github.com/ideasman42][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.