@database wordwrap.guide

@node MAIN

                             WordWrap v2.0
                             =============
                         © 1997 Wilhelm Nöker


Introduction
~~~~~~~~~~~~
"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 even with an editor like TurboText or EdWord  
that can reformat paragraphs, reformatting a whole document is still a
rather tedious job.

Select a topic for more info:    @{" How to use it " link usage }
                                 @{" Examples " link examples }
                                 @{" Known problems " link problems }
                                 @{" Contacting the author " link contact }
                                 @{" Thanks and credits " link thanx }
@endnode

@node Usage

"WordWrap" is invoked from the CLI.  It processes its files from standard
input to standard output, so you have to use Shell file redirection:

  wordwrap [options] <original_file  >new_file

Options are:

    -l<len>         output line length, defaults to 75
    -b              protect @{"blank lines" link blank}
    -bc[<indent>]   convert blank lines to indentation
    -bC[<indent>]   like -bc, but don't indent after groups of blank lines
    -i              protect @{"indentation" link 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" link short}
    -w              @{"two spaces" link wide} after ".", "!" and "?"
    -W              two spaces after ".", "!", "?" and ":"
    -m<width>       add a @{"left margin" link margin}
    -M<width>       ignore a left margin on the input
    -a<dstring>     @{"delimiter string" link delim} that will always start a new line
    -z<dstring>      " , will always end an output line
    -A<dword>       like -a, but only matches against whole words
    -Z<dword>       like -z,  "
    -e<escword>     enable @{"'escaped'" link escape } sections of text

As you can see, options are CASE SENSITIVE.

@endnode


@node blank "Blank Lines"

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 -bc and -bC options are intended to save vertical space when printing 
texts with many small paragraphs.  The start of a new paragraph will be
indicated by an indented line, while blank lines between the paragraphs
will be dropped.  Groups of more than one blank line will not disappear 
completely, they will only be reduced by one.  With -bc, the line after 
such a group will be indented, as one should expect it.  However, with 
-bC, this following line will remain left aligned.  The reasoning is that 
the paragraphs are clearly enough separated by the blank lines, anyway.  
Choose whatever method you like better.

The default width for such newly generated indentations is 4 spaces.
You may override this setting by specifying e.g. -bc6 or -bC6.

@endnode


@node Indentation

  The -i option assumes that each indented line is the start of a new
paragraph, like in this section.  As a side effect, the line break of 
indented or centered blocks of text will also be preserved by this 
option.
        
        That 
        may apply to 
        addresses 
                                 or
                              headings.
                              ~~~~~~~~~
  Maybe you don't like the way these paragraphs are indented by only
two spaces each, or perhaps you've even got a document with a variable
indentation width:  You could change that by specifying a fixed
indentation width, for example -i4, which will indent anything in your
document that isn't left aligned by exactly 4 spaces, even those parts
that were indented by tabs.
  The -ia and -ic options are for people who feel that indentation is an
inappropriate way of separating paragraphs, and that blank lines are the
Right Thing to use.  Yes!  "WordWrap" is a weapon in the holy wars for 
the 1TPS!  :-)

@endnode


@node short "Short Input Lines"

When you wordwrap headed texts you may notice that dashes underlining
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, so you might try
-s40, too, or even -s60.  Also note that the really wide headings usually 
take care of themselves, anyway, because they won't fit onto the same 
line as their underlining dashes at all.

@endnode


@node wide "Space Between Sentences"

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 or by a word
consisting of two consonants only.  This works surprisingly well, even 
with most abbreviations.

@endnode


@node margin "Left Margin"

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.

@endnode

@node delim "Delimiter Strings"

To see how the "delimiter strings" work, you might try reformatting some
C source with -a/* -z*/ -a{ -z} -a# "-z;" or -Aelse -Zelse.  (The double 
quotes around "-z;" are needed because otherwise your shell would treat 
the semicolon and the rest of the input line as a comment!)

I don't know if there are many useful applications to this feature, but 
I needed it to reformat fortune cookie files (using -a%% -z%%). 

At the moment, you may supply up to 10 words of each category, which I 
think is plenty.  Let me know if I'm wrong. ;-)

@endnode

