AFC (Automatic File Comparator)
Release 2.0
John Malpas 11/91

Using Simple AFC (executable: AFC.EXE)

Invocation
    AFC may be invoked with one argument:
        afc $file1
    in which case it will use 20 lines at the top of the screen as a window
    onto $file1, and 5 lines at the bottom of the screen as a control 
    window. 

    Note that a file name on the command line may be specified in the form:

        $file:line number
    eg.
        \afc\readme:25
    in which case FAFC will read the file and position the cursor on line 25. 

    AFC may be invoked with two arguments:
        afc $file1 $file2
    in which case it will use 10 lines at the top of screen as a window 
    onto $file1, 5 lines in the middle of the screen as a control window,   
    and 10 lines at the bottom of the screen as a window onto $file2. The   
    two files may be compared. 

    AFC may be invoked with three arguments:
        afc $file1 $file2 $file3
    which is the same as invoking it with two arguments except that $file3
    becomes the default output filename. 

    AFC may be invoked with no arguments:
        afc
    which is the same as invoking it with two arguments except that it will 
    look for three file names on the first three lines of the File buffer   
    (eg. the file "files.afc" in the current directory) and use these names 
    as the names of its file arguments. 
 
    Note that saving a file (see Save below) leaves your current position 
    in the files in the File buffer, so that invoking AFC with no arguments 
    is a good way to resume what you were doing in your last AFC session.   

The Action Screen
    After invocation, you will see the following Action screen in the 
    control window: 

 Action
 e E   s     w W    r R   c       q
 edit  save  write  read  compare quit

    This screen, as all control screens, expects a single character 
    command. It responds to the following eight characters, and ignores any 
    other character: 

    e (edit):
        Begin editing the file in the window 1 (the top window).
    E:
        Begin editing the file in the window 2 (the bottom window), if any.
    s (save):
        Save the file in window 1 (and the file in window 2, if there is 
        one) to a file of the same name, but with the extension ".sav". For 
        instance, if you are editing the file 
            "readme.txt"
        this command will save it to
            "readme.sav".
        When a file is saved, a record of where you were in the file when
        saving occured is left in the File buffer in the form: 
            readme.sav:48
        meaning that you were on the 48th line. The File buffer itself is
        also saved as part of this command. 

        Note that saving occurs automatically after several file
        modifications when either editing or comparing. 

    w (write):
        Jump to the Write screen (see below); the file to be written is the
        file in window 1. 
    W:
        Jump to the Write screen (see below); the file to be written is the
        file in window 2, if any. 
    r (read):
        Begin editing (see Editing below) the File buffer in order to 
        select a file name to read into window 1. Enter a new file name, or 
        position the cursor over an existing file name, and press <Escape>  
        to select that file. 
    R:
        Begin editing the File buffer in order to select a file name to 
        read into window 2, if any (see r: above). 
    c (compare):
        Jump to the Compare screen (see below), and begin comparing the two
        files. This only works if AFC was invoked with two files. 
    q (quit):
        End the AFC session. If the file has been modified, and you have 
        not written the file, you will be alerted to this state by an 
        Attention screen, and asked to confirm that you want to quit 
        without saving. 

The Write Screen

 Write Write:               w (Write) c (Change file name)
 $fileN To File: $filename

    This control screen expects a single character command, 'w', 'c', or
    <Escape>. 

    w (write):
        Write $fileN to $filename, exactly as shown.
    c (change file name):
        Begin editing the File buffer in the control window. If there are
        already file names in the File buffer, you may] choose one by 
        positioning the cursor over the file name you want and pressing 
        <Escape>. Control returns to the Write screen, with the value of 
        $filename now set to the file name you just selected. If you do not 
        see the correct file name in the File buffer, you may add it to the
        File buffer (the same way you add a line to any file-- see Editing
        below), and then select the name you just added by pressing <Escape>
        with the cursor over that name. 
    <Escape>:
        Leave the Write screen, and return to whereever you came from. Note
        that <Escape> has the same effect from any control screen except 
        the Action screen. 

