WP2X(1)

💖 WP2X(1) 💖

from the General Commands Manual, and she's lowkey a whole icon 🫶

🌸 NAME 🌸

wp2x — A WordPerfect 5.0 to whatever converter

✨ SYNOPSIS ✨

wp2x [ -s ] [ -v ] [ -nblip ] configfile wpfile

🦋 DESCRIPTION 🦋

Okay bestie, so wp2x is literally intended to convert simple files stored in WordPerfect 5.1 format into any other document processing language that uses plain text files. It's giving TeX, LaTeX, troff, GML and HTML — the whole text-format friend group, no cap. 💅

For a quick result without manual configuration — and bestie, that's the main character energy move — you can try the following command to convert a WP file into HTML:

wp2x html foo.wp > foo.html

wp2x reads a configuration file and a WordPerfect 5.1 input file, and uses the information in them to produce an output file, which is sent to stdout. I'm obsessed with that. If the configuration file cannot be found, a suffix of .cfg is appended. The current directory is searched, as well as the lib directory specified by the WP2X_DIR variable in the Makefile (iykyk). (Usually /usr/local/lib/wp2x) and the directories specified by the environment variables PATH, DPATH, and WP2XLIB. 👑

Some codes are not translated because documents that require these codes typically would require significant hand-editing. Hence, there's no point in trying to emulate something you're going to delete anyway. fr fr. 😭

Remember, wp2x is not intended to be used as an automated conversion program. Rather, it is intended to be used as a single step in the document conversion process, which gets most of the the grunt work of conversion done and out of the way, so that you can concentrate your efforts on converting the trickier parts of the document. The object of the game is to produce a readable conversion, rather than a perfect conversion. periodt.

As the program runs, a dot is printed to stderr for every 1024 characters converted. This can be suppressed with the -s switch, and the interval between dots can be changed with the -n switch. ✨

🎀 OPTIONS 🎀

Vibe check: these options are giving control freak, but in the cutest way. 👑

• -s — ngl, it suppresses all non-error output to stderr, including the typeout banner, the progress dots, and warnings about undefined expansions.
• -nblip — Every blip tokens, a dot is emitted to stderr, unless the -s switch is given. The value blip must appear immediately following the -n without an intervening space. If no -n switch is supplied, then a value of 1024 is assumed.
• -v — prints the version number and the program usage.

💅 USAGE 💅

okay bestie so here's the tea: the configuration file is literally the main character that controls how the file gets converted from WordPerfect 5.1 format. every single line of that config file looks like this:

identifier="list of codes"

where that list of codes is a string that gets dropped into the output stream every time the matching WordPerfect code shows up. slay. standard C-style backslash-escape sequences are recognized, plus \xFF for hex values. and good news — you do not have to backslash-protect a newline. some identifiers hand you replaceable parameters, and you interpolate them like this:

• %1 — interpolate first parameter as a decimal integer. 💯
• %2 — interpolate second parameter as a decimal integer.
• %c — interpolate first parameter as an ASCII character.
• %\n — interpolate a newline if the most-recently-output character was not already a newline. (the \n can be either the C-style escape sequence, or an actual newline character.) use this if the expansion must take place at the beginning of a line. (like, for example, troff control characters have to appear as the first character in the line in order to take effect, iykyk.) this sequence is meaningful only at the beginning of the string — if it shows up anywhere else, it's flagged as erroneous. 🚩
• %% — interpolate a percent-sign.

a percent sign followed by any other character? considered an error, periodt. and it's also an error to interpolate a parameter that isn't applicable to the identifier you're defining. but the fun part: you may interpolate the parameters as many times as you want, in whatever order you want. (with the one exception of the %\n code, bestie.)

---

here follows the list of accepted identifiers. in the discussion, %1 means the first parameter and %2 means the second. and remember that the character version of %1 is available as %c. 🎀

• BEGIN — Expanded at the beginning of the file.
• END — Expanded at the end of the file.
• COMMENT — Expanded when wp2x needs to insert a comment into the output. The comment is passed as %s.
• PageNo — Insert current page number
• RomanPage — Set page number to %1, and set roman-numeral mode
• ArabicPage — Set page number to %1, and set arabic-numeral mode
• Tab — What to do when you see a tab character.
• BeginTabs — Emitted when tab settings are about to change. The BeginTabs code should delete all existing tabs and prepare for new tab settings to start. All tab values are given in columns measured from the physical left edge of the paper. (Not from the left margin.) 👀
• SetTab — Set a normal (left-justified) tabstop at column %1.
• SetTabCenter — Set a centered tabstop at column %1.
• SetTabRight — Set a right-justified tabstop at column %1.
• SetTabDecimal — Set a decimal tab at column %1.
• EndTabs — Finish the setting of tabstops.

