home *** CD-ROM | disk | FTP | other *** search
/ Current Shareware 1994 January / SHAR194.ISO / textutil / wsmart12.zip / WORDSMRT.DOC < prev    next >
Text File  |  1993-10-13  |  35KB  |  1,042 lines

  1. WORDSMRT.DOC
  2. Documentation for WordSmart (WSM.EXE), a file-reformatting utility
  3. Version: 1.2
  4. August 3, 1993
  5.  
  6.  WORDSMART and its documentation are Copyright 1992, 1993 by:
  7.  
  8.  Lambert Klein
  9.  P.O. Box 611
  10.  Wayne MI  48184-0611
  11.  Voice telephone: (313) 467-8070        Fax:    313-467-8373
  12.  
  13.  GEnie:       L.Klein1
  14.  CompuServe:  72010,624
  15.  Internet:    72010.624@compuserve.com
  16.  AOL:         LKlein3990
  17.  
  18. Member, Association of Shareware Professionals
  19.  
  20. =======================================================
  21.  
  22.          ┌─────────┐
  23.    ┌─────┴───┐     │               (R)
  24.  ──│         │o    │──────────────────
  25.    │   ┌─────┴╨──┐ │  Association of
  26.    │   │         │─┘  Shareware
  27.    └───│    o    │    Professionals
  28.  ──────│    ║    │────────────────────
  29.        └────╨────┘    MEMBER
  30.  
  31. "This program is produced by a member of the Association of
  32. Shareware Professionals (ASP). ASP wants to make sure that the
  33. shareware principle works for you. If you are unable to resolve
  34. a shareware-related problem with an ASP member by contacting
  35. the member directly, ASP may be able to help. The ASP Ombudsman
  36. can help you resolve a dispute or problem with an ASP member,
  37. but does not provide technical support for members' products.
  38. Please write to the ASP Ombudsman at 545 Grover Road Muskegon
  39. MI 49442 or send a Compuserve message via easyplex to ASP
  40. Ombudsman 70007,3536."
  41.  
  42. ============================================================
  43.  
  44.  
  45.       ┌──────────────────────┐
  46.       │  TABLE OF CONTENTS:  │
  47.       └──────────────────────┘
  48.  
  49.      WordSmart is Shareware  ......  page 3
  50.  
  51.      Thanks  ......................  page 3
  52.  
  53.      Purpose of WordSmart  ........  page 4
  54.  
  55.      Features of WordSmart  .......  page 4
  56.  
  57.      Running WordSmart  ...........  page 5
  58.  
  59.      Basic program syntax  ........  page 5
  60.  
  61.      Program options  .............  page 7
  62.  
  63.      Options summary  .............  page 8
  64.  
  65.      Options in detail  ...........  page 8
  66.  
  67.              Left margin  .........  page 8
  68.  
  69.              Right margin  ........  page 9
  70.  
  71.              Removing all EOLs
  72.              within paragraphs  ...  page 11
  73.  
  74.              Preventing reformatting page 12
  75.  
  76.              What happens during
  77.              -R processing  .......  page 13
  78.  
  79.              Write output file  ...  page 14
  80.  
  81.              Over-write existing
  82.              file  ................  page 15
  83.  
  84.              Remove form-feeds  ...  page 16
  85.  
  86.              Remove multiple spaces  page 16
  87.  
  88.              Print registration ...  page 16
  89.  
  90.        Remove blank lines (reg)  ..  page 17
  91.  
  92.        Quiet processing (reg)  ....  page 17
  93.  
  94.      Piping and redirection  ......  page 18
  95.  
  96.      Errorlevels  .................  page 20
  97.  
  98.      Example bat file  ............  page 20
  99.  
  100.      Registration benefits  .......  page 21
  101.  
  102.  
  103.                                                          page 3
  104.  
  105.  
  106. WordSmart is shareware. If you try it out, find it useful, and
  107. go on using it - please register it. Registration is only
  108. $14.00. plus $4.00 shipping and handling.
  109.  
  110. I hope you find WordSmart useful. If you have any comments,
  111. suggestions, bug reports, and so on, please send them to me
  112. at the address shown above. See the file PROGRAMS.TXT, also
  113. in the archive WORDSMRT.ZIP, for information on my other
  114. shareware, including PrintPlus, my menu-driven dot-matrix
  115. printer control program.
  116.  
  117. -- Lambert Klein
  118.  
  119. ============================================================
  120.  
  121.  
  122. Any registered or trademarked product names mentioned in
  123. this documentation are the property of their respective
  124. owners or publishers.
  125.  
  126. ============================================================
  127.  
  128.  
  129.  
  130.  
  131.  ╓┬───────────┬╖
  132.  ║│  THANKS:  │║
  133.  ╙┴───────────┴╜
  134.  
  135. I would like to thank Mike Arst for his continuous testing
  136. and debugging of WordSmart. There have been many hours of testing
  137. and coding put into WordSmart.
  138.  
  139. Thanks goes to the Writer of WordSmart's documentation, who
  140. also happens to be Mike Arst!
  141.  
  142.  
  143.  
  144.                                                          page 4
  145.  ╓┬────────────┐
  146.  ║│  PURPOSE   │
  147.  ╙┴────────────┘
  148.  
  149. WordSmart, written entirely in assembly language, is a fast
  150. reformatter for text files.
  151.  
  152. For instance, WordSmart can increase the line length of text
  153. files created with relatively short lines, perhaps (as with this
  154. file) because the writer assumed you'd be using a typical dot-
  155. matrix printer setup. But if you are using compressed mode for
  156. printing, you might prefer wider lines. WordSmart helps with this
  157. by automatically increasing line lengths for you (or decreasing
  158. them - your choice); you won't have to do so manually in a text
  159. editor or word processor.
  160.  
  161. FEATURES IN BOTH REGISTERED AND UNREGISTERED
  162. VERSIONS OF WORDSMART
  163.  
  164. o   Accepts input in the form of a source file whose name you
  165.     specify on the command line, or accepts input from "standard
  166.     input" (i.e., via a "pipe").
  167.  
  168. o   Writes an output file whose name you specify on the command
  169.     line; otherwise, writes to "standard output," allowing you
  170.     to redirect the results of processing to a file name or
  171.     else "pipe" the output to some other program.
  172.  
  173. o   Can over-write an existing file at your option
  174.  
  175. o   Adds to or removes spaces at the left sides of lines.
  176.  
  177. o   Changes the lengths of lines (from 10 characters wide
  178.     up to 60,000 characters wide). Can be used to remove "hard"
  179.     line breaks within paragraphs completely, preserving the
  180.     paragraph-endings themselves.
  181.  
  182. o   Removes form-feed characters.
  183.  
  184. o   Reduces runs of multiple spaces to a single space.
  185.  
  186. o   Returns errorlevels, useful when WordSmart is run from
  187.     batch files.
  188.  
  189. o   Removes blank lines from files.
  190.  
  191. ADDITIONAL FEATURES AVAILABLE ONLY IN THE
  192. REGISTERED VERSION
  193.  
  194.  
  195. o   "Quiet" mode - no screen display during processing
  196.  
  197.  
  198. The program will usually be referred to hereafter in the
  199. documentation simply as "WSM."
  200.  
  201.  
  202.                                                          page 5
  203.  ╓┬─────────────────┐
  204.  ║│ RUNNING WSM.EXE │
  205.  ╙┴─────────────────┘
  206.  
  207. WSM can read past an EOF character (Control-Z) and will treat it
  208. as if it were an ordinary character. WSM also treats a NULL (with
  209. a decimal value of 0) no differently from any other character.
  210.  
  211. Limitations:
  212.  
  213. Line-ending characters: WSM cannot process files with Unix-style
  214. line endings (line feeds only), nor those with Mac-style line
  215. endings (carriage returns only). The files must have standard DOS
  216. line endings (carriage return plus line feed).
  217.  
  218. Types of input files: WSM is intended for use only with plain-
  219. text files, not files saved in the "document" format of programs
  220. like WordStar, Microsoft Word, or WordPerfect. Using WSM to alter
  221. such files will probably make them unreadable by the word
  222. processing programs that created them.
  223.  
  224.  ╓┬──────────────────────┐
  225.  ║│ BASIC PROGRAM SYNTAX │
  226.  ╙┴──────────────────────┘
  227.  
  228. Typing WSM alone at the DOS prompt brings up a help-screen
  229. containing a summary of the command-line options and information
  230. about the exit codes (errorlevels) WSM returns.
  231.  
  232. Typical command line:
  233.  
  234. WSM input [options] > output
  235.  
  236. Where:
  237.  
  238. input       is the name of the file you want to process;
  239.  
  240. [options]   are one or more of the command-line options
  241.             (switches) discussed below; and
  242.  
  243. > output    is an optional command whereby you use DOS
  244.             redirection to create an output file.
  245.  
  246. NOTE:       THE NAME OF THE FILE TO BE USED FOR INPUT MUST BE
  247.             THE FIRST PARAMETER ON THE COMMAND LINE.
  248.  
  249.             If you do not put the input file name first,
  250.             WordSmart will display an error message ("source
  251.             path error"), and it will halt without doing any
  252.             further work.
  253.  
  254.             The input file name CANNOT contain the DOS
  255.             wildcards "*" or "?".
  256.  
  257.  
  258.                                                          page 6
  259.  
  260. Other ways to write the command line:
  261.  
  262.         WSM input [options] | another_program
  263.  
  264. In this kind of command, you use a "pipe" to send WSM's output
  265. not to a file, but to some other program ("another_program" in
  266. the above example) that can read from "standard input."
  267.  
  268. This also works:
  269.  
  270.         another_program | WSM [options] > output
  271.  
  272.  
  273. In this case, you pipe some other program's output to WSM. Note
  274. that in this case, you do NOT give WSM the name of an input file.
  275. You could use WSM's "write output file" option (see below) or use
  276. "> output."
  277.  
  278. NOTE:  There are some risks to be aware of when using redirection
  279.        to write output files. They will be discussed in greater
  280.        detail in the section called "Piping and output
  281.        redirection."
  282.  
  283. A WSM command line that does not contain a "write output to
  284. file..." command forces the results of processing to be sent only
  285. to "standard output" - to the screen. You can use this to preview
  286. the results of processing and without first having to write an
  287. output file. If you use a program like LIST.COM (a shareware file
  288. viewer by Vernon Buerg), you can pipe output from WSM.EXE to LIST,
  289. thus:
  290.  
  291.         WSM input [switches] | list /s
  292.  
  293. (LIST's "/s" option is required when it is receiving input via
  294. "pipe" like that.)
  295.  
  296.  
  297.                                                          page 7
  298.  
  299.  ╓┬─────────────────┐
  300.  ║│ PROGRAM OPTIONS │
  301.  ╙┴─────────────────┘
  302.  
  303. WordSmart's functions are all invoked with command-line "switches."
  304.  
  305. Each "switch" is a hyphen, followed by a single letter (with no
  306. space between the hyphen and the letter). The case of the letter
  307. is unimportant. Both of the following are "legal" forms of the
  308. "-B" switch:
  309.  
  310.         -b      -B
  311.  
  312. Some switches require additional information, which will be
  313. referred to hereafter as an "argument." For example, -W tells
  314. WSM to write an output file; the output file name argument
  315. follows the -W.
  316.  
  317. You can either add or omit a space between a switch and its
  318. argument. Both of the following are legal ways to add the output
  319. file name argument to the "-w" switch:
  320.  
  321.          -Woutput      -W output
  322.  
  323. There are two possible switch characters: the hyphen and the
  324. forward slash. Either -W or /W would work for the switch used
  325. to specify the output file name. All of the following are "legal"
  326. ways of writing that switch (the file name argument is
  327. represented by the word "output"):
  328.  
  329.         -woutput      -w output      /woutput      /w output
  330.  
  331.         -Woutput      -W output      /Woutput      /W output
  332.  
  333.  
  334.  
  335.                                                          page 8
  336.  ╓┬──────────────────────╖
  337.  ║│ OPTIONS - SUMMARIZED ║
  338.  ╙┴──────────────────────╜
  339.  
  340. Switch   Purpose
  341.  
  342. -L       Specify the left margin; must be followed by a number
  343.          indicating the number of spaces to add at the left
  344.          margin.
  345.  
  346. -R       Specify the right margin; must be followed by a number
  347.          indicating the maximum line width.
  348.  
  349. -W       Write output file; must be followed by the name of the
  350.          file to write.
  351.  
  352. -O       Over-write an existing file without query. This option
  353.          takes no arguments.
  354.  
  355. -F       Remove form-feed characters. This option takes no
  356.          arguments.
  357.  
  358. -S       Remove runs of multiple spaces, reducing the string
  359.          of spaces to one space only. This option takes no
  360.          arguments.
  361.  
  362. -I       Send a WordSmart registration form directly to the
  363.          printer. This option takes no arguments.
  364.  
  365. -B       Removes all blank lines past one. -B0 removes all.
  366.  
  367. -Q       "Quiet" mode - no screen display at all during or
  368.          after processing. This option takes no arguments.
  369.          AVAILABLE ONLY IN THE REGISTERED VERSION.
  370.  
  371.  
  372.  ╓┬───────────────────────────────┐
  373.  ║│ OPTIONS - DESCRIBED IN DETAIL │
  374.  ╙┴───────────────────────────────┘
  375.  
  376.  
  377.  ┌────────────────────────────────┐
  378.  │ -L   ADD SPACES TO LEFT MARGIN │
  379.  └────────────────────────────────┘
  380.  
  381. "-L" is always followed by a two- or three-digit number
  382. indicating the number of spaces to add at the left of each line
  383. of the input file. Example:
  384.  
  385. -L5  would add 5 spaces to the beginning of each line. If the file
  386. has no left-margin indents at all, the command -L5 would put the
  387. first NON-space character on each line in column 6.
  388.  
  389.  
  390.                                                          page 9
  391.  
  392. If there are already spaces at the start of a line, the -L
  393. command adds the additional spaces to them. For example, a file
  394. whose lines are already indented by two spaces would be
  395. indented by seven spaces after you'd used -L5.
  396.  
  397. In the present version of WSM, the -L command does not REMOVE
  398. spaces from the left margin. Thus, -L0 has no meaning. (Removal
  399. of spaces from the left margin is being considered for a future
  400. version of WordSmart.)
  401.  
  402. Example - if this is a line in the input file:
  403.  
  404. Here is a test line
  405.  
  406. ... it looks this way after processing via -L5:
  407.  
  408.      Here is a test line
  409.  
  410. The first non-space character ("H") is now at column 6.
  411.  
  412. CAUTION:  Numbers higher than 200, used with the -L switch,
  413.           might cause corruption in or truncation of the output
  414.           file.
  415.  
  416.  ┌───────────────────────┐
  417.  │ -R   NEW RIGHT MARGIN │
  418.  └───────────────────────┘
  419. -R is followed by a number 2 to 5 digits long, indicating a new
  420. line width (the number cannot exceed 60000). The number does not
  421. necessarily mean how many characters long the line will be; it is
  422. an "absolute" setting, indicating the right-most COLUMN NUMBER
  423. past which a line must break to a new line. (There's more
  424. information later in this documentation concerning exactly how
  425. WSM makes line-ending decisions).
  426.  
  427. For instance, if the input file has no left-margin indents at
  428. all, and if you use the -R switch with an argument of 50, the
  429. widest possible output line will be 50 characters long. On the
  430. other hand, if you were to use these commands:
  431.  
  432.          -L10  -R50
  433.  
  434. ... then WSM would add 10 spaces to the left margin and re-
  435. format lines out to column 50 (maximum). In that case, there
  436. would be a maximum of 40 characters on each line, NOT including
  437. the spaces added at the beginning of the line.
  438.  
  439.  
  440.                                                          page 10
  441. Example - lines that break at column 25:
  442.  
  443. This is an example of
  444. lines that don't extend
  445. past column 25. The goal
  446. is to re-break them with
  447. the command -R45 so that
  448. they break at column 45.
  449.  
  450. After processing with the command -R45:
  451.  
  452. This is an example of lines that don't extend
  453. past column 25. The goal is to re-break them
  454. with the command -R45 so that they break at
  455. column 45.
  456.  
  457.  
  458. A nonsensical command like  -L40 -R30  would, if taken literally,
  459. add 40 spaces to the start of each line but then try to break all
  460. lines at column 30. If you give WSM an instruction like that, it
  461. ignores the left-margin command entirely and takes only the right-
  462. margin command into account.
  463.  
  464. If you use an argument less than 10, -R defaults to a value of
  465. 10. (There is one notable exception; -R0. See "Removing All Line
  466. Breaks Within Paragraphs," below.)
  467.  
  468. If you have a text file in which each paragraph is a single long
  469. line, use -R plus a two-digit argument (80 or below) if you want to
  470. make the file more easily readable on-screen. But note: If there
  471. are NO blank lines in such a file, and if none of the lines is
  472. indented, processing it with WSM.EXE will cause the entire file to
  473. be treated as a single paragraph, and you'll lose all paragraph
  474. breaks. The solution would be to add blank lines between paragraphs
  475. and then process the file with WSM.
  476.  
  477. Where processing begins and ends:
  478.  
  479. For WordSmart's purposes, a paragraph is one or more lines with
  480. at least one blank line above and below it (them). If a line
  481. appears blank but contains spaces, WSM still treats it as a blank
  482. line. The reason is that, before processing begins, WSM removes any
  483. spaces at the right side of a line - "trailing spaces" - if they
  484. are the last characters before the line boundary. (Thus, a line
  485. containing only spaces has all of its spaces removed before
  486. processing begins.)
  487.  
  488.  
  489.                                                          page 11
  490.  ┌────────────────────────────────────────────┐
  491.  │ REMOVING ALL LINE BREAKS WITHIN PARAGRAPHS │
  492.  └────────────────────────────────────────────┘
  493.  
  494. Omitting the -R switch entirely from the WordSmart command line,
  495. OR using the command -R0 (zero), tells WSM to remove ALL line
  496. endings within paragraphs in the input file. Using -R0 (or no
  497. -R command at all) is a quick way to turn each paragraph of the
  498. input file into a single long line (see below for exceptions,
  499. however).
  500.  
  501. This is useful if you will import the text file into a desktop
  502. publishing (DTP) program. You almost always want a DTP program to
  503. make its own line-ending decisions, but its ability to do so is
  504. always defeated by "hard" line breaks within paragraphs. In the
  505. ideal situation, each paragraph is a single long line, and the
  506. only "hard" line breaks in the file are those at the very ends of
  507. the paragraphs.
  508.  
  509. -R0 (or no -R at all) will preserve the FINAL line boundary of
  510. each paragraph, AS LONG AS THERE IS AT LEAST ONE BLANK LINE ABOVE
  511. AND BELOW EACH PARAGRAPH.
  512.  
  513. Example: Suppose the input file looks like this:
  514.  
  515. Line one.
  516. Line two.
  517. Line three.
  518. Line four.
  519.  
  520. Line five.
  521. Line six.
  522.  
  523. Result of processing the file with -R0 (or no -R command
  524. at all):
  525.  
  526. Line one. Line two. Line three. Line four.
  527.  
  528. Line five. Line six.
  529.  
  530.  
  531.                                                          page 12
  532.  ┌─────────────────────────┐
  533.  │ PREVENTING REFORMATTING │
  534.  └─────────────────────────┘
  535.  
  536. If, while re-breaking lines in a file, WSM encounters a line
  537. that is already indented from the left margin - using either
  538. spaces or Tab characters - it will not move any part of that
  539. line up to the previous line.
  540.  
  541. This is a handy way to prevent reformatting of certain lines.
  542. Suppose the input file looks like this:
  543.  
  544. Line one.
  545. Line two.
  546.   Line three.
  547.   Line four.
  548. Line five.
  549.   Line six.
  550. Line seven.
  551.  
  552. Line eight.
  553.   Line nine.
  554.  
  555.  
  556. Result of processing the file with -R0 (or no -R command):
  557.  
  558. Line one. Line two.
  559.   Line three.
  560.   Line four. Line five.
  561.   Line six. Line seven.
  562.  
  563. Line eight.
  564.   Line nine.
  565.  
  566. When WSM changes the line length, no part of an already-indented
  567. line will be merged with the one ABOVE it. However, it might be
  568. merged with any NON-INDENTED line BELOW it (whether the latter
  569. occurs depends on the argument to the -R switch - if you have
  570. used -R at all).
  571.  
  572. Try a few experiments to get a feel for how line-width
  573. reformatting (and exceptions thereto) works.
  574.  
  575.  
  576.                                                          page 13
  577.  ┌─────────────────────────────────────┐
  578.  │ WHAT HAPPENS DURING "-R" PROCESSING │
  579.  └─────────────────────────────────────┘
  580.  
  581. First, the program strips trailing spaces from all lines.
  582.  
  583. Then WSM breaks lines at a space or a hyphen. It NEVER breaks up
  584. a word unless the word already contains a hyphen. Space
  585. permitting on a given line, it leaves the part of the word to the
  586. left of the hyphen, and the hyphen itself, on the line and brings
  587. the part of the word to the right of the hyphen down to the next
  588. line. This line:
  589.  
  590. I won't look the same, post-processing, eh?
  591.  
  592. ... might look like this after WSM finishes with it:
  593.  
  594. I won't look the same, post-
  595. processing, eh?
  596.  
  597. If there isn't room on the upper line for that part of the word
  598. (plus the hyphen itself), WSM brings the ENTIRE word down to the
  599. next line, thus:
  600.  
  601. I won't look the same,
  602. post-processing, eh?
  603.  
  604. Dashes:
  605.  
  606. Hyphens sometimes appear in text files to indicate "long" dashes.
  607. WSM treats such character strings - like that -- (or that)
  608. differently from how it deals with hyphens in other situations.
  609.  
  610. Suppose the input file contains a paragraph like this:
  611.  
  612. Here are some lines --       Or:     Here are some lines -
  613. not many -- with dashes.             not many - with dashes.
  614.  
  615. If you use WSM to increase the file's right margin, the above two
  616. lines might become:
  617.  
  618. Here are a few lines -- not many -- containing dashes.
  619.  
  620.         Or:
  621.  
  622. Here are a few lines - not many - containing dashes.
  623.  
  624. WSM makes this kind of change whether or not there is a space (or
  625. more than one space) between the "dash" and the end of the line.
  626. The key here is that the "dash" must be PRECEDED by a space,
  627. which tells WSM that the hyphen is used as a "dash" and not to
  628. break a word. 
  629.  
  630.  
  631.                                                          page 14
  632.  
  633. If "dashes"--(like these)--are NOT preceded by spaces, the results
  634. might not be just right in the output file. You might need to do
  635. a bit of editing afterward, removing a space WSM will sometimes
  636. add to the right of such "dashes" in the output file (if the
  637. double hyphen falls at the very end of a line in the input file).
  638.  
  639.  
  640.  ┌────────────────────────┐
  641.  │ -W   WRITE OUTPUT FILE │
  642.  └────────────────────────┘
  643.  
  644. The -W switch tells WordSmart to write an output file and
  645. requires a file name argument. Omitting the argument causes an
  646. error message to appear, and no processing occurs - except when
  647. you've "piped" some other program's output to WSM for use as its
  648. own input. (There's more information about that in the section
  649. below called "Piping and Output Redirection.")
  650.  
  651. WSM will NEVER allow you to use the same file name for input and
  652. output when you use the -W switch. (But if you use redirection,
  653. all bets are off - see the piping/redirection information below
  654. for more about this.)
  655.  
  656. The output file name can contain path information but CANNOT
  657. contain the DOS wildcards "*" or "?".
  658.  
  659. If you specify a subdirectory that does not exist, WSM halts with
  660. an error message. (If you make that error when using the
  661. REGISTERED version and if you have used the -Q switch for "quiet"
  662. processing, WSM just beeps.)
  663.  
  664. Example - to process an input file called INPUT.DOC and write
  665. an output file called OUTPUT.DOC:
  666.  
  667.          WSM input.doc -r50 -w output.doc
  668.  
  669. Over-writing an existing output file or choosing a new name:
  670.  
  671. If you are not using the -O switch, and if you specify an output
  672. file that now exists, WSM will beep, open a window on the screen
  673. announcing that the file exists, and ask you to make one of three
  674. choices: Select a new file name, over-write the existing file, or
  675. quit.
  676.  
  677. Press "Q" or ESC to quit at once - no further action.
  678.  
  679. Press "O" to over-write the existing file (unless it is write-
  680. protected).
  681.  
  682.  
  683.                                                          page 15
  684.  
  685. Press "N" to open a window in which you type a new file name.
  686. This also opens a window first containing the message "INSERT
  687. OFF." Pressing ENTER or ESC right away cancels the new-file-name
  688. prompt and tells WSM to quit without doing anything. Or type the
  689. new output file name (including path information, if need be) at
  690. the prompt, then press ENTER to continue processing. WSM then
  691. writes the output file.
  692.  
  693. (If you decide to over-write the existing file after all, re-type
  694. its name at the new-file-name prompt. WSM presents the "over-
  695. write/new file name/quit" prompt again. Type "O" to over-write
  696. the file.)
  697.  
  698. The new-output-name prompt supports a few simple editing
  699. keystrokes: The left- and right-arrow keys move the cursor back
  700. and forth across characters in the prompt line without erasing
  701. any characters. BACKSPACE erases the character to the left of the
  702. cursor. DEL erases the character underneath the cursor.
  703.  
  704. Pressing INS toggles insert-mode on and off (and toggles the text
  705. in the smaller window from "INSERT OFF" to "INSERT ON" and back).
  706. With insert-mode ON, typing characters into the prompt line
  707. pushes any existing characters to the right; with insert-mode
  708. OFF, typing characters into the prompt over-strikes any
  709. characters now there.
  710.  
  711. You can, initially, type file names much longer than the legal
  712. DOS limit. But if you do so, after you press ENTER, WSM
  713. will beep and inform you that you've typed an illegal file
  714. name. Press ENTER after reading this error message, and you'll
  715. be returned to the new-file-name prompt.
  716.  
  717. The -W switch is one way to write an output file; using
  718. redirection is another. That method will be discussed shortly.
  719.  
  720.  
  721.  ┌───────────────────────────────┐
  722.  │ -O   OVER-WRITE EXISTING FILE │
  723.  └───────────────────────────────┘
  724.  
  725. Use the -O switch (no arguments) to suppress WSM's query about
  726. over-writing an existing output file. Example:
  727.  
  728. WSM input.doc -R50 -w output.doc -o
  729.  
  730. The -O switch can appear anywhere to the right of the input file
  731. name, and you can use the switch (without causing an error
  732. message) whether or not the output file name already exists.
  733.  
  734.  
  735.  
  736.                                                          page 16
  737.  ┌──────────────────────────────────┐
  738.  │ -F   REMOVE FORM-FEED CHARACTERS │
  739.  └──────────────────────────────────┘
  740.  
  741. Use -F (no arguments) to remove printer form-feed (FF) characters
  742. (Control-L, decimal value, 12).
  743.  
  744. If the FF character is by itself on a line, -F deletes the ENTIRE
  745. line (including line boundary). If the FF character appears at
  746. the start or end of a line containing other text, WSM will remove
  747. the FF itself but will not remove any other text on the line
  748. (aside from trailing spaces).
  749.  
  750.  ┌─────────────────────────────┐
  751.  │ -S   REMOVE MULTIPLE SPACES │
  752.  └─────────────────────────────┘
  753.  
  754. Use -S (no arguments) to reduce strings of two or more spaces in
  755. a row to a single space.
  756.  
  757. This is handy for removing, say, multiple spaces following
  758. punctuation. (Multiple spacing is not desirable if you're sending
  759. the text to a typesetting or DTP system.)
  760.  
  761. -S is also handy for unjustifying text whose writer has used
  762. multiple spaces to left/right-justify the lines. -S always leaves
  763. a SINGLE space in place of the string of multiple spaces
  764. (including at the beginnings of lines that have been indented by
  765. two or more spaces; this version of WSM is not able to remove ALL
  766. spaces at the start of lines).
  767.  
  768.  ┌──────────────────────────────────────┐
  769.  │ -I   PRINT REGISTRATION FORM/INVOICE │
  770.  └──────────────────────────────────────┘
  771.  
  772. The -I switch takes no arguments. Give the command:
  773.  
  774.         WSM -I
  775.  
  776. to print a WordSmart registration form on your printer. Make sure
  777. the printer is on and ready before giving the command. WordSmart
  778. does not do a "printer-ready?" check before starting the print
  779. routine.
  780.  
  781. -I works in both the registered and unregistered versions but is
  782. not noted in the registered version's help-screen.
  783.  
  784.  
  785.                                                          page 17
  786.  
  787.  ╓╥────────────────────────────╖
  788.  ║║ -B   REMOVE BLANK LINES -  ║
  789.  ╙╨────────────────────────────╜
  790.  
  791. Use -B (no arguments) to remove all blank lines in the file past
  792. one, including lines that begin with spaces.
  793. -B0 removes all blank lines.
  794.  
  795. NOTE:  This command will NOT remove lines that begin with one or
  796.        more tab characters but that are otherwise blank (i.e.,
  797.        they contain nothing other than tabs or spaces). But lines
  798.        that begin with one or more spaces WILL be removed even if
  799.        there are tabs after the spaces.
  800.  
  801.  
  802.  ╓╥─────────────────────────────────────────────────────╖
  803.  ║║ -Q   "QUIET" PROCESSING - *REGISTERED VERSION ONLY* ║
  804.  ╙╨─────────────────────────────────────────────────────╜
  805.  
  806. Use -Q (no arguments) to suppress all WordSmart screen displays.
  807. If there is any error during processing, you are alerted to the
  808. problem only via a beep. -Q is useful if you run WSM from batch
  809. files and want full control over the screen displays during
  810. execution of the batch files.
  811.  
  812. In some situations, WSM will not beep if there is an error when
  813. you're using the -Q switch. But you can check for errors by
  814. testing for the exit code (errorlevel) WSM returns (errorlevels
  815. are discussed shortly).
  816.  
  817.  
  818.                                                          page 18
  819.  ╓┬───────────────────────────────┐
  820.  ║│ PIPING AND OUTPUT REDIRECTION │
  821.  ╙┴───────────────────────────────┘
  822.  
  823. WordSmart can take as input either a file whose name you
  824. specify on the command line, or the output of some other
  825. process - via "piping."
  826.  
  827. Suppose you use an automated search/replace program called SR that
  828. can write to standard output or can read from standard input.
  829. Examples:
  830.  
  831.         SR command | WSM [options]
  832.  
  833. Or:
  834.  
  835.  
  836.         WSM [options] | SR command
  837.  
  838. In the first case, you pipe the SR's output to WSM. In the
  839. second, you pipe WSM's output to SR.
  840.  
  841. When you tell WSM to get its information from standard input, do
  842. NOT put the name of an input file into the WSM command line.
  843.  
  844. Given a command like the following:
  845.  
  846.         another_program | WSM input.doc [options]
  847.  
  848. ... WSM completely ignores the piped information and reads
  849. only INPUT.DOC, instead.
  850.  
  851. Writing output files using redirection:
  852.  
  853. You can use WSM's -W switch to write an output file, or you can
  854. use DOS redirection (">" and ">>").
  855.  
  856. Using ">" can be risky. Suppose you'd like to process the file
  857. INPUT.DOC and over-write it with the changed version - same file
  858. name - rather than write a new file. So you give this command:
  859.  
  860. WSM input.doc [options] > input.doc
  861.  
  862. Result: A file called INPUT.DOC that is only ZERO BYTES LONG.
  863. Definitely not what you wanted.
  864.  
  865. Reason: DOS (not WSM) creates the zero-byte file. Then WSM reads
  866. the input file. But by that time, there isn't anything to read
  867. other than a zero-byte file! If you have only one copy of
  868. INPUT.DOC, you'll have lost it for good.
  869.  
  870.  
  871.                                                          page 19
  872.  
  873. Don't EVER try to over-write your existing file that way. Play
  874. it safe; process the file as follows:
  875.  
  876.         WSM input.doc [options] > output.doc
  877.  
  878. I.e., use a different output file name (or forget redirection
  879. and use WordSmart's -W switch).
  880. The following sort of command is also risky:
  881.  
  882.         WSM [options] < input.doc > input.doc
  883.  
  884. It might work well at some times, but destroy or corrupt your
  885. input file at other times. The following is much safer:
  886.  
  887.         WSM [options] < input.doc > output.doc
  888.  
  889. The following doesn't work, either:
  890.  
  891.         WSM input.doc [options] -w output.doc > new.doc
  892.  
  893. You think, perhaps, that you can create two identical output files
  894. at the same time - OUTPUT.DOC and NEW.DOC? Doesn't work. In that
  895. case, WSM writes OUTPUT.DOC and DOS itself writes a zero-byte file
  896. called NEW.DOC.
  897.  
  898. Redirection and screen displays:
  899.  
  900. When you use redirection, you don't give WSM.EXE enough
  901. information to create complete screen displays. If you pipe
  902. information to WSM, it doesn't display a proper input file name -
  903. because there isn't an input file to begin with.
  904.  
  905. If you write an output file via redirection, the WSM screen
  906. display doesn't show any output file name.
  907.  
  908.  
  909.                                                          page 20
  910.  ╓┬─────────────┐
  911.  ║│ ERRORLEVELS │
  912.  ╙┴─────────────┘
  913. WordSmart returns 7 different exit codes (errorlevels):
  914.  
  915. Code    Meaning
  916.  
  917. 0      Processing was successful
  918.  
  919. 1     "Read" error - couldn't find the specified input file.
  920.  
  921. 2      Can't write the output file because you gave it the same
  922.        name as the input file.
  923.  
  924.       (NOTE: Using output redirection completely defeats
  925.       WordSmart's ability to check for that kind of error.)
  926.  
  927. 3      Can't over-write the specified output file - it now
  928.        exists (and you haven't used the -O switch).
  929.  
  930. 4      Can't write the specified output file - you've given
  931.        a drive and/or path name that doesn't exist. WSM also
  932.        returns this errorlevel if you try to write an output
  933.        file to a floppy drive that isn't ready, or to a write-
  934.        protected disk.
  935.  
  936. 5      Can't over-write the existing file because it's write-
  937.        protected.
  938.  
  939. 255    Returned if you type WSM without any command-line
  940.        options at all.
  941.  
  942.  
  943. The errorlevels become most useful when you're running WSM from a
  944. batch file and are using the -Q ("quiet") switch, in which case
  945. there are no screen displays at all.
  946.  
  947. See the file WORDSMRT.BAT for a simple example of checking for the
  948. return of errorlevels in a batch file. The batch file uses WSM's
  949. -Q switch, which will not function if you don't yet have the
  950. registered version of WSM; but you will still be able to see how
  951. the errorlevel-checking works. (The presence of -Q in the command
  952. line will not cause the unregistered version to return any error
  953. messages.)
  954.  
  955.  ╓┬───────────────────┐
  956.  ║│ ABOUT EXAMPLE.BAT │
  957.  ╙┴───────────────────┘
  958. EXAMPLE.BAT, included in the WordSmart distribution archive, is a
  959. simple batch file that shows the results of processing using
  960. various -R commands.
  961.  
  962. EXAMPLE.BAT uses the file you're reading right now (WORDSMRT.DOC)
  963. for input, and it writes an output file called XXXXXXX_._XX. Once
  964. you're done using EXAMPLE.BAT, be sure to delete XXXXXXX_._XX.
  965.  
  966.  
  967.                                                          page 21
  968.  
  969. Type EXAMPLE at the DOS prompt for information on the batch
  970. file's syntax.
  971.  
  972. I hope you find WordSmart useful. I will greatly appreciate your
  973. registering it.
  974.  
  975. -- Lambert Klein
  976.  
  977.  
  978.  ┌┬───────────────────────────────────────────────────┬┐
  979.  ││ Documentation by Mike Arst, CompuServe 70403,1337 ││
  980.  └┴───────────────────────────────────────────────────┴┘
  981.  
  982.  
  983.  ┌┬────────────────────────┬┐
  984.  ││ REGISTRATION BENEFITS: ││
  985.  └┴────────────────────────┴┘
  986.  
  987. You have a 30-day evaluation period to try out WordSmart.
  988. After 30 days you must register WordSmart to legally continue
  989. its use.
  990.  
  991. When you register WordSmart you receive the following:
  992.  
  993. 1. A disk with the Registered version of WordSmart,
  994.    branded with your name and serial number.
  995.  
  996. 2. Other Shareware and Freeware.
  997.  
  998. 3. A printed manual for WordSmart.
  999.  
  1000. 4. Voice, mail and Email support.
  1001.  
  1002. 5. Any extra features that are added to WordSmart. This
  1003.    will include the the -Q switch for quiet screen during 
  1004.    processing.
  1005.  
  1006. 6. The great feeling of registering a high-caliber program
  1007.    at a very reasonable price!
  1008.  
  1009. To print the registration form type     WSM -I [Enter]
  1010. at the Dos prompt.
  1011.  
  1012. Thank you for your support!
  1013.  
  1014.  Lambert Klein
  1015.  PO Box 611
  1016.  Wayne MI  48184-0611
  1017.  
  1018. You can register WordSmart on CompuServe also. Just "GO SWREG".
  1019.  
  1020. Program Title:          WordSmart 
  1021. Registration ID:        562
  1022.  
  1023.  
  1024.      CREDIT CARD ORDERS ONLY -
  1025.  
  1026.      You can order with MC, Visa, Amex, or Discover from Public (software)
  1027.      Library by calling 800-2424-PsL or 713-524-6394 or by FAX to 713-524-
  1028.      6398 or by CIS Email to 71355,470. You can also mail credit card
  1029.      orders to PsL at P.O.Box 35705, Houston, TX 77235-5705.
  1030.  
  1031.      THE ABOVE NUMBERS ARE FOR ORDERS ONLY.
  1032.  
  1033.      Any questions about the status of the shipment of the order, refunds,
  1034.      registration options, product details, technical support, volume
  1035.      discounts, dealer pricing, site licenses, etc, must be directed to
  1036.      Lambert Klein, Voice: 313-467-8070, Fax: 313-467-8373, Email or mail.
  1037.  
  1038.      To insure that you get the latest version, PsL will notify us the day
  1039.      of your order and we will ship the product directly to you. 
  1040.  
  1041. Non- Credit card orders may be sent to the Author: Lambert Klein.
  1042.