Seonbi: SmartyPants for Korean language
=======================================

[![][releases-badge]][releases] [![][hackage-badge]][hackage] [![][dockerhub-badge]][dockerhub] [![][ci-status-badge]][ci]

[![](https://dahlia.github.io/seonbi/showcase.svg)][demo web app]

(TL;DR: See the [demo web app].)

Seonbi (선비) is an HTML preprocessor that makes typographic adjustments
to an HTML so that the result uses accurate punctuations according to
the modern Korean orthography.
(It's similar to what [SmartyPants] does for text written in English.)

It also transforms `ko-Kore` text (國漢文混用; [Korean mixed script]) into
`ko-Hang` text (한글전용; Hangul-only script).

Seonbi provides a Haskell library, a CLI, and an HTTP API; any of them can
perform the following transformations:

 -  All hanja words (e.g., `漢字`) into corresponding hangul-only words
    (e.g., `한자`)
 -  Straight quotes and apostrophes (`"` & `'`) into curly quotes HTML
    entities (`“`, `”`, `‘`, & `’`)
 -  Three consecutive periods (`...` or `。。。`) into an ellipsis entity (`…`)
 -  Classical (Chinese-style) stops (`。` & `、`) into modern (English-style)
    stops (`.` & `,`)
 -  Pairs of less-than and greater-than inequality symbols (`<` & `>`) into
    pairs of proper angle quotes (`〈` & `〉`)
 -  Pairs of two consecutive inequality symbols (`<<` & `>>`) into
    pairs of proper double angle quotes (`《` & `》`)
 -  A hyphen (`-`) or hangul vowel *eu* (`ㅡ`) surrounded by spaces, or
    two/three consecutive hyphens (`--` or `---`) into a proper em dash (`—`)
 -  A less-than inequality symbol followed by a hyphen or an equality
    symbol (`<-`, `<=`) into arrows to the left (`←`, `⇐`)
 -  A hyphen or an equality symbol followed by a greater-than inequality
    symbol (`->`, `=>`) into arrows to the right (`→`, `⇒`)
 -  A hyphen or an equality symbol wrapped by inequality symbols (`<->`, `<=>`)
    into bi-directional arrows (`↔`, `⇔`)

Each transformations can be partially turned on and off, and some
transformations have many options.

All transformations work with both plain texts and rich text tree.
In a similar way to SmartyPants, it does not modify characters within
several sensitive HTML elements like `<pre>`/`<code>`/`<script>`/`<kbd>`.
Chinese/Japanese stops or hanzi/kanji characters inside elements with
`lang="zh"`/`lang="ja"`[^1] are never transformed.

[^1]: Technically, only Korean contents and language-unspecified elements
      are transformed.  Elements having `lang` attribute with language tags
      referring to any Korean language are treated as Korean contents,
      e.g., `ko`, `ko-Hang`, `kor-KP`, `kor-Kore`.

[releases]: https://github.com/dahlia/seonbi/releases
[releases-badge]: https://img.shields.io/github/v/release/dahlia/seonbi
[hackage]: https://hackage.haskell.org/package/seonbi
[hackage-badge]: https://img.shields.io/hackage/v/seonbi
[dockerhub]: https://hub.docker.com/r/dahlia/seonbi
[dockerhub-badge]: https://img.shields.io/docker/v/dahlia/seonbi?label=docker%20image&sort=semver
[ci]: https://github.com/dahlia/seonbi/actions
[ci-status-badge]: https://github.com/dahlia/seonbi/workflows/build/badge.svg
[demo web app]: https://dahlia.github.io/seonbi/
[SmartyPants]: https://daringfireball.net/projects/smartypants/
[Korean mixed script]: https://en.wikipedia.org/wiki/Korean_mixed_script


End-user apps
-------------

Technically, Seonbi is basically exposed as a software component,
which is also known as API (application programming interface), to be used
as a module of other softwares.

However, as these official interfaces are not for humans but machines, it's
not easy to use for end-users whom haven't experienced software
programming.  For such end-users, here's the list of end-user apps:

 -  [Demo web app]: The official web app.  Not that mobile-friendly
    (usable though).
 -  [Seonbi Translator] (선비 번역기): An iOS shortcut made by
    [Heechan Bak] ([@channprj]).
 -  [seonbi-webapp]: Probably aims to replace the official web app.
    Made by Lee Dogeon ([@moreal]).
 -  [seonbi-ext]: A browser extension made by Lee Dogeon ([@moreal]).

[Seonbi Translator]: https://www.icloud.com/shortcuts/1e468a5dd0104fc5b69fe803952fc154
[Heechan Bak]: https://chann.dev/
[@channprj]: https://github.com/channprj
[seonbi-webapp]: https://github.com/moreal/seonbi-webapp
[@moreal]: https://github.com/moreal
[seonbi-ext]: https://github.com/moreal/seonbi-ext


Installation
------------

Seonbi provides official executable binaries for Linux (x86_64), macOS,
and Windows (64-bit).  You can download them from the [releases] page.

It is also distributed as a [Docker image][dockerhub]:

    $ echo '訓民正音' | docker run -i dahlia/seonbi:latest seonbi
    훈민정음

If you want to use it as a Haskell library install the [seonbi][hackage] package
using Stack or Cabal.


CLI
---

The `seonbi` command basically takes the input HTML as standard input, and
then transforms it into the output HTML as standard output:

    seonbi < input.html > output.html

You could pass a filename as an argument instead (and it is `-` by default):

    seonbi input.html > output.html

There is `-o`/`--output` option as well:

    seonbi -o output.html input.html

Although it automatically detects text encoding of the input file,
you could explicitly specify `-e`/`--encoding`:

    seonbi -e euc-kr -o output.html input.html

Although there are several style options, e.g., `-q`/`--quote`, `-c`/`--cite`,
`-r`/`--render-hanja`, in most cases, giving `-p`/`--preset` is enough:

    echo '平壤 冷麵' | seonbi -p ko-kr  # 평양 냉면
    echo '平壤 冷麵' | seonbi -p ko-kp  # 평양 랭면

Read `-h`/`--help` for details:

    seonbi --help


HTTP API
--------

The `seonbi-api` command starts an HTTP server that takes `POST` requests
with an HTML source with transformation options, and responds with
a transformed result HTML.  You can decide a hostname and a port number
with `-H`/`--host` and `-p`/`--port` options:

    seonbi-api -H 0.0.0.0 -p 3800

The following is an example request:

    POST / HTTP/1.1
    Content-Type: application/json
    Host: localhost:3800

    {
      "preset": "ko-kr",
      "contentType": "text/html",
      "sourceHtml": "<p>하늘과 바람과 별과 詩</p>"
    }

The HTTP API server would respond like this:

    HTTP/1.1 200 OK
    Content-Type: application/json
    Server: Seonbi/0.3.0

    {
      "success": true,
      "contentType": "text/html",
      "resultHtml": "<p>하늘과 바람과 별과 시</p>"
    }

If a web app needs to use the HTTP API server, [CORS] should be configured
through `--allow-origin`/`-o` option:

    seonbi-api -o https://example.com

To learn more about parameters interactively, try the [demo web app].

[CORS]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS


Haskell API
-----------

All functions and types lie inside `Text.Seonbi` module and its submodules.
The highest-level API is `Text.Seonbi.Facade` module.

See also the [API docs] or [Hackage].

[API docs]: https://dahlia.github.io/seonbi/docs/


Deno API
--------

There is a simple client library for Deno as well.  See also
the [scripts/deno/](scripts/deno/) directory.


License
-------

Distributed under LGPL 2.1 or later.


Etymology
---------

*[Seonbi]* (선비) means a classical scholar during Joseon periods (14c–19c).
Today there's a meme that calls a person who feels morally superior or has
elitism *seonbi* in the Korean internet.  So *seonbi* and *smarty pants* have
some things in common.

[Seonbi]: https://en.wikipedia.org/wiki/Seonbi