diff --git a/hyphenate/info.rkt b/hyphenate/info.rkt index 7f9f2ae2..f25ab2e9 100644 --- a/hyphenate/info.rkt +++ b/hyphenate/info.rkt @@ -1,2 +1,4 @@ #lang info -(define collection "hyphenate") \ No newline at end of file +(define collection "hyphenate") + +(define scribblings '(("scribblings/hyphenate-manual.scrbl" ()))) diff --git a/hyphenate/scribblings/hyphenate-manual.scrbl b/hyphenate/scribblings/hyphenate-manual.scrbl new file mode 100644 index 00000000..55b4c245 --- /dev/null +++ b/hyphenate/scribblings/hyphenate-manual.scrbl @@ -0,0 +1,43 @@ +#lang scribble/manual + +@(require (for-label racket "../main.rkt")) + +@defmodule[hyphenate] + +@title{Hyphenate} + +@author{Matthew Butterick (mb@"@"mbtype.com)} + +An implementation of the Knuth–Liang hyphenation algorithm originally developed for TeX. This version was ported from Ned Batchelder's @link["http://nedbatchelder.com/code/modules/hyphenate.html"]{Python version}. + +@margin-note{I developed this library to handle hyphenation for my web-based book @link["http://practicaltypography.com"]{Butterick's Practical Typography}. Even though support for CSS-based hyphenation is still iffy among web browsers, soft hyphens work reliably.} + +@section{Quick start} + +@section{Interface} + +@defproc[ +(hyphenate +[text string?] [joiner char? @(integer->char #x00AD)] +[#:exceptions exceptions (listof string?) empty]) +string?] +Returns a hyphenated copy of @racket[_text] with @racket[_joiner] inserted at the hyphenation points. By default, @racket[_joiner] is the soft hyphen. + +@margin-note{Unlike a regular hyphen, you only see a soft hyphen when it appears at the end of a line or page as part of a hyphenated word. Otherwise it's invisible.} + +Using the @racket[#:exceptions] keyword, you can pass hyphenation exceptions as a list of words with regular hyphen characters (@racket["-"]) marking the permissible hyphenation points. If an exception word contains no hyphens, that word will never be hyphenated. + +Famously, Knuth & Liang were so confident about their algorithm that they originally released it with only 14 exceptions: @italic{associate[s], declination, obligatory, philanthropic, present[s], project[s], reciprocity, recognizance, reformation, retribution}, and @italic{table}. While their bravado is admirable, it's easy to discover words they missed. + +@defproc[ +(hyphenatef +[text string?] +[pred procedure?] +[joiner char? @(integer->char #x00AD)] +[#:exceptions exceptions (listof string?) empty]) +string?] +Like @racket[hyphenate], but only words matching @racket[_pred] are hyphenated. Convenient if you want to avoid, for instance, capitalized words. + +@section{Caveats} + +@section{License}