WordWrap
                             ========


"wordwrap" is a text filter that rearranges the line breaks in a plain
ASCII text, preserving paragraphs (or ignoring them, if you wish :)=).
I wrote it, because I often encounter strangely formatted but large texts 
on usenet -- and because I don't own an editor like TurboText that can 
reformat paragraphs. ;-)


Usage
----- #

  wordwrap [options] <original_file >new_file

options are:

    -l<len>         output line length, defaults to 75
    -b              protect blank lines
    -i              protect indentation
    -i<indent>       " , enforcing a fixed indentation width
    -ia             \_ the same as -i, but adding a
    -ia<indent>     /  blank line before each paragraph.
    -ic             convert indentations to blank lines
    -s<maxlen>      protect short input lines
    -w              two spaces after ".", "!" and "?"
    -W              two spaces after ".", "!", "?" and ":"
    -m<width>       add a left margin
    -M<width>       ignore a left margin on the input
    -e<escword>     enable 'escaped' sections of text #

As you can see, options are case sensitive.


Notes
-----

Try "-l1": this will create ouput with one word per line. Fun! ;-)
    The -b option that preserves blank lines is highly recommended in all
cases. You will find very few texts that look good without it.
    The -i option assumes that each indented line is the start of a new
paragraph, like in this section. This will also protect the line break
of indented blocks like the options list above or the heading on top of
this document.
    Maybe you don't like the way these paragraphs are indented by only 
four spaces each (or perhaps you've even got a document with a variable
indentation width): Try -i6, this will indent anything in the text that
isn't left aligned by exactly 6 spaces, even those parts that were indented
by tabs.
    Some people feel that indentation is an inappropriate way of separating
paragraphs and that blank lines are the Right Thing to do. These folks
should love the "-ia" and (even better ;-) "-ic" option.
    When you wordwrap this text you should notice how the dashes 
underlining the section headings are wrapped in an unwanted way. Try -s20, 
this will insert a line break after each input line containing less than 
20 non-blank characters: voilą. B.t.w., it's hard to do any damage with 
this option, you might have even said -s40 or -s60. In a text originally
formatted for 75 columns like this, it is unlikely to encounter a line
shorter than 40 or 60 characters within a paragraph.
    It is common practice in english texts to separate sentences by an
extra wide space. With -w enabled, wordwrap will try its best to find these
places, by following some simple rules: Sentences are ended by '.', '!' or
'?' at the end of a word, but never by a single letter. This works 
surprisingly well (I mean, even with most abbreviations), but of course 
it is not perfect.
    Please think twice before using the -m option. IMHO, adding a left 
margin to ASCII texts is a waste of space. However, it can be useful for
printing, if you're too lazy to set a left margin in the printer prefs.
    The -M<width> option is only needed (if ever) together with the -i 
options. It strips <width> blanks from the start of each input line before 
looking for indented lines. Please note that tabs are counted as *one 
single blank*! B.t.w., this operation is almost, but not exactly the same 
as cutting a vertical block off the left margin from within a text editor: 
It is safer, because it will never remove any non-blank characters.


Escape mode
-----------

The -i and -s options cannot fully prevent that the alignment of tables
or ASCII art diagrams is recklessly destroyed. You might either restore 
such sections manually or insert a copy from the original document. And
you can keep "wordwrap" from touching them at all by enclosing them in 
"escape words".

As you may have noticed, this document is already equipped with such escape
words ("#"), and you can enable them by typing: #
 
  wordwrap <wordwrap.doc -e#

# The escaped sections will appear highlighted in the console output to
help you see what's going on.

You are free to choose whatever escape word you like (e. g. "-eESC"), but
it should be something that usually doesn't appear in your input text, at 
least not as a single word. I'd prefer "-e#" for regular texts and "-e$$" 
if that doesn't work.


Examples
--------

Most of these examples do not redirect their output, because I think
playing with the options is nicer this way. #

  wordwrap <wordwrap.doc                    ; can you read this? :)
  wordwrap <wordwrap.doc -b                 ; much better
  wordwrap <wordwrap.doc -b -e#             ; enable escaped sections
  wordwrap <wordwrap.doc -b -e# -s20        ; makes "underline" work
  wordwrap <wordwrap.doc -b -e# -s20 -i     ; for those indented paragraphs
  wordwrap <wordwrap.doc -b -e# -s20 -ic    ; do the Right Thing ;-)
  wordwrap <wordwrap.doc -b -e# -s20 -ic -w ; almost perfect

Now try some text widths:

  wordwrap <wordwrap.doc -b -e# -s20 -ic -w -l40
  wordwrap <wordwrap.doc -b -e# -s20 -ic -w -l60            ; this is nice
  wordwrap <wordwrap.doc -b -e# -s20 -ic -w -l60 >wwr.doc   ; keep it #

At last, this doc file is formatted as it should be. (Well, almost. Do
you see what's gone wrong due to "-ic"? And can you find the one sentence
that did end in a single letter, so that "-w" failed? ;-)


Known problems
--------------

Lines indented with tab characters are likely to become too long in the
output, because "wordwrap" knows nothing about tabs and counts them just
like simple spaces. Specifying a fixed indentation width like -i4 (or -i8 
or whatever you prefer) instead of -i will replace the tabs by spaces and
fix this problem. If that does not seem appropriate for the given text
layout, you must first convert all tabs to spaces, using a utility like 
"detab" (or maybe your text editor).

The notorious combination CR/LF is no problem (the CR's are simply
stripped), however LF/CR (note the reverse order) might confuse "wordwrap" 
when using -i. I don't know if this ever occurs, but if it does, you will
have to use a different text filter to strip those CR's first.

It is no good idea to place a closing escape word in the middle of a 
paragraph, as this will produce double spaces. Sorry, but I'm too lazy to 
fix this.


Credits
-------

This program was written using EdWord and the GNU C compiler.

"wordwrap" is Freeware/Mailware: If you like it, send me E-Mail: #

  wnoeker@t-online.de
  (Wilhelm Noeker)

# Thanks to K.E. Trygstad, Adam M. Costello and Jim Aites for helpful
suggestions. 
Greetings to Gerald Keegan. ;)