catdoc(1)

✨ catdoc(1) ✨

okay bestie, gather round, because this is a General Commands Manual page and the command is catdoc and it is lowkey iconic. it lives in the General Commands Manual section, it's a MS-Word reader, and it is about to change your whole text-extraction game. no cap. 💖

---

🌸 NAME 🌸

catdoc — reads MS-Word file and puts its content as plain text on standard output

like, that's it. that's the whole job. and she ate. 💅

---

🎀 SYNOPSIS 🎀

catdoc [-vlu8btawxV] [-m number] [ -s charset] [ -d charset] [ -f
output-format] file

yes the wrapping is weird, that's just how the manpage wrote it, keep it exactly like that bestie ✨

---

🦋 DESCRIPTION 🦋

okay so catdoc behaves much like cat(1), but instead of just dumping bytes at you, it reads an MS-Word file and produces human-readable text on standard output. slay. Optionally, it can use latex(1) escape sequences for characters which have special meaning for LaTeX. It also makes some effort to recognize MS-Word tables, although it never tries to write correct headers for the LaTeX tabular environment. Additional output formats, such as HTML, can be easily defined. very demure, very modular. 🧚

catdoc doesn't attempt to extract formatting information other than tables from the MS-Word document, so different output modes mainly mean that different characters should be escaped and different ways are used to represent characters missing from the output charset. Peep CHARACTER SUBSTITUTION below 👇

catdoc uses an internal unicode(4) representation of text, so it is able to convert texts when the charset in the source document doesn't match the charset on the target system. See CHARACTER SETS below 👇

If no file names are supplied, catdoc processes its standard input unless it is a terminal. It is unlikely that somebody could type a Word document from the keyboard, so if catdoc is invoked without arguments and stdin is not redirected, it prints a brief usage message and exits. Processing of standard input (even among other files) can be forced using a dash - as the file name. periodt. ✋

By default, catdoc wraps lines which are more than 72 chars long and separates paragraphs by blank lines. This behavior can be turned off by the -w switch. In wide mode catdoc prints each paragraph as one long line, suitable for import into word processors that perform word wrapping. main character energy fr fr 🌈

---

✨ OPTIONS ✨

• -a — shortcut for -f ascii. Produces ASCII text as output. Separates table columns with TAB. 💅
• -b — process a broken MS-Word file. Normally, catdoc checks if the first 8 bytes of the file are the Microsoft OLE signature. If so, it processes the file; otherwise it just copies it to stdin. It is intended to use catdoc as a filter for viewing all files with a .doc extension. so messy but so useful 😭
• -dcharset — specifies the destination charset name. The charset file has the format described in CHARACTER SETS below and should have a .txt extension and reside in the catdoc library directory (${prefix}/lib/x86_64-linux-gnu/catdoc). By default, the current locale charset is used if langinfo support is compiled in.
• -fformat — specifies the output format as described in CHARACTER SUBSTITUTION below. catdoc comes with two output formats — ascii and tex. You can add your own if you wish. go off, build your own format 👑
• -l — causes catdoc to list the names of available charsets to the stdout and exit successfully. cute little inventory moment 🎀
• -mnumber — specifies the right margin for text (default 72). -m 0 is equivalent to -w.
• -scharset — specifies the source charset (the one used in the Word document), if the Word document doesn't contain UTF-16 text. When reading rtf documents, it is typically not necessary, because rtf documents contain an ansicpg specification. But it can be set wrong by Word (I've seen RTF documents in Russian where cp1252 was specified). In this case this option would take precedence over the charset specified in the document. But the source_charset statement in the configuration file has less priority than the charset in the document. the drama of it all 💀
• -t — shortcut for -f tex. Converts all printable chars which have special meaning for LaTeX(1) into appropriate control sequences. Separates table columns by &.
• -u — declares that the Word document contains UNICODE (UTF-16) representation of text (as some Word-97 documents). If catdoc fails to correctly read a Word document with the default charset, try this option. she's the emergency backup plan 🫶
• -8 — declares that the Word document is 8 bit. Just in case catdoc recognizes the file format incorrectly.
• -w — disables word wrapping. By default catdoc output is split into lines not longer than 72 (or the number specified by the -m option) characters, and paragraphs are separated by a blank line. With this option each paragraph is one long line.
• -x — causes catdoc to output unknown UNICODE characters as \xNNNN, instead of question marks. no more mystery question marks bestie ✨
• -v — causes catdoc to print some useless information about the Word document structure to stdout before the actual start of the text. (she said useless, not me 🙈)
• -V — outputs catdoc version.

---

🌈 CHARACTER SETS 🌈

When processing an MS-Word file, catdoc uses information about two character sets, typically different — input and output. They are stored in plain text files in the catdoc library directory. Character set files should contain two whitespace-separated hexadecimal numbers — an 8-bit code in the character set and a 16-bit Unicode code. Anything from a hash mark to the end of the line is ignored, as well as blank lines. ✨