Editing
    When you begin editing a file, the title bar of the window associated
    with that file lights up. You may move around the file with the arrow   
    keys. 

    <PageUp> moves half of a screen up. <PageDown> moves half of a screen
    down. 

    <Home> moves first to the beginning of the current line, then to the 
    first line on the screen, then to the beginning of the file. 

    <End> moves first to a space after the last character on the current 
    line, then to the end of the current line, then to the last line on the 
    screen, then to the last line of the file. 

    <Tab> moves to the beginning of the next word.

    Empty lines after the last line of the file are indicated by ~ in the  
    first column of the screen. 

    By default, the edit window comes up in insert mode, indicated by a 
    green square with "I" in it on the right side of the title bar. 
    Pressing <Insert> toggles the edit window into overwrite mode, 
    indicated by a violet square with "O" in it on the right side of the 
    title bar. Pressing <Insert> again toggles the edit window back to 
    insert mode. 

    Inserting
        When you insert characters into existing text, that text is shoved
        aside to make room for the new characters. In insert mode, an 
        <Enter> key is interpreted as a request for chopping the current 
        line into two lines, at the current x position. If the cursor is in 
        the leftmost column, an empty new line will be added above the 
        current line. 

        AFC tries to keep the lines balanced (full). When the text on one
        line overflows, AFC will add a new line below and preserve the 
        margin (number of spaces at the beginning of the line) of the 
        previous line. 

    Overwriting
        When you overwrite existing text, the character about to be 
        replaced is highlighted by a violet square. In overwrite mode, an   
        <Enter> key is interpreted as a down arrow. 

    When editing a file, the <F1> key will show a help screen in the 
    control window: 

-Char  <Del>   MrkSet  F2  Search F6  UspLine  ^D   Write ^Z
-Word     ^W   MrkCopy F3  Next   F7  Usp PP   ^F   Jump1 ^J
-Line     ^S   MrkMove F4  Subst  F8  JoinLine F9   Jump2 ^K
-RestLine ^Q   -PP     ^P             Fill PP  F10  Spell F5

    These are function and control key commands that are only accessible 
    while editing a file. The explanation in the help screen is very terse. 
    Here follows a full explanation of all functions available while 
    editing. 

    <Del> (-Char):
        Deletes the character under the cursor.
    ^W (Control W) (-Word):
        Deletes the word under the cursor.
    ^S (-Line):
        Deletes the current line.
    ^Q (-RestLine):
        Deletes characters in the current line from the cursor x position
        until the end of the line. 

        Note that all of the delete commands write the characters deleted  

        into a file called "deleted.afc." If you want to get something 
        back, you can edit this file and copy it. 
    ^P (-PP):
        Deletes the rest of the paragraph, from the current line until the
        next empty line. 
    <F2> (MrkSet):
        Sets the mark on the current line. This is the way to move lines 
        from file to file, or from one place in a file to another. The 
        marked line is indicated by a + in the first column. 
    <F3> (MrkCopy):
        Copies the marked line to just after the current line, and advances 
        the mark by one line. 
    <F4> (MrkMove):
        Copies the marked line to just after the current line, deletes the 
        marked line, and advances the mark by one line. 
    ^D (UspLine):
        Removes all extra spaces in the current line.
    ^F (Usp PP):
        Removes all extra spaces in the rest of the paragraph, from the 
        current line until the next empty line. 
    <F9> (JoinLine):
        Joins as many words from line below onto the current line as will  
        fit. If no words will fit, it moves the cursor down one line. 
    <F10> (Fill PP):
        Fills lines (puts as many words as will fit on each line) in the 
        rest of the paragraph, from the current line until the next line 
        with a different margin. 
    Shift<F10>:
        Fills lines from the current line until the end of the file. 
    ^Z (Write):
        Jumps to the Write screen for this file.
    ^X (Page):
        If AFC is paging blocks of lines, ^X  will read the next block of  
        lines into the edit buffer. Lines between the beginning of the 
        current page and the current line are written to a temporary file,  
        to be dealt with later when the file is closed. Lines between the   
        current line and the end of the current page are preserved in the   
        edit buffer. Thus, ^X always preserves at least one line: If you 
        move the cursor to the last line of the page and press ^X, the 
        first line of the page through the next to last line will be 
        written to the temporary file, and the last line will be 
        preserved. 

        AFC normally pages in blocks of 10,000 lines. To cause AFC to page 
        sooner than this, set the DOS environment variable "afc_pm" to the  
        desired page size prior to invoking AFC. For example, the DOS 
        command: 
            set afc_pm=5000
        will cause AFC to page in blocks of 5,000 lines.

    AFC should be able to compare two 10,000 line files on a 256K system,  
    without any paging. Paging adds an extra complication to using the 
    program: it is more difficult to save the files while you are working   
    on them if AFC is paging. 

