Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/145.lha/Snip_v1.2/snip.doc

Text File | 1986-11-21 | 11.4 KB | 248 lines

SNIP - this is my own implementation of "cutting" text from _any_
       window. I understand there is another program available to do
       the same thing; therefore I will do a better job on this than
       if there wasn't :-). BTW, I've yet to see this other program,
       named "Snipit" if I'm not mistaken. (This is _still_ true as of
       the Snip 1.2 release, 04-26-88).

Usage: snip [-p] [-c] [-s] [-k] [-K] [x_offset y_offset] [-f <fontname>]

Copyright 1988 John Russell     Freely redistributable

The latest version (1.2) has proven to be so useful that I'd be remiss
not to encourage small donations ($5 or $10) if you're so inclined :-).

5 Alderdice Place
St. John's, Newfoundland
Canada  A1B 2P8
[phone]

E-mail: [e-mail]    (...utai!garfield!john13)

Features:

    - area to be cut is outlined during cutting
    - text in target area prevented from scrolling while cut going on
    - for non-standard windows, you can tweak placement of the 8x8
      regions with command line arguments or via key commands
    - multiple save formats; the layout of the program makes it simple
      to add in your own if it isn't supported

    Currently supported:
     - print text to standard output
     - save text to PIPE: file
     - save text to clipboard
     - have text echoed as if typed, with or without carriage returns
       between lines

** New features in 1.2 **

    - new save formats (clipboard and two methods for redirection into the
      input stream)
        - the "-c" option now works, and causes text to be written to the
          clipboard
        - new options "-k" and "-K" allow you to paste text back into any
          window that you would normally type into. "-k" writes the block of
          text back using carriage returns to terminate each line, "-K"
          writes the text back as one long line.
        - new key commands 'k' and 'K' allow you to select the equivalent
          output options at any time
    - support for *any* 8 x 8 font (see SNIPGEN.DOC for details on -f option)
    - supplied program to generate font definition files for new fonts
    - extended help message
    - now detaches from CLI window so you don't need to 'run' it, and never
      eats more than 4K stack

Bugs/caveats:

    - Heliosmouse/Sunmouse type utilities hamper the operation of SNIP; you
      should disable them when SNIP is in use
    - Certain operations, such as window depth-arranging or the appearance
      of requesters, have caused me lockups in the past if they occur
      while an area of text is being outlined (since I lock the layers of
      a window which may be on the WB screen). Note that this will be an
      exceptional case since the mouse will be operating SNIP. I don't know
      about interaction with programs that use window-to-front to keep
      themselves on top of the display.
    - Outlining of text must be from top-left to bottom-right, although the
      box will follow the mouse correctly in all directions.
    - Unrecognized characters are signalled by a '?'. These will be those
      in reverse, bold, italics, or underline or special accented characters
    - the method of inserting rawkey events into the input stream may not
      work with different keymaps; I don't know how to get around this
      short of altering the internal tables I use; if I can find a way I
      will make it fully keymap-compatible
    - the new -k and -K options may overflow the output buffer of some
      programs, for instance if you paste a large section of text into a
      terminal program operating at 1200 baud. If this turns out to be a
      big problem I'll allow some form of delay in the output, but that's
      the only scenario I've been able to cause any problems in so far.

SNIP is a program I wrote for two reasons:

1) I needed something like it
2) I had heard there was a program to do it and wondered how it would be
   possible to "read" text from a window, since once the letters are plotted
   there's no record of them anywhere except as pixels on the screen

Using SNIP
----------

1. Output Destination

    The main consideration when using SNIP is deciding how you want the text
you "cut" from a window to be saved. Since I couldn't find any one way which
was good enough for all cases, I allowed 5 alternatives, and made it
possible to switch between them at any time.

Print to standard output - this is the default if you don't specify anything
    else. You may of course redirect standard output any way you like. In
    this mode, multiple writes can be done to a single file which is closed
    when the program exits. All error messages are also sent to standard
    output.

Write to pipe: file - I don't know about anyone else, but I find a pipe
    facility very useful; I imagine it's also very under-used, so if you
    don't have either of the two PD or one commercial implementations
    available I advise you to look into getting one. Basically a pipe is a
    file you can read and write simultaneously. Only some small amount of
    space is used at a time (typically 4K) so you can send a 500K output
    file from one program as input to another program without ever having
    to save anything to disk. Once the last of the data has been read, the
    file disappears.

    Thus any editor or other program that accepts straight ASCII input can
    process text you save to a pipe. This is the most common way for me to
    use SNIP - I see some interesting text on the screen, perhaps I can't
    re-display it in order to save it, and so I use SNIP to write it to a
    pipe file. Then I can copy it to disk, read it into DME, send it to the
    printer, or whatever I want.