The catdoc distribution includes some of these character sets. Additional character set definitions, directly usable by catdoc, can be obtained from ftp.unicode.org. Charset files have a .txt suffix, which shouldn't be specified in command-line or configuration files. important!! don't do it!! 💅

Note that catdoc is distributed with Cyrillic charsets as default. If you are not Russian, you probably don't want it, and should reconfigure catdoc at compile time or in the runtime configuration file. 🎀

When dealing with documents with charsets other than default, remember that Microsoft never uses ISO charsets. While letters in, say, cp1252 are at the same position as in ISO-8859-1, some punctuation signs would be lost if you specify ISO-8859-1 as the input charset. If you use cp1252, catdoc would deal with those signs as described in CHARACTER SUBSTITUTION below. iykyk 😭

---

💖 CHARACTER SUBSTITUTION 💖

catdoc converts an MS-Word file into the following internal Unicode representation:

1. Paragraphs are separated by the ASCII Line Feed symbol (0x000A)
2. Table cells within a row are separated by the ASCII Field Separator symbol (0x001C)
3. Table rows are separated by the ASCII Record Separator (0x001E)
4. All printable characters, including whitespace, are represented with their respective UNICODE codes.

This UNICODE representation is subsequently converted into 8-bit text in the target character set using the following four-step algorithm:

1. The list of special characters is searched for the given Unicode character. If found, then the appropriate multi-character sequence is output instead of the character.
2. If there is an equivalent in the target character set, it is output.
3. Otherwise, the replacement list is searched and, if there is a multi-character substitution for this UNICODE char, it is output.
4. If all of the above fails, the "Unknown char" symbol (question mark) is output.

Lists of special characters and the list of substitutions are character set-independent, because special chars should be escaped regardless of their existence in the target character set (usually, they are parts of US-ASCII, and therefore exist in any character set), and the replacement list is searched only for those characters which are not found in the target character set. the logic is logicking ✨

These lists are stored in the catdoc library directory in files with a prefix of the format name. These files have the following format:

Each line can be either a comment (starting with a hash mark) or contain a hexadecimal UNICODE value, separated by whitespace from a string which would be substituted instead of it. If the string contains no whitespace it can be used as is, otherwise it should be enclosed in single or double quotes. Usual backslash sequences like '\n', '\t' can be used in these strings. 🧚

---

👑 RUNTIME CONFIGURATION 👑

Upon startup, catdoc reads its system-wide configuration file (catdocrc in the catdoc library directory) and then the user-specific configuration file ${HOME}/.catdocrc. two files, one vibe. 💅

These files can contain the following directives:

• source_charset = charset-name — Sets the default source charset, which would be used if no -s option is specified. Consult the configuration of a nearby Windows workstation to find the one you need.
• target_charset = charset-name — Sets the default output charset. You probably know which one you use. 🙈
• charset_path = directory-list — colon-separated list of directories which are searched for charset files. This allows you to install additional charsets in your home directory. If the first directory component of the path is ~ it is replaced by the contents of the HOME environment variable. On the MS-DOS platform, if a directory name starts with %s, it is replaced with the directory of the executable file. An empty element in the list (i.e. two consecutive colons) is considered the current directory.
• map_path = directory-list — colon-separated list of directories which are searched for the special character map and the replacement map. Same substitution rules as in charset_path are applied.
• format = format name — Output format which would be used by default. catdoc comes with two formats — ascii and tex — but nothing prevents you from writing your own format (set two map files: special character map and replacement map).
• unknown_char = character specification — sets the character to output instead of an unknown Unicode character (default '?'). A character specification can have one of two forms — a character enclosed in single quotes, or a hexadecimal code.
• use_locale =(yes|no) — Enables or disables automatic selection of the output charset (default yes), based on system locale settings (if enabled at compile time). If automatic detection is enabled, then output charset settings in the configuration files (but not in the command line) are ignored, and the current system locale charset is used instead. There is no automatic choice of input charset based on locale language, because most modern Word files (since Word 97) are Unicode anyway. okay so the command line always wins, got it 👑

---

💀 BUGS 💀

Doesn't handle fast-saves properly. Prints footnotes as separate paragraphs at the end of the file, instead of producing correct LaTeX commands. Cannot distinguish between an empty table cell and the end of a table row. 😭 she's doing her best okay

---

🫶 SEE ALSO 🫶

xls2csv(1), catppt(1), cat(1), strings(1), utf(4), unicode(4)

the whole friend group, obsessed 🎀

---

⭐ AUTHOR ⭐

V.B.Wagner <vitus@45.free.net>

---

and that's the whole page bestie!! 💖 this one is MS-Word reader, Version @catdoc_version@, dated catdoc(1) — so go forth, extract that text, and slay. 🌸🦋✨👑