/proselint

A linter for prose.

Primary LanguageJavaScriptBSD 3-Clause "New" or "Revised" LicenseBSD-3-Clause

proselint logo

Build Status Code Climate Coverage Status Lint score Dependency Status

Writing is notoriously hard, even for the best writers. Yet there is a tremendous amount of knowledge about the discipline strewn across usage guides, dictionaries, technical manuals, essays, pamphlets, websites, and the hearts and minds of great authors and editors. But poring over Strunk & White hardly makes one a better writer — it turns you into neither Strunk nor White. And nobody has the capacity to apply all the advice from Garner’s Modern American Usage, a 975-page usage guide, to everything they write. In fact, the whole notion that one becomes a better writer by reading advice on writing rests on untenable assumptions about learning and memory. The traditional formats of knowledge about writing are thus essentially inert, waiting to be transformed.

We devised a simple solution: proselint, a linter for prose. (A linter is a computer program that, like a spell checker, scans through a document and analyzes it.)

proselint places the world’s greatest writers and editors by your side, where they whisper suggestions on how to improve your prose. You’ll be guided by advice inspired by Bryan Garner, David Foster Wallace, Chuck Palahniuk, Steve Pinker, Mary Norris, Mark Twain, Elmore Leonard, George Orwell, Matthew Butterick, William Strunk, E.B. White, Philip Corbett, Ernest Gowers, and the editorial staff of the world’s finest literary magazines and newspapers, among others. Our goal is to aggregate knowledge about best practices in writing and to make that knowledge immediately accessible to all authors in the form of a linter for prose.

proselint is a command-line utility that can be integrated into existing tools.

Installation

To get this up and running, install it using pip: pip install proselint.

Usage

You can run proselint on a document:

❯ proselint text.md

This prints a list of suggestions to stdout, one per line. Each suggestion will have the form:

text.md:<line>:<column>: <check_name> <message>

For example,

text.md:0:10: wallace.uncomparables Comparison of an uncomparable: 'unique' can not be compared.

The command-line utility can also print the list of suggestions in JSON using the --json flag. In this case, the output is considerably richer:

{
    // Type of check that output this suggestion.
    check: "wallace.uncomparables",

    // Message to describe the suggestion.
    message: "Comparison of an uncomparable: 'unique' can not be compared.",

    // The person or organization giving the suggestion.
    source: "David Foster Wallace"

    // URL pointing to the source material.
    source_url: "http://www.telegraph.co.uk/a/9715551"

    // Line where the error starts.
    line: 0,

    // Column where the error starts.
    column: 10,

    // Index in the text where the error starts.
    start: 10,

    // Index in the text where the error ends.
    end: 21,

    // start - end
    extent: 11,

    // How important is this? Can be "suggestion", "warning", or "error".
    severity: "warning",

    // Possible replacements.
    replacements: [
        {
            value: "unique"
        }
    ]
}

Available plugins for text editors

proselint is available on:

Checks

You can disable any of the checks by modifying .proselintrc.

ID Description
butterick.symbols Using the right symbol
carlin.filth Words to avoid
consistency.spacing Consistent sentence spacing
consistency.spelling Consistent use of British vs. American spelling
garner.airlinese Avoiding jargon of the airline industry
garner.am_pm Using the right form for the time of day
garner.animal_labels Likening things to animals using fun words
garner.archaism Avoiding archaic forms
garner.back_formations Avoiding needless backformations
garner.capitalization Captializing what ought to be capitalized
garner.cliches Avoiding cliché
garner.commercialese Avoiding jargon of the commercial world
garner.dates Stylish formatting of dates
garner.denizen_labels Calling people the right names
garner.diacritical_marks Using dïacríticâl marks
garner.illogic Avoiding illogical forms
garner.jargon Avoiding miscellaneous jargon
garner.malapropisms Avoiding common malapropisms
garner.many_a Many a singular
garner.misspelling Avoiding common misspellings missed by spell-check
garner.mixed_metaphors Not mixing metaphors
garner.mondegreens Avoiding mondegreens
garner.needless_variants Using the preferred form
garner.oxymorons Avoiding oxymorons
garner.preferred_forms Miscellaneous preferred forms
garner.punctuation Using the right punctuation
garner.redundancy Avoiding redundancy
garner.sexism Avoiding sexist language
gowers.overworked_metaphors Overworked metaphors
inc.corporate_speak Avoiding corporate buzzwords
leonard.exclamation Avoiding hyperbolic use of exclamation
leonard.hell Avoiding a common cliché
lilienfeld.terms_to_avoid Avoiding misused psychological terms
misc.annotations Catching annotations left in the text
misc.chatspeak Avoiding lolling and other chatspeak
misc.credit_card Keeping credit card numbers secret
misc.currency Avoiding redundant currency symbols
misc.hyperbolic Not being hyperbolic
misc.link_checker Linking only to existing sites
misc.password Keeping passwords secret
misc.whence Usage of the word "whence"
nfl.naughty_words Avoiding words banned by the NFL
nordquist.redundancy Avoiding redundancy and saying things twice
norris.denizen_labels Using the right denizen label
ogilvy.pretension Avoiding being pretentious
orwell.debased Avoiding debased language
oxford.venery_terms Call groups of animals by the right name
palahniuk.suddenly Avoiding the word suddenly
pinker.apologizing Being confident
pinker.hedging Not hedging
pinker.latin Avoiding overuse of Latin phrases
pinker.metaconcepts Avoiding overuse of metaconcepts
pinker.narcisissm Talking about the subject, not its study
pinker.scare_quotes Using scare quotes only when needed
strunk_white.composition Avoiding wordy phrases
strunk_white.greylist Words to avoid
strunk_white.usage Misc. usage recommendations
twain.damn Avoiding the word "very"
wallace.tense_present Misc. advice
wallace.uncomparables Not comparing uncomparables
write_good.cliches Avoiding cliches
write_good.lexical_illusions Avoiding lexical illusions
write_good.weasel_words Avoiding weasel words
wsj.athletes Spelling the names of athletes correctly

Contributing

Interested in contributing to proselint? Great — there are plenty of ways you can help. Read more on our website, where we describe how you can help us build proselint into the greatest writing tool in the world.