**  In release 1.2 the pipe: I use behaves oddly. Some programs like 'type'
    read data from it correctly, but at least DME only reads the first line.
    However the new output options can be used to import text into a word-
    processor if you like. See below.

Paste to Clipboard - this is another under-used feature of the Amiga, sadly
    most editors don't use the clipboard for their cut and paste buffers.
    If they did you would be able to cut a section of text in, say,
    AmigaBasic, and paste it into another editor, or vice versa. Complete
    interchangeability, in the same vein as IFF.

**  I've implemented the clipboard section however aside from verifying that
    the data is written and seems to be in correct format I don't know of
    anything I have that will read it, so that part can't be tested.

Keyboard - the program which inspired this one (if only by reputation) pastes
    its data this way, by fooling your computer into thinking you had re-
    typed the text you snipped. This is extremely useful, so I implemented it
    for V1.2. I also give two different sub-options here... you can have the
    text printed as a column, eg line1 <cr> line2 <cr> etc, or as one long
    line. The first example allows you to import a section of text unaltered
    into something like a word-processor, the second allows you to do
    something like type 'delete' and snip a bunch of filenames which will be
    pasted back into the command line. When either of these output modes are
    selected, the next window to be activated after some text is cut will
    receive the text.

2. Interaction (keyboard/mouse control).

    When the SNIP window is active, the RIGHT mouse button can be used to
outline a rectangular area of text within whichever window the mouse is
currently over. After the text of the area has been interpreted the area
will flash to let you know it is done. While you are operating on the window
it will not change (eg scroll).

    Due to the need to move the mouse among many windows, utilities such as
Heliosmouse must be disabled while running SNIP. I have an idea which may
let Heliosmouse run as normal _except_ when SNIP is operating, and this
will probably be the next addition I make. Sorry, I've been busy and only
spent the last day updating SNIP after a few months away from it.

    All command-line options can be changed by using the keyboard while SNIP
is the active window, except the font selection. The current key commands are:

    - s: change output destination to standard output (usually the CLI window)
    - p: change output to the file pipe:snip
    - c: change output to the clipboard (currently only prints a warning
         message)
    - k: change output to the keyboard
    - K: same as k except text is pasted as one long line

    - u: move the expected location of characters in a window UP by 1 pixel
    - d: move the expected location of characters in a window DOWN 1 pixel
    - l: move the expected location of characters in a window LEFT 1 pixel
    - r: move the expected location of characters in a window RIGHT 1 pixel

3. What to do with the PIPE: file.

    What I personally do is to create a macro within my favourite text editor
(DME) to insert the text straight into the editor window. Here is the DME
syntax:

    map s-f1 `insfile pipe:snip'

    You may wish to surround the new area with blank lines or do some more
formatting on it, but just the command to "read the file pipe:snip into the
editor window" will work with _any_ word-processor or editor that supports
such an operation (almost all).

    BTW, this allows me to use "cut and paste" between multiple windows in
editors that don't have built-in support for it, like, what a coincidence,
the version of DME that I use :-) !

** In V1.2 DME behaves oddly using the above example, but some other programs
   don't so it's still quite useful.

Syntax & Examples
-----------------

snip              <-  program will print all messages to the CLI (default)

snip >prt:        <-  redirect output to the printer. You can cut
                      multiple pieces of text and have them all
                      printed this way.

snip >df0:file    <-  same deal, except text is all saved in a file

snip -p           <-  text is written to a file called "pipe:snip".
                      If you don't have a pipe device, you can re-
                      assign pipe: to somewhere else, although this
                      is less convenient.

snip -c           <-  text is written to the clipboard, unit #0

snip 2 1          <-  to snip text from a non-standard (ie non-console)
                      window, you can specify an (x,y) offset from the
                      normal cut position within the window. For
                      instance, many versions of VT100 require that you
                      give an offset of (0,-1) to work properly. If you
                      specify one offset, you must specify both. Note
                      that you can also use the keyboard to adjust the
                      exact positioning of characters within a window.

snip -k 0 -1      <-  combination of an output option with x,y offsets

snip -f pearl     <-  use file "pearl.fontdef" or "s:pearl.fontdef" so
                      as to recognize text in the pearl 8 font

Credits
-------

    Window-locating routine by
        Davide P. Cervone
    Bug fix for setting/restoring drawmodes suggested by
        Leo Schwab
    Idea for improving efficiency via ModifyIDCMP from
        Bryce Nesbitt
    Several who responded with the idea of using a union
        to align a byte-array and achieve a speed increase.
    Clipboard code from an example by
        Andy Finkel and Bob "Kodiak" Burns
    Code to send events to the input device adapted from "Ping" by
        Chris Saulit
    A timely reminder when I had quite forgotten about SNIP from
        Phil Kasten
    SetFont by Dave Haynie