The Compare Screen
    This screen begins comparing the two files character by character. 
    Every difference must be resolved before Compare will continue. Of the  
    Compare screen commands, some merely alter the position of the cursor   
    in either file, while others destructively change the text in either 
    file. 

    The point of the Compare screen is to enable you to resolve all of the 
    differences between two files and to make a final copy that contains the
    best of both files. The best strategy is to decide which of the two files
    is better, and to concentrate all modifications on this file. 

 Compare
 + -  > <  x X     e E   d D   u U  c C   l L   i I
 1    2    delete  edit  down  up   copy  copy insert
           char                     char  line line

    +:
        Moves the cursor in window 1 forward one column.
    -:
        Moves the cursor in window 1 back one column.
    >:
        Moves the cursor in window 2 forward one column.
    <:
        Moves the cursor in window 2 back one column.
    x (delete char):
        Deletes the current character in window 1.
    X:
        Deletes the current character in window 2.
    e (edit):
        Begins editing the file in window 1.
    E:
        Begins editing the file in window 2.
    d (down):
        Moves the cursor in window 1 down one line.
    D:
        Moves the cursor in window 2 down one line.
    u (up):
        Moves the cursor in window 1 up one line.
    U:
        Moves the cursor in window 2 up one line.
    c (copy char):
        Copies the current character in window 2 over the current character in
        window 1. 
    C:
        Copies the current character in window 1 over the current character in
        window 2. 
    l (copy line):
        Copies the current line in window 2 over the current line in window 1.

    L:
        Copies the current line in window 1 over the current line in window 2.

    i (insert line):
        Inserts the current line in window 2 below the current line in window
        1. 
    I:
        Inserts the current line in window 1 below the current line in window
        2. 
    <Escape>:
        Leaves the Compare screen.

 Using Full AFC (executable: FAFC.EXE) 
    FAFC is largely similar to AFC, but includes some additional
    functionality. In particular, FAFC can: 

    * Build spelling dictionaries interactively;

    * Spell check a file from up to 6 dictionaries simultaneously, thus 
    enabling you to have multiple foreign language dictionaries and multiple
    technical term dictionaries; 

    * Search for text patterns across line boundaries;

    * Specify the starting position in a file by either line number or the 
    first occurance of a string; 

    * Jump to specified links to other files (and positions in those 
    files), thus enabling hypertext-style multiple document navigation. 

Invocation
    Invocation is the same as AFC, except that a file name on the command  
    line may also be specified in the form: 
        $file:String
    eg.
        \afc\readme:Invocation
    in which case FAFC will read the file and position the cursor over the
    first occurence of the string, highlighting the string. The string is   
    actually a search specification; see Searching below. 

    If the first argument to FAFC on the command line is of the form: 
        -s$searchbuf
    it will read the file $searchbuf into the Search buffer (see Searching
    below), instead of the default file "search.afc." 

    If the first or second argument to FAFC on the command line is of the
    form: 
        -f$filebuf
    it will read $filebuf into the File buffer, instead of the default file
    "files.afc." When you want to read a new file, or write a file from the 
    Write screen, you will have access to all of the names in $filebuf 
    without having to reenter them. 

    The DOS environment variable "afc_dir" specifies a directory on your 
    system where AFC related files are to be found, including "help.afc" and
    whatever dictionaries you have. A typical value for this variable is: 
        set afc_dir=\afc

    The DOS environment variable "afc_lists" specifies the names of word list
    files (dictionaries) to be loaded automatically on startup. A value for
    this variable might be: 
        set afc_lists="tibetan.sp sanskrit.sp junk.sp"

    FAFC will try to find these word lists first in $afc_dir, and then in  
    the current directory. 

The Action Screen
 Action
 e E   s     w W    r R   c       l     f      q
 edit  save  write  read  compare lists files  quit
    FAFC's Action screen has several new commands:

    l (lists):
        Jump to the Manage WordList screen. From this screen, you may load 
        additional word list files, or write out any loaded word lists that 
        you may have changed. 
    f (files):
        Begin editing the File buffer in the control window.

