utf8trans(1)

📦
version 0.8.8 · 2 versions
, in alpine 3.22, alpine 3.23, alpine 3.24, arch rolling, centos-stream 10, centos-stream 9, debian bookworm, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0, ubuntu jammy

💖 utf8trans 💖

okay bestie, welcome to the utf8trans(1) page from the docbook2X crew — she's a tiny little transliteration queen and she's about to eat 💅

✨ NAME ✨

utf8trans — transliterate UTF-8 characters according to a table

🎀 SYNOPSIS 🎀

utf8trans charmap [file]...

🦋 DESCRIPTION 🦋

So here's the vibe: utf8trans takes the characters in the files you list — or from standard input if you don't list any files at all, no pressure — transliterates them, and drops the output on standard output. Everything coming in and everything going out is in UTF-8 encoding. That's the whole contract. Non-negotiable, but also slay. 💜

What is this actually for, you ask? Usually it's used to render characters in Unicode text files as some markup escapes or ASCII transliterations. And before you get any ideas — it is not intended for general charset conversions, bestie. That's not the gig. It provides functionality similar to the character maps in XSLT 2.0 (XML Stylesheet Language – Transformations, version 2.0). So if that's your reference point, you already get it. iykyk. ✨

🌸 OPTIONS 🌸

  • -m, --modify — modifies the given files in-place with their transliterated output, instead of sending it to standard output. This one is genuinely useful for efficient transliteration of many files at once, no cap 🔥
  • --help — show brief usage information and exit. short, sweet, iconic 🫶
  • --version — show version and exit. literally just that 💅

🌈 USAGE 🌈

The translation is done according to the rules in the ‘character map’, named in the file charmap. And it has the following format, so listen up:

  1. Each line represents a translation entry, except for blank lines and comment lines, which are ignored. 🚫
  2. Any amount of whitespace (space or tab) may precede the start of an entry. no rules about indentation, live your life.
  3. Comment lines begin with #. Everything on the same line is ignored. gone, deleted, not invited 💀
  4. Each entry consists of the Unicode codepoint of the character to translate, in hexadecimal, followed by one space or tab, followed by the translation string, up to the end of the line.
  5. The translation string is taken literally, including any leading and trailing spaces (except the delimeter between the codepoint and the translation string), and all types of characters. The newline at the end is not included.
The above format is intended to be restrictive, to keep utf8trans simple. That's the whole design philosophy, bestie — minimal, focused, main character energy 👑

But wait — if a XML-based format is what you're craving, there's a xmlcharmap2utf8trans script that comes with the docbook2X distribution, and it converts character maps in XSLT 2.0 format to the utf8trans format. so you're covered either way 🌸

😭 LIMITATIONS 😭

  • utf8trans does not work with binary files, because malformed UTF-8 sequences in the input are substituted with U+FFFD characters. However, null characters in the input are handled correctly, so at least there's that. This limitation may be removed in the future — manifesting it 🙈
  • There is no way to include a newline or null in the substitution string. nope. can't. not happening. periodt. 💅

👑 AUTHOR 👑

Steve Cheng <stevecheng@users.sourceforge.net>. king behavior fr fr 💜

okay that's the whole page bestie, you're officially a utf8trans girlie now 🎀 this was docbook2X 0.8.8, dated 3 March 2007 — vintage but she still ate 💖✨🦋

📦 where this page comes from