1 .TH catdoc 1 "Version @catdoc_version@" "MS-Word reader"
3 catdoc \- reads MS-Word file and puts its content as plain text on standard output
6 .BR catdoc " [" -vlu8btawxV "] [" -m "
24 but it reads MS-Word file and produces human-readable text on standard output.
27 escape sequences for characters which have special meaning for LaTeX.
28 It also makes some effort to recognize MS-Word tables, although it never
29 tries to write correct headers for LaTeX tabular environment. Additional
30 output formats, such is HTML can be easily defined.
33 doesn't attempt to extract formatting information other than tables from
34 MS-Word document, so different output modes means mainly that different
35 characters should be escaped and different ways used to represent characters,
36 missing from output charset. See CHARACTER SUBSTITUTION below
42 representation of text, so it is able to convert texts when charset in
43 source document doesn't match charset on target system.
44 See CHARACTER SETS below.
46 If no file names supplied,
48 processes its standard input unless it is terminal. It is unlikely that
49 somebody could type Word document from keyboard, so if
51 invoked without arguments and stdin is not redirected, it prints brief
52 usage message and exits.
53 Processing of standard input (even among other files) can be forced using
54 dash '-' as file name.
58 wraps lines which are more than 72 chars long and separates paragraphs by
59 blank lines. This behavior can be turned of by
64 .B catdoc prints each paragraph as one long line, suitable for import into
65 word processors which perform word wrapping theirselves.
71 - shortcut for -f ascii. Produces ASCII text as output.
72 Separates table columns with TAB
75 - process broken MS-Word file. Normally,
76 .B catdoc checks if first 8 bytes
77 of file is Microsoft OLE signature. If so, it processes file, otherwise
78 it just copies it to stdin. It is intended to use
80 as filter for viewing all files with
85 - specifies destination charset name. Charset file has format described in
86 CHARACTER SETS below and should have
88 extension and reside in
89 .B catdoc library directory ( @libdir@/catdoc). By default, current
90 locale charset is used if langinfo support compiled in.
93 - specifies output format as described in CHARACTER SUBSTITUTION below.
95 comes with two output formats - ascii and tex. You can add your own if you
101 to list names of available charsets to the stdout and exit successfully.
104 Specifies right margin for text (default 72).
110 Specifies source charset. (one used in Word document), if Word document
111 doesn't contain UTF-16 text. When reading rtf documents, it is
112 typically not necessary, because rtf documents contain ansicpg
113 specification. But it can be set wrong by Word (I've seen RTF documents
114 on Russian, where cp1252 was specified). In this case this option would
115 take precedence over charset, specified in the document. But
116 source_charset statement in the configuration file have less priority
117 than charset in the document.
122 converts all printable chars, which have special meaning for
124 into appropriate control sequences. Separates table columns by
128 - declares that Word document contain UNICODE (UTF-16) representation
129 of text (as some Word-97 documents). If catdoc fails to correct Word document
130 with default charset, try this option.
133 - declares is Word document is 8 bit. Just in case that catdoc
134 recognizes file format incorrectly.
137 disables word wrapping. By default
139 output is splitted into lines not longer than 72 (or number, specified by
140 -m option) characters and paragraphs
141 are separated by blank line. With this option each paragraph is one
145 causes catdoc to output unknown UNICODE character as \\xNNNN, instead
149 causes catdoc to print some useless information about word document
150 structure to stdout before actual start of text.
153 outputs catdoc version
156 When processing MS-Word file
158 uses information about two character sets, typically different
159 - input and output. They are stored in plain text files in
161 library directory. Character set files should contain two whitespace-separated
162 hexadecimal numbers - 8-bit code in character set and 16-bit Unicode code.
163 Anything from hash mark to end of line is ignored, as well as blank lines.
166 distribution includes some of these character sets. Additional character set
167 definitions, directly usable by
169 can be obtained from ftp.unicode.org. Charset files have
171 suffix, which shouldn't be specified in command-line or configuration
176 is distributed with Cyrillic charsets as default. If you are not
177 Russian, you probably don't want it, an should reconfigure catdoc at
178 compile time or in runtime configuration file.
180 When dealing with documents with charsets other than default, remember
181 that Microsoft never uses ISO charsets. While letters in, say cp1252 are
182 at the same position as in ISO-8859-1, some punctuation signs would be
183 lost, if you specify ISO-8859-1 as input charset. If you use cp1252,
184 catdoc would deal with those signs as described in CHARACTER
187 .SH CHARACTER SUBSTITUTION
189 converts MS-Word file into following internal Unicode representation:
191 1. Paragraphs are separated by ASCII Line Feed symbol (0x000A)
193 2. Table cells within row are separated by ASCII Field Separator symbol
196 3. Table rows are separated by ASCII Record Separator (0x001E)
198 4. All printable characters, including whitespace are represented with their
199 respective UNICODE codes.
201 This UNICODE representation is subsequently converted into 8-bit text in
202 target character set using following four-step algorithm:
204 1. List of special characters is searched for given Unicode character.
205 If found, then appropriate multi-character sequence is output instead of
208 2. If there is an equivalent in target character set, it is output.
210 3. Otherwise, replacement list is searched and, if there is multi-character
211 substitution for this UNICODE char, it is output.
213 4. If all above fails, "Unknown char" symbol (question mark) is output.
215 Lists of special characters and list of substitution are character
216 set-independent, because special chars should be escaped regardless of their
217 existence in target character set (usually, they are parts of US-ASCII, and
218 therefore exist in any character set) and replacement list is searched only
219 for those characters, which are not found in target character set.
221 These lists are stored in
223 library directory in files with prefix of format name. These files have
226 Each line can be either comment (starting with hash mark) or contain
227 hexadecimal UNICODE value, separated by whitespace from string, which
228 would be substituted instead of it. If string contain no whitespace it
229 can be used as is, otherwise it should be enclosed in single or double
230 quotes. Usual backslash sequences like
232 can be used in these string.
235 .SH RUNTIME CONFIGURATION
236 Upon startup catdoc reads its system-wide configuration file (
239 library directory) and then
240 user-specific configuration file
241 .BR ${HOME}/.catdocrc.
243 These files can contain following directives:
245 .BI "source_charset = " charset-name
246 Sets default source charset, which would be used if no
248 option specified. Consult configuration of nearby windows
249 workstation to find one you need.
251 .BI "target_charset = " charset-name
252 Sets default output charset. You probably know, which one you use.
254 .BI "charset_path = " directory-list
255 colon-separated list of directories, which are searched for charset files.
256 This allows you to install additional charsets in your home directory.
257 If first directory component of path is ~ it is replaced by contents of
259 environment variable.
260 On MS-DOS platform, if directory name starts with %s, it is replaced
261 with directory of executable file. Empty element in list (i.e. two
262 consequitve colons) is considered current directory.
264 .BI "map_path = " directory-list
265 colon-separated list of directories, which are searched for special character
266 map and replacement map.
267 Same substitution rules as in
271 .BI "format = " "format name"
272 Output format which would be used by default.
274 comes with two formats -
275 .BR ascii " and " tex
276 but nothing prevents you from writing your own format (set two map files -
277 special character map and replacement map).
279 .BI "unknown_char = " "character specification"
280 sets character to output instead of unknown Unicode character (default '?')
281 Character specification can have one of two form - character enclosed in
282 single quotes or hexadecimal code.
284 .BI "use_locale =" "(yes|no)"
285 Enables or disables automatic selection of output charset (default
288 system locale settings (if enabled at compile time). If automatic
289 detection is enabled, than output charset settings in the configuration
290 files (but not in the command line) are ignored, and current system
291 locale charset is used instead. There are no automatic choice of input
292 charset, based of locale language, because most modern Word files (since
293 Word 97) are Unicode anyway
298 fast-saves properly. Prints footnotes as separate paragraphs at the end of
299 file, instead of producing correct LaTeX commands. Cannot distinguish
300 between empty table cell and end of table row.
314 V.B.Wagner <vitus@45.free.net>
projects / oss / catdoc.git / blob