NAME
    Sentences.AVf, version 1.1 (08-Aug-92)


DESCRIPTION

    Sentences is a flow written to show synchronous use of ARexx in
    AmigaVision.  It uses a combination of string files and separate
    ARexx scripts to perform various functions on a sentence that
    the user enters.

    Sentences displays a sentence in the first text box and the
    number of times each letter occurs in the sentence in the second.
    Below and to the left of that are three boxes showing the number
    of words in the sentence, the number of characters (including
    punctuation and spaces), and the average number of characters
    per word.

    If the values for letter occurrences do not show up, check to
    make sure the path in the "FIND OCCURRENCES OF EACH LETTER"
    execute icon points to the ARexx script, occur.rexx.

    In the lower-right part of the window are several command gadgets.
    There are four commands available on the primary screen.

    QUIT:  To exit the flow, select the close gadget in the upper-
        left corner of the window.

    INFO ON SENTENCES:  Selecting this gadget displays this text.
        See below for information on how text gadgets work.

    ENTER NEW SENTENCE:  Creates an input gadget over the previous
        sentence.  Use <RIGHT-AMIGA>X to clear the field, type a new
        sentence, and press <RETURN>.

    EXAMINE OCCUR.REXX:  Displays the ARexx script used to count the
        occurrences of each letter in the sentence.

    There are five commands in a text window.  The close gadget in
    the upper-left corner closes the text window.  The four arrows
    in the lower-right move the text.  Single arrows indicate line-
    by-line, double arrows indicate page-by-page movement.


DISCUSSION

    There are three EXECUTE icons in this flow that use ARexx to do
    specific calculations.  Let's examine each of them:

    CALCULATE AVG. CHARACTERS PER WORD
        This icon uses a fairly long string file (rather than a
        separate script) that needs to return a single value, the
        average.  Written out, the icon contains this program:

            options results
            getvar sentence
            s = result
            w = words(s)
            if (w==0) then return 0  /* No words, no average! */
            l = 0
            do i=1 to w
                l = l + wordlength(s, i)  /* Find # letter each word */
            end
            return (l/w)    /* Calculate and return the average. */

        There are a few things to note.  Originally the sentence was
        passed as "s='[sentence]'", but since the data was a sting
        that could contain single or double quotes, the script would
        get confused about what was and wasn't the string.  Unless
        you are sure your data contains no such problems, use GETVAR
        rather than directly passing the value into the string file.
        This also will keep capitalization correct and will prevent
        string overflow in the EXECUTE icon's FILE gadget.

        Note that the characters per word includes punctutation.  It
        is left as an exercise to make this script ignore punctuation
        for this function.  See occur.rexx for a possible solution.

    CALCULATE # WORDS, # CHARACTERS
        This EXECUTE icon is similar to the previous one, but since
        it must return two values, it uses SETVAR rather than RESULT.
        The ARexx string file is as follows:

            options results
            getvar sentence
            s = result
            setvar nwords words(s)
            setvar nchars length(s)

        Note the space savings by using the ARexx expressions words()
        and length() as arguments for the setvar commands.

    FIND OCCURRENCES OF EACH LETTER

        This icon uses a separate ARexx script called "occur.rexx".
        You can view the script via the flow or any text viewer
        or editor.

FILES
    sentences.ilbm      background screen for program
    textwin.ilbm        background for text windows
    textgad.win         up/down page/line gadgets for text windows
    occur.rexx          ARexx script that counter letter occurrences
    sentences.doc       doc file for AmigaVision flow
    beep                response beep for all gadgets


NOTES
    BUG FIXES:

    1.1 (08-Aug-92)
        Original version returned improper values for both string
        file scripts because it originally passed the sentence as
        a parameter in the execute icon.  For example,

            "setvar words ('[sentence]')"

        would return improper values if the AmigaVision variable,
        sentence, contained ARexx string delimiters like " or '.
        To correct this, the string file now plucks the appropriate
        value directly from AmigaVision using GETVAR.

        Obscures the sentences window close gadget when in a text
        window since the gadget is inactive.

        Added extra line of text for letter count since a sentence
        with more than 15 different letters would cause the string
        to truncate in the (then single) text object.

        Fixed bogus values for average letters per word when string was
        empty.  This was caused by dividing the number of letters (0) by
        the number of words (0).