diff options
Diffstat (limited to 'docs/text-encoding.md')
| -rw-r--r-- | docs/text-encoding.md | 40 |
1 files changed, 26 insertions, 14 deletions
diff --git a/docs/text-encoding.md b/docs/text-encoding.md index 71bdada..f299b51 100644 --- a/docs/text-encoding.md +++ b/docs/text-encoding.md @@ -2,7 +2,7 @@ ## Background -The Hotline protocol was designed for classic Mac OS, which used an encoding called Mac Roman for text. Modern operating systems use UTF-8 instead. Mobius automatically translates between these two encodings so that classic Hotline clients and modern filesystems can work together. +The Hotline protocol was designed for classic Mac OS, which used an encoding called Mac Roman for text. Modern operating systems use UTF-8 instead. Mobius translates filesystem names and newly imported feed news so that classic Hotline clients and modern UTF-8 sources can work together. Most other protocol text remains raw bytes. By default, Mobius assumes all clients use Mac Roman encoding. If your server exclusively serves modern UTF-8 clients, you can disable the Mac Roman conversion. This document explains how encoding works and how to configure it. @@ -17,9 +17,20 @@ When a Hotline client uploads, downloads, browses, creates, or renames files and This means files on disk always use UTF-8 names, regardless of what encoding the client uses. You can place files with Unicode names in the server's file directory and clients will see them — as long as the characters have Mac Roman equivalents. -### Chat, news, and usernames are NOT translated +### Server-generated feed news is translated -Text in chat messages, news articles, usernames, and private messages is passed through as raw bytes with no encoding conversion. This means: +RSS and Atom sources are UTF-8 server data rather than client-authored Hotline +text. Mobius encodes each imported article's title, author, and body when it is +first added to `ThreadedNews.yaml`. With the default `macintosh` setting, +characters that Mac Roman cannot represent are replaced. With `utf8`, feed text +is stored unchanged. + +Imported entries become ordinary raw-byte news articles. Changing `Encoding` +therefore affects future imports only; it does not rewrite existing articles. + +### Chat, user-authored news, and usernames are NOT translated + +Text in chat messages, existing news articles, usernames, and private messages is passed through as raw bytes with no encoding conversion. This means: - If all your users are on classic Mac clients, they'll see each other's text correctly (all Mac Roman). - If all your users are on modern UTF-8 clients, they'll also see each other's text correctly. @@ -29,13 +40,13 @@ There is no way to configure this behavior — the Hotline protocol has no mecha ## Configuration -The `Encoding` field in `config.yaml` controls how file and folder names are translated: +The `Encoding` field in `config.yaml` controls how file and folder names and server-generated feed news are translated: ```yaml # Default — translates between Mac Roman and UTF-8 (compatible with classic Hotline clients) Encoding: macintosh -# No-op — passes file names through without conversion (for servers with only modern UTF-8 clients) +# No-op — passes file names and feed news through unchanged (modern UTF-8 clients only) Encoding: utf8 ``` @@ -59,12 +70,13 @@ Modern Hotline clients that send UTF-8 for file operations may produce unexpecte ## Summary -| What | Encoding translation? | Notes | -|---------------------------|----------------------|-----------------------------------------------| -| File and folder names | Yes | Mac Roman <-> UTF-8 at the filesystem boundary | -| Chat messages | No | Raw bytes, passed through as-is | -| News articles and titles | No | Raw bytes, passed through as-is | -| Usernames | No | Raw bytes, passed through as-is | -| Private messages | No | Raw bytes, passed through as-is | -| File comments | No | Stored and retrieved as raw bytes | -| Login credentials | No | Obfuscated, no charset conversion | +| What | Encoding translation? | Notes | +| --- | --- | --- | +| File and folder names | Yes | Mac Roman <-> UTF-8 at the filesystem boundary | +| Newly imported feed articles | Yes | UTF-8 source text -> configured encoding at import time | +| Chat messages | No | Raw bytes, passed through as-is | +| Existing and user-authored news articles | No | Raw bytes, passed through as-is | +| Usernames | No | Raw bytes, passed through as-is | +| Private messages | No | Raw bytes, passed through as-is | +| File comments | No | Stored and retrieved as raw bytes | +| Login credentials | No | Obfuscated, no charset conversion | |