Editing
    There are several functions that FAFC provides while editing that AFC  
    does not. 

    ^J (Jump1):
        If the cursor in on the beginning of a file name, this command will
        cause that file to read into the other edit window (whatever edit   
        window you are in, it is the other one). 
    ^K (Jump2):
        If the cursor in on the beginning of a file name, this command will
        cause that file to read into the current edit window. 

        ^J and ^K give rudimentary hypertext capability. For instance, if the
        following line appears in the file being edited: 
            See also \afc\readme:Overwriting
        and you put the cursor over the first '\' of "\afc\readme" and press
        ^J, the file "readme" will be read into the other edit window (if
        possible), and the cursor in the other window will be positioned over
        the first time the string "Overwriting" occurs in this file. 
    <F6> (Search):
        Jump to edit the Search buffer in the control window. Enter a new
        search specification, or select a previously entered search 
        specification by moving the cursor of the line containing the 
        specification, and pressing <Escape>. See Searching below. 
    <F7> (Next):
        Find the next occurence of the current search specification. 
    <F8> (Subst):
        Replace the last matching pattern with the specified substitution, if
        any. 
    Shift<F8>:
        Replace all matching patterns in the rest of the file with the 
        specified substitution, if any. 
    <F5> (Spell):
        Begin spell-checking the file against the currently loaded word 
        lists. 

The Spell Screen
    When FAFC finds an unfamiliar word, if will invoke the Spell screen in the
    control window. Suppose you have two word lists loaded, "x.sp" and  
    "junk.sp," and FAFC has just encountered the word "junkk" in your file. 
    The Spell screen will look like this: 
 Spell
 s (skip) <Number> (add)
 0 x.sp   1 junk.sp
 junkk
 june july

    The Spell screen shows the currently loaded word lists, numbered from
    to 5: 
       0 x.sp  1 junk.sp
    Below, it shows the unfamiliar word:
        junkk
    followed by words in the word lists that may be cognates:
        june july
    The Spell screen accepts the following commands:

        s:
            Skip this word. It the word reoccurs, Spell will find it again.U
        N (where N is an integer between 0 and 5):
            Add this word to word list N. Note that if you add words to a word
            list, and would like them to be there the next time you use FAFC,
            you must save the list using the Manage WordLists screen (see
            above). 