so for example, if the WordPerfect file contains a code that says Set new tabstops as follows: Regular tab at column 15, a centered tab at column 40, a right-justified tab at column 59, and a regular tab at column 60, then these expansions get made in succession:

BeginTabs
SetTab(15)
SetTabCenter(40)
SetTabright(59)
SetTab(60)
EndTabs

• HSpace — Hard (nonbreakable) space.
• HPg — Hard page break.
• CondEOP — Force a new page if fewer than %1 half-lines remain on current page.
• HRt — Hard return.
• SRt — Soft return.
• - — Breakable hyphen.
• -- — Breakable hyphen, appearing at the end of a line.
• = — Non-breakable hyphen.
• \- — Discretionary hyphen.
• \-- — Discretionary hyphen, appearing at the end of a line.
• Marg — Set left margin at %1 characters and right margin at %2 characters.
• TopMargin — Set top margin to %1 lines.
• PageLength — Set page length to %1 lines.
• SS — Single spacing.
• DS — Double spacing.
• 1.5S — One-and-a-half spacing.
• TS — Triple spacing.
• LS — Other line spacing. %1 is twice the desired spacing. (like, a request for 2.5-spacing sets %1=5.)
• LPI — Set %1 lines per inch (%1 is either 6 or 8)
• Bold — Begin boldface
• bold — End boldface
• Und — Begin underline
• und — End underline
• DoubleUnd — Begin double underline
• doubleund — End double underline
• Red — Begin redline
• red — End redline
• Strike — Begin strikeout
• strike — End strikeout
• Rev — Begin reverse video
• rev — End reverse video
• Outline — Begin outline text
• outline — End outline text
• Fine — Begin fine font size
• fine — End fine font size
• Over — Begin overstrike font
• over — End overstrike font
• Sup — Begin superscript
• sup — End superscript
• Sub — Begin subscript
• sub — End subscript
• Large — Begin large font size
• large — End large font size
• Small — Begin small font size
• small — End small font size
• VeryLarge — Begin very large font size
• verylarge — End very large font size
• ExtraLarge — Begin extra large font size
• extralarge — End extra large font size
• Italics — Begin an italics font
• italics — End an italics font
• Shadow — Begin shadow font
• shadow — End shadow font
• SmallCaps — Begin small capitals font (fixed width)
• smallcaps — End small capitals font (fixed width)
• UpHalfLine — Advance printer up 1/2 line
• DownHalfLine — Advance printer down 1/2 line
• AdvanceToHalfLine — Advance to absolute vertical position. %1 is what WordPerfect thinks the current vertical page position is, in half-lines. %2 is the desired position, also in half-lines.
• Indent — Expanded when an "Indent" code appears.
• indent — Expanded at the end of an indented paragraph.
• DIndent — Expanded when a "left-and-right-indent" code appears.
• dindent — Expanded at the end of an double indent
• MarginRelease — Margin release. %1 is the number of characters to move left.
• Center — Center current line
• center — End centering
• CenterHere — Center line around current column
• centerhere — End centering
• Align — Begin alignment
• align — End alignment
• AlignChar — Set alignment character
• FlushRight — Begin flush right
• flushright — End flush right
• Math — Begin math mode
• math — End math mode
• MathCalc — Begin math calc mode
• MathCalcColumn — Math calc column
• SubTotal — Do subtotal
• IsSubTotal — Subtotal entry
• Total — Do total
• IsTotal — Total entry
• GrandTotal — Do grand total
• Col — Begin column mode
• col — End column mode
• Fn — Expanded at the beginning of a footnote.
• fn — Expanded at the end of a footnote.
• En — Expanded at the beginning of an endnote.
• en — Expanded at the end of an endnote.
• SetFn# — Set the number for the next footnote to %1.
• FNote# — Footnote number.
• ENote# — Endnote number.
• Figure# — Figure number.
• TableMarker — Insert table of contents here
• Hyph — Enable hyphenation.
• hyph — Disable hyphenation.
• Just — Enable justification.
• just — Disable justification.
• Wid — Enable widow/orphan protection.
• wid — Disable widow/orphan protection.
• HZone — The hyphenation zone. %1 and %2 are the two magical values that WordPerfect uses to control hyphenation. ✨
• DAlign — Set the decimal alignment character to that whose ASCII value is %1. (%c is useful here.)
• Header — Begin header text
• header — End header text
• Footer — Begin footer text
• footer — End footer text
• Supp — Suppress page number/header/footer information for one page. %1 argument is a bit field which describes what sort of suppression is desired. here's what the bits mean, bestie:
  • 1 = all
  • 2 = page number
  • 4 = page numbers moved to bottom
  • 8 = all headers
  • 16 = header a
  • 32 = header b
  • 64 = footer a
  • 128 = footer b