@node escape "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.  
But I think it's easier to keep "WordWrap" from touching them at all by
enclosing them in "escape words".  Consider this example: #

  System    | advantage   | drawback
  ----------+-------------+------------------------------
  Amiga     | nice        | not always available
  Macintosh | reliable    | only one mouse button
  PC        | compatible  | requires frequent CPU updates

# which uses "#" as the escape word and could be processed by specifying
"-e#".  Note how the #'s are placed at the end of the preceding and the
start of the following paragraph.

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.

Escaped sections will appear highlighted in the console output to help 
you see what's going on.  That's useful for debugging, if your escape
words didn't produce the expected results.

@endnode


@node Examples

You should have received three sample text files with this program (two
of them lifted from Project Gutenberg etexts, aminet/docs/etext/, one
from the web pages at Louisiana State University).  Note that most of the 
following examples do not redirect their output, because I think playing 
with the options is nicer this way.

The first file, 'Treasure.txt', is one of my favourite chapters from
"Treasure Island".  It is in a very well-behaved format already, with 
blank lines seperating the paragraphs.

  wordwrap <treasure.txt -b -l40         ; wow, it really works :)
  wordwrap <treasure.txt -b -l60 -i      ; preserves the centered heading
  wordwrap <treasure.txt -bc             ; very compact output format
  wordwrap <treasure.txt -bC             ; see the difference?
  wordwrap <treasure.txt -bC -l65 >PRT:  ; print it, if you like

'SunTzu.txt' is an episode from the life of Sun Tzu, author of "The Art
of War", with an interesting point to it (or at least some black humor ;).
Most paragraphs are seperated by indentation only, and because it was 
originally a quotation inside a larger text, the whole thing is 
accompanied by a left margin of 2 spaces.  Not so simple a format, but 
still one that "wordwrap" can be made understand.

  wordwrap <suntzu.txt -b                   ; nice try :->
  wordwrap <suntzu.txt -b -s30              ; for the underlined heading
  wordwrap <suntzu.txt -b -s30 -i           ; looks good?
  wordwrap <suntzu.txt -b -s30 -i -l40      ; no, something's wrong
  wordwrap <suntzu.txt -b -s30 -i -l40 -M2  ; this does the trick!
  wordwrap <suntzu.txt -b -s30 -ic -M2      ; like it better this way?

The last example 'StatAmWar.txt' was originally in HTML format and has
already undergone some heavy editing.  Reformatting it doesn't make much
sense either, because its large tables leave you little choice about
the line length ;).  But at least it is a good example for wordwrap's 
escape mode.  Note that I already inserted the required escape words 
("#") in the text, normally you would have to do this yourself.

  wordwrap <statamwar.txt -b -s50         ; close, but not perfect :->
  wordwrap <statamwar.txt -b -s50 -e#     ; enable the escape words
  wordwrap <statamwar.txt -b -s50 -e# -w  ; wide spaces between sentences
                                                                 
@endnode

@node problems "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 whatever you prefer) 
   instead of -i will replace the tabs by the given number of spaces and 
   fix this problem.  If that does not seem appropriate for the given 
   text layout, you must convert all tabs to spaces before running 
   "WordWrap", using a utility like "detab" (or maybe your text editor).

 * Reformatting texts with hyphen- ations in them will look rather 
   crappy.  I know, plain ASCII texts aren't supposed to contain 
   hyphenated words at all, but some of the Gutenberg Project etexts, for 
   example, do (I suppose because they were scanned from printed copies 
   that were typeset that way).
   A future version of "WordWrap" might try to put hyphenated words back
   together, but please let me know if anyone would care for such a 
   feature at all.

 * 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.

@endnode

@node contact "Contacting the Author"

"WordWrap" is Freeware/Mailware:  If you like it, send me e-mail (or a
postcard):

        Wilhelm Nöker                   Hertastr. 8
        wnoeker@t-online.de             44388 Dortmund
                                        Germany

I usually like postcards better, however if you want a reply, you should
use e-mail (or write something really nice or really important ;).

@endnode

@node thanx "Thanks and Credits"

"WordWrap" was written using EdWord Pro 5.6 and the GNU C compiler.

Many thanks to Jen Allen, who prepared this AmigaGuide file.  
Thanks to K.E. Trygstad, Adam M. Costello, Jim Aites and Kristoffer 
Karlsson for helpful comments and suggestions.  
Also thanks to Gerald Keegan, Svante Hedin, and Andre Reichl for their 
moral support. ;-)

@endnode