Searching
    Search Specifications
        A search specification consists of literal words, regular expression
        word patterns, word quantifiers, and logical operators such as OR
        ({...}) and NOT (!). For instance, if you specify: 
          in the list
        it will match any literal occurance of these three words in the file,
        even if a newline is in between any two of the words. The expression: 
          in the { list file }
        will match any occurance of either:
            in the list in the file
        The expression:
          in the !list
        will match any occurance "in" followed by "the" followed by any 
        word OTHER THAN "list." 

        Regular Expressions
            Regular expressions may be used to specify lexical level pattern
            matching within words. A regular expression begins with the
            character ^ (which indicates the beginning of a word, NOT   the
            beginning of line as in other software tools based on regular
            expressions). For instance, 
              ^[Tt]he
            will match both:
                the The
            Note that the whole word must be accounted for in the regular
            expression. Thus the expression above, ^[Tt]he, will NOT match  
                 there
            However, the expression:
              ^[Tt]he.*
            will match any of:
                The the there They them ...
            Other examples:
              ^d.*ing
                (a word beginning with 'd', ending with 'ing')
              ^[a-z].*ing
                (a word beginning with any letter from 'a' to
                'z', ending with 'ing')
              ^[^a].*
                (a word not beginning with 'a')
              ^.*
                (any word)

        You may combine regular expressions with literal words,so that the
        expression: 
          ^[Ii]n the list
        matches:
            In the list in the list

        Quantification
            Any word pattern (a literal word, a regular expression, an OR
            construct, a NOT construct) may be quantified by a following 
            quantification expression. Quantification expressions begin with
            '*' (read: times) so that the expression: 
              the *2
            specifies exactly two contiguous occurances of the word "the," 

            and 
              the *2-8
            specifies any where from 2 to 8 contiguous occurances of the word
            "the." Word patterns may be zero quantified, so that: 
              in the *0-1 list
            matches:
                in the list in list 

            Further examples:
              Function ^.* 0-10 Value
            specifies the word "Function" followed within 10 words by the  
            word "Value." 
              Edit !Buffer *0-10 Buffer
            specifies the word "Edit" followed by up to 10 words, none of  
            which is "Buffer," followed by "Buffer." 

            Since the last operation is so common, there is a special UNTIL 
            (?) operator. The following two expressions are equivalent: 
              Edit !Buffer *0-10 Buffer 
              Edit ?Buffer *0-10

        Variables
            Sometimes it is convenient to isolate sub-expressions into 
            symbolic variables. The example above can be generalized to apply
            to several prepositions by adding the following two lines to the
            Search buffer: 
                Preposition = { in by from of for }
                %Preposition the list
            The first line sets the value of the variable "Preposition." 
            Variable names should be capitalized. The second line refers to 
            the variable as its first word with % directly in front of the  
            variable name. The first line may be located anywhere in the 
            Search buffer; if you press <Escape> with the cursor over the   
            second line, FAFC will find the value of the variable, so that  
            it is exactly equivalent to the expression: 
                 { in by from of for } the list

        Parsing
            FAFC finds words on space boundaries. However, you may specify 
            that certain letters always act as a word by themselves, 
            regardless of space boundaries. These letters are known as 
            "Single" words, and by default they are: 
                ., ();:!?
            Note that the space is one of them, and should be for most 
            purposes of FAFC. For instance, with the default "Single" words,
            FAFC will understand the following line: 
                The buffer is full.
            as consisting of 5 words, the last of which is "." That is, it
            will separate "full." into two words. 

            Also, by default, the only quote character is ", and words 
            inside of "'s ON THE SAME LINE will be treated as a single 
            word, for purposes of searching and spelling. 

            You may change both the "Single" character words and the quote
            characters by using <F6> to edit the Search buffer. At the end  
            of this buffer you should see two lines that look like: 
                Single = ., ();:!?
                Quote = "
            You may change either of these lines by editing the line and 
            then leaving the Search buffer with <Escape>, which causes FAFC 
            to see the new value. For instance, you might change the lines  
            as follows: 
               Single = ., ();:!?-[]"/*-<>
               Quote =
            which means that all of those characters will act as "Single"
            words, and there will no quote character. Special quote 
            characters include: 
                [ matched by ]
                ( matched by )
                < matched by >
                { matched by }
           Any other quote character is matched by itself.

    Substitutions
        Words on the right side of / in a search specification may be 
        substituted for the pattern on the left side of /, whenever that 
        pattern is found. <F8> executes this substitution. 

        For instance, with the following search specification:
             search buffer / search file
        then when FAFC finds "search buffer," and you press <F8>, FAFC will
        replace "search buffer" with "search file." 

        You may refer to a word on the left side of / in the substitution  
        by writing % followed by the number of the word. So, with this 
        specification: 
            { search delete program } buffer / %1 file
        when FAFC finds "search buffer," <F8> will replace it with "search 
        file"; when it finds "delete buffer," <F8> will replace it with 
        "delete file," etc. The expression "%1" refers to whatever actual   
        word in the text matched the word specification: 
            { search delete program }

        Referring to Intra-Word Strings
            You can mark a substring inside of a regular expression by 
            surrounding them with parantheses. For instance, the regular 
            expression: 
                ^([Tt])he
            acts exactly like ^[Tt]he during pattern matching, but when an 
            occurance of ^[Tt]he is found, you can use just the first 
            character (either 't' or 'T') in a substitution specified on the
            right side of /. The syntax is: 
                ^([Tt])he / %1.1
            where .1 refers to the first marked substring in the first word.
            You may mark up to 10 such substrings. 

            For instance, suppose you want to change every occurance of: 
                while looking
            to
                after having looked
            except that you would like it to apply to EVERY verb, not just 
            to the verb "look." Thus: 
                while ^(.*)ing / after having %2.1 -ed

            In "%2.1," 2 refers to the second matched word, eg. "looking."  
            ".1" refers to the first marked substring within that word. The 
            - in front of "ed" surpresses the space that would normally be  
            inserted between words in the substitution. 

    Using Priviledged Characters
       Certain characters, eg. '{', '*' '!' et. al. are priviledged to the 
       search language-- they indicate syntactic constructions such as OR,  
       quantification, etc. If you want to use a literal word that BEGINS   
       with one of these characters, you can escape its priviledged meaning by
       preceding it with \. Thus, 
           *1-2
       is a syntactic construct that quantifies the previous word, but 
           \*1-2
       means the literal word "*1-2".

Installation
    Make a directory to hold all AFC files, eg.
        mkdir c:\afc
    Copy the contents of your install disk to this directory:
        c:
        cd \afc
        a:
        copy *.* c:
    You should see the following files:
        AFC.EXE
        FAFC.EXE
        HELP.AFC
        X.SP
        README
    Add the following lines to AUTOEXEC.BAT, or whatever setup script you
    use: 
        set afc_dir=\afc
        rem   To use word lists:
        set afc_lists="x.sp junk.sp"
        rem   To change line length:
        set afc_ll=75
        rem   To change number of lines/page:
        set afc_pm=5000
    The you may either put the .EXE files in a directory that is already in
    your path, or add this new directory (\afc) to your path.