• CtrPg — Center page vertically
• SetFont — Change pitch or font. %1 is the desired pitch. (Negative means proportionally-spaced.) %2 is the font number.
• SetBin — Select paper bin to %1 = 0, 1, ...
• PN0 — No page numbering.
• PN1 — Page number in top left.
• PN2 — Page number in top center.
• PN3 — Page number in top right.
• PN4 — Page number on top outside corners (even/odd).
• PN5 — Page number in lower left.
• PN6 — Page number in bottom center.
• PN7 — Page number in lower right.
• PN8 — Page number on bottom outside corners (even/odd).

---

if no expansion is supplied for an identifier, then nothing is emitted to stdout, but a warning message gets sent to stderr. this warning message will appear at most once per identifier, and you can suppress it completely with the -s option. 🫶

the special identifier typeout makes its replacement text display on the screen every single time the configuration file is read. it's giving identification messages, or reminders to the user. lowkey useful.

a special identifier is any character enclosed in single quotation marks, which represent themselves. for example,

'α'="{\\alpha}"

causes the string {\alpha} to be emitted when an α is encountered. this could also have been written as

'\xE0'="{\\alpha}"

if the character α has ASCII value 0xE0. (which is true for the IBM PC encoding, no cap.)

if no definition exists for a particular special character, it is transmitted undisturbed. but if a special character is encountered from the upper half of the ASCII character set, and if it has no definition, then a warning message is also emitted. (which can be suppressed with the -s option, bestie.)

💀 pro tip: lines beginning with the # character are comments.

💭 NOTES (the lore drop, bestie)

okay so real talk — this whole thing started as an original WP 4.2 to anything translator. and the file format? it has changed a lot between 4.2 and 5.0. like, glow-up of the century. so this translator no longer reads WP 4.2 files, although it could be extended to do so. it just… hasn't been. 🫶

the 5.0+ format starts with a standard header file. there's a four byte magic number at the head of the file, followed by various product and version information. all WordPerfect Corporation utilities use this standard header. see the WPproducts array in wp2x.c. 👑

once the contents of the file have been located, there are three kinds of codes:

1. simple one byte controls (WP 4.2 had only these kinds)
2. fixed length controls
3. variable length controls

there are a large number of undefined types defined for future use. if wp2x detects something it doesn't understand, it can extract the length and skip that code. no panic, just vibes. and there are a number of defined codes that are unimplemented. please see the code, specifically tokens.c where much of the input processing is done. 💅

---

📁 FILES

the sample configuration files in /usr/local/lib/wp2x give you some sort of idea what a production quality configuration file might look like.

not me being honest: they are not intended to be used as-is. they're meant to be modified to suit your particular needs. consider them inspo, not a finished look. ✨

---

👀 SEE ALSO

• tex(1)
• latex(1)
• nroff(1)
• troff(1)
• WordPerfectDeveloper'sToolkit
• getopt(3)

---

🚨 DIAGNOSTICS

the group chat of error messages. here's what each one is telling you:

• Ignoring byte [XX] — indicates that an unimplemented single byte code was ignored. 🙈
• Ignoring fixed [XX] — indicates that an unimplemented fixed length code was ignored.
• Ignoring variable [XX] sub [XX] length — indicates that an unimplemented variable length code was ignored, and gives its length. 📏
• Warning: Expected XX but received XX at pos: YYYY — something is wrong in the input file at byte YYYY.
• Warning: No expansion for XX (C) — a WP code for which no expansion was defined in the config file was encountered.
• Internal error: Invalid escape C — an error occurred while processing an expansion escape (%x substitution). probably it was not a recognized escape, check the config file.
• Fixed Length block [XX] incorrectly terminated by [YY] as pos Z — something is wrong with the input file, a fixed length block was screwed up. 😭
• Reserved code [XX] seen — something that WPC defined as reserved was seen. check with WPC for new meaning.
• Not a recognized file type. — the file did not start with the right WPC magic number. maybe this is a 4.2 file, or not a WordPerfect file at all? 🤔
• Error: Cannot open X (reason) — the file X could not be opened, for the indicated reason.
• Error: Expecting a hex digit — inside a string, you typed the characters \x, but the next character was not a valid hex digit.
• Error: string pool overflow — the configuration file contained too many strings. increase the value of POOL_SIZE and recompile. 🫠
• Error: Unknown identifier X — the word X was encountered in the configuration file when wp2x expected a token identifier like HRt. most likely, you either misspelled it, or you got your quotation marks out of sync.
• Error: Identifier not followed by = sign — after an identifier must come an equals-sign. periodt.
• Error: Quotation mark expected — after the equals-sign must come a quotation mark.
• Error: X: `%\n' not at start of expansion — the expansion for the identifier X contained the indicated sequence of characters somewhere other than the beginning of the string. the `%\n' interpolation code is meaningful only at the beginning of a string.
• Error: X: invalid escape `%x' — the expansion for the identifier X contained an invalid escape. either you used %1, %2 or %c when the identifier X does not supply that parameter, or you meant for a genuine percent sign to be output, in which case you should put %% in the expansion.
• Error: Invalid character identifier — character identifiers can only be one character long (after backslash interpretation).
• Warning: Expected XX but received YY. — the program expected the next byte from the WP file to be XX, but the byte YY was encountered instead. this means either that your WP file is damaged, or that the program is seriously confused. (or both.) the program will pretend that the byte in the file was indeed XX, which may lead to synchronization errors later on. 💀
• Warning: No expansion for X — the WP file contained the token X, but the configuration file did not contain any expansion text for it. a null expansion was assumed.
• Warning: No expansion for XX (c) — the WP file contained the character c (hex code XX), but the configuration file did not contain any expansion text for it. the character was emitted unaltered. beware that this may give your text formatter indigestion if it does not handle eight-bit characters. 🤢
• Warning: X code not supported — the file being converted uses a code which wp2x does not know how to convert. a comment is placed in the output file in its place. if you ever encounter a WPCorp reserved or a WPCorp undefined code, the author would appreciate hearing from you. 🫶
• Internal error: Invalid escape, %x — while processing text, wp2x noticed that you used an invalid escape. nothing is emitted as the escape text. (the internal-ness is that this error is supposed to be caught at the time the configuration file is read.) 😵‍💫

---

🐛 BUGS

naive configuration files will fail if your WP file doesn't nest its tags properly. a typical case is

[Center][B]Hello[center]
[Center]There[b][center]

to produce a centered boldface Hello. if you use the naive encoding of

Center="\\centerline{"
center="}\n"
Bold="{\\bf "
bold="}"

then this will expand to

\centerline{{\bf Hello}
\centerline{There}}

WordPerfect has no clean concept of grouping; it lets you change fonts at any time and let those changes propagate outside the current environment. (with the exception of headers, footers, footnotes, and endnotes.) no cap. 🎀

now sure, you could write complicated configuration strings to try to handle this properly, but it'd probably not be worth the trouble. after all, the purpose is not to perform a perfect conversion, but rather to produce a readable conversion, which can then be massaged by hand to produce a perfect manuscript. lowkey iconic design philosophy honestly. 💅

another potential problem is combined attributes, like boldface underline. under a naive configuration,

[B]Boldface [U]Underlined boldface[b] Underlined[u] normal.

comes out as

 {\bf Boldface {\it Underlined boldface} Underlined\/} normal.

which is wrong for two reasons:

1. the nesting problem discussed above
2. TeX font attributes do not combine. 💔

similar problems exist for other document preparation systems. so be careful. fr fr.

---

👑 AUTHORS

• original author: Raymond Chen <raymond@math.berkeley.edu>
• previous maintainer: Michael Richardson <mcr@ccs.carleton.ca>
• current maintainer: Martin Hinner <mhi@penguin.cz>

---

and that's a wrap on the whole WP2X(1) page, bestie — section 1 of the manual, all of it, converted and slayed. 🌈✨ go forth and translate those WordPerfect files, and remember: readable > perfect. mwah. 💖🦋