ASC2WS.TXT
     Revised 08-02-1989

     ASCII TO WORDSTAR CONVERSIONS -
     REMOVING CARRIAGE RETURN/LINE FEED PAIRS (CR/LF) FROM THE
     ENDS OF LINES, FROM INSIDE WORDSTAR ITSELF

     Designed for WordStar 5 but should work with all versions.
     ---------------------------------------------------------
     by Barry F. MacDonnell, July 1989.
     CompuServe ID: 71500,3413
     GEnie: B.MACDONNEL3

     Public domain: Permission to distribute
     is granted without restriction.
     ---------------------------------------------------------

     There may come a time when you want to take someone's text
     file from another word processor, or from a BBS download or
     e-mail letter and use WordStar to "massage" it into the
     shape you want.  Or, perhaps you use a simple text editor
     for the small stuff, but now need to import the editor's
     files into WordStar so that you can enhance them.  You may
     want to use new margins or highlight text, for example.

     Usually you get imported files in ASCII format: no embedded
     codes, just plain text with each line ending in a hard
     carriage return.  This format that can be read by any
     word processor or text editor.
 
     But ... eliminating all unwanted hard carriage returns
     and line feeds (abbreviated here as CR/LF, but which show
     up on the right side of your screen as a "<" symbol) is
     another matter. You have to get rid of these pesky
     critters if you want to reformat paragraphs in the file
     using WordStar's ^B (control-B).

     The usual method suggested in the WordStar 5.0 manual
     works fine by pressing ^6 (Control-upper row 6) on each
     line ending with a CR/LF.  Normally you don't want to do
     this on the last line in each paragraph or the lines
     between paragraphs. You then reformat the document with
     ^QU or repeatedly pressing ^B.

     For any file longer than a few paragraphs, the use of ^6 can
     be a real chore: hard on the hands and eyes.  Imagine
     pressing ^6 several hundred times.
     
     I automated this process with four (4) Find-and-Replace
     passes through the file.  You might find this process
     helpful; it is easier than it looks!


                         INSTRUCTIONS
                         ------------

     *IMPORTANT*  If your ASCII file's text does NOT begin in
     Column 1 on your screen (that is, it has an offset left
     margin), and/or it is more than one page long and has "^L"
     form feeds/page breaks in it, see the *NOTES* at the end of
     this file before beginning.

     
     First, open the ASCII file as a WordStar Document file.
     Then:
     
     1.   Press ^QA, for WordStar's Find-and-Replace function.

          You need to Find all CR/LFs at the end of each
          paragraph (not individual lines; that comes later), or
          those at and below any one-line text headings.

          You do this by entering the CR/LF code, ^N (control-N,
          which appears as the pair of control characters ^M^J in
          the display box), as many times as needed to equal the
          *maximum number* of blank lines that you can see
          anywhere in the file between blocks of text -- plus
          one.
     
          For example, say the greatest number of blank lines you
          can see anywhere in your file is five. In the on
          screen
          "Find" box you would type

                     ^N^N^N^N^N^N <Return>

          (Five control-Ns plus one.  Don't forget to hold down
          the control key while you press N six times.)

          What you'll see is

                     ^M^J^M^J^M^J^M^J^M^J^M^J

          You then Replace these six CR/LF (^M^J) pairs with six
          "#" characters --

                     ###### <Return>

          -- one for each ^M^J pair. These serve as paragraph and
          spacing markers. (You could use any character not used
          elsewhere in your file, but "#" seems handy.  If you're
          not sure what character to use, do a quick Find on that
          character first.  If it's already used, try something
          else, like the tilde ~.  You wouldn't use #, ~, ^, or *
          to convert *this* file, for example.  The plus sign
          or dollar sign would work, however.)

          For Options, press

                     AGN <Return> for Align, Replace throughout
          file, and Don't ask.

          WordStar will then do a Find-and-Replace.  If it cannot
          find the required number of CR/LFs it will tell you so;
          this means there weren't any strings of six (or however
          many) CR/LFs as you thought there were.

          In any case, press ESCape when it's finished its
          complete pass through to the end of the file.

     2.   Repeat step #1, *deleting* one ^M^J pair and one "#"
          symbol for each pass through the file.  Using the
          Delete key while in the display box makes this easy,
          but you'll press it twice for the ^M^J pair and once
          for the "#" since ^M and ^J are really separate control
          codes.

          Do this until only one ^M^J pair is left.  Enter a
          space in the Replace box (just press the space bar
          once) instead of a "#" symbol; this allows Replacing
          single line CR/LFs with a space.  If you didn't
          leave a space, text lines would close up and not
          reformat properly later. If you left a "#" that's OK
          -- just remember to use Find-and-Replace later (Find
          #, Replace it with <space>).

     
     3.   Now that the original ASCII file has no more CR/LFs in
          it, and is all "bunched" together, reverse the above
          process to reset paragraphs. That's what the "#"
          symbols were used for.

          Press ^QA.  Enter the maximum number of "#" symbols to
          Find (in our example, this would be six). Replace them
          with the same number of ^M^J pairs needed to give hard
          carriage returns and line feeds in the proper places.
          Again, use AGN as your Options.

     
     4.   Repeat step #3, deleting in a similar manner to step
          #2, until only the last two "#" symbols are left to
          Replace (which hold places for two CR/LFs -- the
          typical number between paragraphs). Replace these with
          ^M^Js and you now have a file in WordStar's document
          format.

          (The last line in the file may need a CR/LF entered
          manually, however.  Look over the newly converted
          file and if everything is OK, save it to disk.)


     By the way, I tried to turn these steps into a macro, only
     to find that the ^Ms in the Find-and-Replace box would abort
     the macro: ^M is like pressing the <Return> key in a running
     macro.  In any event, once you try this method you'll see it
     goes quite fast enough as it is.

     What happens if you start a Find-and-Replace with the
     *minimum* number of blank lines and work up to the maximum
     you think are in the file?  You'll get uniform paragraph
     spacing -- the smallest you've set.  (Maybe only one line
     between paragraphs.)

     Lastly, always make a backup of your ASCII file first, in
     case you accidentally save and overwrite the original
     file before checking everything out. You may want to
     refer to the original later.  I cannot be responsible for
     any loss or damage if you use the methods detailed in
     this file. (That's a disclaimer, folks.)  Enjoy!

                           *NOTES*
                           -------
     *Remove* any form feed characters from the ASCII file (^L)
     from inside WordStar before beginning.  These "page breaks"
     were put in by the text editor or word processor that
     created the ASCII file.

     Then:  If your ASCII file's left margin is not in column 1
     -- that is, it's offset by some amount, typically five
     columns (as in the file you are now reading), then you'll
     need to clean it up first.  Here are two ways to do it:


     1. Count the spaces from (and including) column 1 to the
     left margin of the text.  Use WordStar's Find and Replace
     function to get rid of these extra spaces.  If you
     counted five spaces, for example, use this procedure:

        Find    ^N<space><space><space><space><space>  <Return>
        Replace ^N                                     <Return>
        Options AGN                                    <Return>

     After entering ^N (displayed as ^M^J) you press the
     <spacebar> in the Find box five times, followed by <Return>.
     This Finds only CR/LF-plus-5-space-strings.  Enter a ^N in
     the Replace box: you are replacing the string with a single
     CR/LF.

     Select the Options, press <Return> and the text should close
     up to the left margin as you watch.

     After you've eliminated the offset left margin, you may want
     to repeat this Find & Replace to remove any other spaces
     (indents) that keep the text from aligning in column 1.
     Just substitute the required number of spaces in the process
     above.

     Finally, proceed with the Instructions to Find & Replace the
     CR/LFs at the end of each line.


     2. Use the technique described in WordStar News, Summer
     1989, page 8, to create a macro to turn paragraph indents
     (usually 5 spaces) into a tab.  Then use ^QA to Find the
     tabs (^I) and replace them with (nothing).  The WS NEWS
     article, in an example, defines Shorthand Macro #1 to be:

          ^Q~^QF^N<SPACE><SPACE><SPACE><SPACE><SPACE>
             ^M<SPACE>^M^D^T^I^P<SPACE>^[1

     (Type the above into the shorthand screen for macro #1.
     NOTE: Use Ctrl-P, Ctrl-Q-~ to indicate you are entering
     control characters (like the ^Q~) into the macro.  Ditto for
     ^QF, ^N, ^M, ^D, ^T, <Tab>, ^P<SPACE>, <ESC>1.  Each of
     these control-key combinations is preceded with ^P.  The
     ^P<SPACE> gives a small delay to allow you to bail out with
     Ctrl-U if you need to.  This macro calls itself so you may
     want to bail out at some point.

     Once executed this macro goes through the file and replaces
     the 5 hard spaces following a CR/LF (^N) with a tab (^I).
     In offset ASCII files with 5 spaces between the left margin
     and your text, all lines will snuggle up to the left margin
     after you go through with ^QA and replace the tabs.

     If you want to use another macro besides #1, replace the "1"
     at the end of the string with "x" for the named macro you
     want to use.

     For best results set your help level at 2 or higher.  At the
     end of the Find & Replace, the macro number will print
     on screen at the end of the file; just remove it.  Then go
     ahead and Find & Replace the tabs with (nothing).  Voila!
     Your file begins in column 1.

     After you've eliminated the offset left margin, proceed
     with the above Instructions to Find & Replace the CR/LFs at
     the end of each line.

     This 2nd procedure has the added advantage of giving you a 
     useful macro to Convert Indents to Tabs if you later import 
     any ASCII file (or *old WordStar Document files*) into 
     WordStar 5.n, since the newer versions of WordStar use a 
     "special binary code" instead of 5 spaces for a tab.  
     This, according to the WS NEWS article, allows WordStar 
     to be very precise in where the tab stop appears, and tabs 
     are "completely font independent."
 
     The disadvantage is that you create a macro that replaces
     5 spaces with a tab.  If your ASCII file's offset margin has
     greater or fewer spaces than 5, you'll need to adjust the
     macro above accordingly.  No big deal, but you'll have to
     reset the macro for differing ASCII files.  For other than 
     5-space margins, then, using the first method will be easier.

                           ** END **