Help file for the 'xpg' file browser utility

uniquename 2013aug05

The following text is for a 'shofil.hlp' file that is part of the 'xpg' utility, posted at the page titled 'xpg' - a text file browser, with a useful Show-All-Matches (SAM) feature.

##+#########################################################################

           A HELP GUIDE FOR THE 'xpg' TEXT-BROWSER GUI UTILITY

               of the FE (Freedom Environment) system


               A utility for rapid

                    - viewing
                    - searching
                    - extracting-and-showing-'match'-lines, and
                    - printing

               of plain text files (especially, large ones) on Linux/Unix.


                                          This help was Started: 1999 Jul 19
                                                        (for an early version
                                                          on SGI-IRIX - Unix)

                                                        Updated: 2010 Sep 17
                                                            (on Ubuntu Linux)

                                                in file .../helps/shofil.hlp

                              This help file is shown via the 'Help' button
                              on the 'xpg' GUI interface.

                                          Some relatively minor changes were
                                          made to this help on 2013aug05, for
                                          a 'stand-alone' version of the 'xpg'
                                          system, contributed to the
                                          wiki.tcl.tk site.
##+#########################################################################

TABLE OF CONTENTS

- INTRODUCTION to the 'xpg' utility

   - REPLACEMENT for old-style, command-line Text-Viewers (cat, more, pg, less)
                                 --- and for Text-Editors in which a text file
                                     might accidentally be changed

   - The 'xpg' SEARCH FACILITY (basic processing features)

      - 'Search (again)' button
      -  Case sensitivity
      -  Setting search start point
      -  No (more) matches indicator
      - 'Show All Matches' button (for extracting text)
      - 'Clear' button (for search string)

   - The PRINT FACILITY (assigning a command)

   - Some SCROLLING/PAGING Facilities

      - Mouse scrolling
         - Vertical
         - Horizontal

      - Keyboard scrolling
         - 'End' & 'Home' keys
         - 'PageDown' & 'PageUp' keys
         - 'down-arrow' & 'up-arrow' keys

- SOME APPLICATIONS of 'xpg'

- INVOCATION/IMPLEMENTATION METHODS for 'xpg'

   - Via an ALIAS (like 'xpg'), for command-line execution

   - Via RIGHT-CLICK-ON-TEXT-FILE in a file manager, like Nautilus

   - Via the Nautilus 'Open With' menu of apps

   - Via RIGHT-CLICK-ON-ONE-OR-MORE-FILE(S) in Nautilus
     --- to start a 'Nautilus script' using 'xpg'
 
   - By DESK-TOP ICON

   - Within applications (especially, within SCRIPTS)


- ADDITONAL FEATURES of 'xpg'

  - Three 'Search (again)' options - Backward, CaseSense, RegExp

  - Two 'Show All Matches' (SAM) options - CaseSense, NOT

  - The 'WinColor' and 'TxtFont' buttons
 
  - user-notifications as a big file is read (loaded) into the xpg GUI

  - single click highlight of ENTIRE full-filenames (for quick paste)


- A BRIEF LOOK BACK (an overview)


                                                                Page 2
************
************
INTRODUCTION to the 'xpg' utility:
************
************

  The 'xpg' utility is a 'Show-Text-File' utility that provides a GUI
  (Graphical User Interface)  for SHOWING  and/or  SEARCHING  and/or
  EXTRACTING-'Match-Lines'-FROM  and/or  PRINTING  a plain text file.

  For example, the 'xpg' utility is used to show this Help document when
  the Help button on the 'xpg' GUI is clicked.

  Hence, you can use the 'Search' and 'Extract-Matching-Lines' (plus or
  minus N lines) features of 'xpg' to examine this Help document.

---

  The 'xpg' utility is implemented via a Tcl-Tk script called 'shofil.tk',
  which presents the GUI interface --- with 'widgets' such as buttons,
  entry-fields, and labels --- as well as the main text-area widget.

  Hence, we may sometimes refer to this utility as 'shofil.tk' or simply
  'shofil'.

---

  This utility was devised as a more modern, X-windows version of the
  Unix 'pg' command (and the Unix/Linux 'more' and 'less' commands).

  Those utilities allowed for some rather crude page-forward and
  page-backward capabilities within terminal (command-line) windows.

  Since this utility was devised as a vast improvement of the 'pg'
  command that was available on some Unix systems, this utility
  was named 'xpg'.

           [To give credit to its Tcl-Tk foundation, 'xpg' could have
            been called 'tkpg' --- but 'xpg' is a simpler, more
            streamlined name --- with one less character to type.]

---

  The 'xpg' utility can be invoked by typing the command

                       xpg <text-filename>

  at a Linux/Unix shell prompt, on essentially any Linux/Unix workstation on
  which the FE system installs.

  If 'xpg' does not work (is 'not found'), one can define an 'alias',
  as described in the 'Implementation' section below.

  That section describes some implementation methods that allow for start
  up with a few mouse clicks (or via drag-and-drop) --- no keyboarding
  required.



                                                                Page 3
******************************************
 REPLACEMENT FOR OLD TEXT-TERMINAL VIEWERS (or for TEXT EDITORS)
******************************************

     The 'xpg' utility functions as an X-windows version of the
     show-text-in-shell-window Unix utility 'pg' -- or its cousins
     'cat', 'more', and 'less'.

     In other words, 'xpg' is meant to provide a more modern,
     GUI-interface way to present a text file to a user for browsing
     --- more modern than the old utilities like 'pg' or an editor
     utility like 'view' ('vi' with the read-only flag set).

     Editor-based viewing utilities, even GUI-style editors like 'gedit'
     or 'kate' or 'nedit', have the disadvantage that the user can turn
     off the read-only switch --- if they even have a read-only switch.
     ('nedit' does.)

     So the 'xpg' utility, not having editor capabilities, offers a SAFE
     way of viewing text files --- by making it impossible to accidentally
     alter the text being viewed.

---

     The 'xpg' GUI is nicer than 'pg' for paging & searching -- and presents
     a simple interface to a few basic functions.  Examples:

        -  'xpg' allows the user to use a SCROLLBAR for PAGING,

        -  'xpg' has a 'Search(again)' BUTTON and ENTRY-FIELD for the
           standard 'keyword' search function,

     ! AND ! , 'xpg' has a unique facility :

        - 'xpg' has a 'Show All Matches' BUTTON that gathers all the
           lines in the text file that include the 'keyword' or phrase in the
           ENTRY-FIELD --- and shows those match lines, clustered together,
           in a new instance of the 'xpg' window.

        This ShowAllMatches facility even has a 'Plus-or-Minus-N-lines'
        capability!

     This 'ShowAllMatches' feature can be highly useful to Linux/Unix
     system administrators and to application developers --- as well as
     to general Linux users.

---

     'xpg' also presents a 'WinColor' button so that the user
     can quickly choose a background color for the GUI ---
     a light-background (with dark-text automatically set)  or
     a dark-background  (with light-text automatically set).

     This allows the user to quickly adjust to lighting conditions
     (or visual disabilities) --- with a background color of his/her
     own choice.

      Or the user may wish to use this color capability when they have
      several documents opened with 'xpg'. They can color-code each
      window to quickly identify the nature of each window.

      No doubt users can find other uses for this 'WinColor' option ---
      if only to make the 'xpg' window nicer for screenshots. 

---

     The 'xpg' utility has a built-in print capability that is easily
     set and easily used. The print options in some of the older Unix
     text editors were not implemented in a user-friendly way --- or
     they were frustratingly inflexible.



                                                                Page 4
*************************
THE 'xpg' SEARCH FACILITY (BASIC PROCESSING FEATURES)
*************************

     At the top of the 'xpg' GUI is an entry field into which
     you can key (or paste) a string of characters to search for.
     Then click on the "Search (again)" button to initiate the search.

     By default, 'Search (again)' looks for either lower-case or
     upper-case matches of the string entered by the user.  However
     a 'Case-sensitive' checkbutton is available, as described near
     the bottom of this guide, in an 'Additional Features' section.

     By default, the search of text in the text-widget of the 'xpg' GUI
     goes 'forward'. But a 'Backward' checkbutton is available to allow
     changing the search direction. See the 'Additional Features' section.

             [Note that the 'Show All Matches' button, described more fully 
              below, can almost eliminate the need for 'Backward' search.]

     Also, by default, the search is a simple 'direct match'. But there is
     a 'RegExp' checkbutton that allows for changing the Search to allow
     regular-expressions in the search entry-field. See the 'Additional
     Features' section.

     A simple example would be to search for '^$', which would find
     'empty' ('null') lines in the text file. That is, it searches for
     those lines that contain nothing but a line-feed character (which
     is not shown in most text viewers and editors --- other than hex
     editors).

     Even more options and 'behaviors' could be provided, than those in the
     current version, but the current intent is to keep the GUI relatively
     simple and provide the 'pg'-like text-browsing capabilities that would
     satisfy text-file browsing needs in 98% of use instances (not
     necessarily 100% of the world's or universe's use instances).


************************************
Setting 'Search (again)' Start Point:
************************************

     The user can reset the starting point of the search-forward
     feature at any time after a search is started -- by scrolling to
     a text area and clicking mouse-button-1 on the character location
     at which to re-start the search.
        
     Then click on the 'Search (again)' button.

     To check on the location of the cursor after clicking mouse-button-1
     on a character location (or at any time), you can press mouse-button-2
     (the middle mouse button).

     A popup message will indicate the line number (and column number) of
     the 'current cursor location'.

*******************************
The No (More) Matches Indicator:
*******************************

     After pressing the 'Search (again)' button,
     when no more matches are found (or no matches at all are found),
     a 'No Match' pop-up message appears. It shows a count of the matches
     found --- and the line and column numbers of the last match.

     The next time you click the 'Search (again)' button --- typically after
     changing the text string/phrase in the search field entry widget,
     that new text string search will start at the top of the text ---
     because that is where a person usually wants the search to start.

     If that is not the case, the user can relocate the search so that it
     starts lower in the file, with a simple mouse-button-1 click, at any time
     after clicking the Search button, as described above.



                                                                Page 5
*************************************
The 'xpg'  'Show All Matches'  button:
*************************************

     The 'xpg' GUI has a (unique) 'Show All Matches' button that provides
     a 'batch search' capability --- and a multiple-strings search capability.

     For a given search string, by clicking on the 'Show All Matches' button
     instead of clicking on the 'Search (again)' button, all the matching lines
     within the text file are found in one search.

     The 'batch' of matches is shown in a popup window --- which is another
     instance of the 'xpg' GUI.

     In other words, the 'xpg' utility uses itself to show the lines extracted
     by the 'Show All Matches' function.

             NOTE on 'AND' and 'OR' searches:

             You can use this feature ('xpg' showing its string-matches in
             another 'xpg' window) to advantage --- to look for matches of a
             different string, among the currently shown matches.  This is an
             'AND' search, as opposed to an 'OR' search.  An 'OR' search can
             be done using the vertical bar character, | , as described below,
             in a section on 'searching for multiple strings'.

             An example of a combined 'OR-then-AND' search is described in
             the 'NOTE on seaching for multiple-strings' section, below.

----------------

     By default, the 'Show All Matches' (SAM) search is case-INsenstive --- and
     it is an 'exact' search, not a 'regular expression' search.

           (A 'CaseSense' checkbutton is available to make the SAM-search
            case sensitive.

            In addition, there is a 'NOT' button, to make the SAM-search
            show the opposite of the match lines.

            These buttons are described a little more in an 'Additonal Features'
            section near the bottom of this help file.)
 
----------------

     The 'Show All Matches' function is modified by an option-menu button
     that allows you to show lines around the match lines --- plus-or-minus
     N lines where N may be integers like 0, 1, 2, 3, 4, 5, 6, 8, 10, 15, 25.

     If you use N = 0 (zero), the popup window shows only the 'match lines',
     and no neighboring lines.

             NOTE on showing lines BELOW (and ABOVE) matches:

                   The 'N' in the plus-or-minus-N-lines option menu serves
                   a double-purpose.  It can be used for 'Show All Matches'
                   --- but it is also used to control the number of lines
                   seen around a match as you step through matches found
                   with the ** 'Search (again)' ** button. The main utility
                   of this is so that a 'Search (again)' match that is 
                   high-lighted near the bottom (or top) of the text display
                   area has some surrounding lines visible.

                   For example, with N=3, when a match is found (high-lighted)
                   NEAR THE BOTTOM OF THE DISPLAY, when you use the 
                   'Search (again)' button, the 3 lines BELOW the match
                   (if any) will show in the text-widget of the 'xpg' window.

                   If you want more lines to show below the match,
                   you can set N=10, say, and perform the search again.

                   [If you have N=0, at least one line should show below a
                    match found with 'Search (again)'.]
     

                                                                Page 6

           A NOTE on seaching for multiple-strings ---
                ** using the vertical bar character ** :

                   With the 'Show All Matches' button, you can search for
                   one or more strings in lines of a file.  This is like
                   the Unix 'egrep' (extended grep) command.

                   You can give 'egrep' the string 'fatal|error|fail|warning',
                   where the sub-strings are separated by the 'vertical-bar'
                   character.  For a given text file, 'egrep' will show the
                   lines that contain matches to  AT LEAST ONE  of the strings.

                   This is an 'OR' relationship --- finding any one of
                   'fatal', 'error', 'fail',  OR  'warning'  in a line.
                   'Show All Matches' does the same thing as 'egrep', and more.

                                The '|' character is 'shift-back-slash' on
                                 most keyboards.  It may be represented by a
                                 *split* vertical-bar symbol on the key.

                    'xpg' goes beyond 'egrep'.  The 'Show All Matches' 
                    function will NOT ONLY show the lines containing any
                    of the multiple strings, but it can ALSO show plus-or-minus
                    N lines around those lines.

                    In fact, to the author's thinking, the 'ShowAllMatches' button
                    is like a 'eegrep' -- an extended 'egrep' --- or an extended,
                    extended 'grep'.

                    For example:
                    A 'fatal|error|fail|warning' search, plus-or-minus-N-lines,
                    can be useful on a huge text file like a log file that
                    includes many kinds of error messages.

                    The extra lines will normally be needed to see other
                    message lines that might explain the error lines found.

                    ------

                    Here is an example of a handy 'OR' search with 'xpg' ---
                    combined with an 'AND' search.

                    Let us say you are in a big company with licensed software
                    in use. There is an application which generates a license
                    checkout log file.  The log file has lines that contain
                    the string 'out:' indicating a license checkout, and lines
                    that contain 'in:' indicating a license check-in --- for
                    various 'features' of the application. The feature name
                    is in the check-out and check-in lines. Also, there
                    is a userid in these check-out and check-in lines.

                    There are no dates in the 'out:' and 'in:' lines, but
                    there are occasional 'timestamp' lines that give a date
                    and time, say every 4 hours of the day.

                    Our task:
                    We want to see the 'checkout' records for a particular
                    userid, along with date-time info. So ...

                    We bring up the license log file in 'xpg'.
                    First, we can use the 'Show All Matches' button with the
                    search string 'out:|timestamp', with N=0. 

                    This will show all the license 'features' that were 
                    checked-out during the time-period of the log file ---
                    along with the 'TIMESTAMP' records that give the
                    date-stamps that let you know on which days the
                    check-outs occurred.

                    Let us say the userid of interest is 'abc00'.  So
                    we can do another 'Show All Matches' search ---
                    ON THE PREVIOUS RESULTS --- using the string
                    'abc00|timestamp', with N=0.

                    This will filter out all the 'out:' lines that are
                    associated with users other than 'abc00'.

                    So now we see all the license 'features' that 'abc00'
                    checked-out during the time-period of the log file ---
                    along with the 'TIMESTAMP' records that give the
                    date-stamps that let you know on which days the 'abc00'
                    check-outs occurred.

                    Even if the log file is quite a few Megabytes in size,
                    these queries proceed very quickly.

                    ------

                    This example should give you an 'inkling' of the 
                    information-revealing power of these multi-stage,
                    OR-and-then-AND 'Show All Matches' searches --- which can
                    be performed with a few mouse-clicks and keystrokes.

     

                                                                Page 7


           A NOTE on seaching for special characters:

                   An earlier version of the 'Show All Matches' facility
                   required you to use additional 'escape' characters to
                   show all occurences of a special character --- like 
                   '(' or '['.

                   Some special characters --- like '(' and '[' --- would yield
                   no matches with the 'Show All Matches' button --- even
                   when there were such characters in the text file.

                   You had to handle special character searches --- with the
                   'Show All Matches' button --- by putting two or three
                   back-slash characters in front of the special character,
                   like
                          \\$      or    \\[
                   or
                         \\\$      or   \\\[

                   But that is no longer necessary.

                   NOW you can enter the single character for special
                   characters like parentheses,  brackets, braces, etc.: 

                        ( )   [ ]  { }  < >

                   In fact, you can try it out on this help file.

                   Some other special characters to try with 'Show All Matches'.

                        ~ ` @ # $ % ^ & *  _ - + = | : ; " ' , . ? /

 
                        The 'Search (again)' button will show special-character
                        matches.  It uses the text-widget 'search -exact'
                        function of Tk scripts, whereas the 'Show All Matches'
                        button uses a search technique based on the pattern
                        matching capabilities of the 'awk' report formatting
                        program.  There MAY be cases where the two search buttons
                        return slightly different results.  Effort could be
                        expended to make the two buttons work more similarly, but
                        where is the pay-back --- and, besides, "vive la
                        difference".

                   There are cases of searches involving the back-slash (\)
                   character where you may need to put double-back-slash (\\)
                   in place of a single back-slash character. This is because
                   of the special function of back-slash as an 'escape' character
                   --- to indicate special characters that should be treated
                   as a character and not as a special command or indicator.
     

                                                                Page 8
*************************
The 'xpg'  'Clear' button (for the search-string entry box):
*************************

     Users will frequently find it helpful to paste a string into the
     'search string' entry field --- from text in the 'xpg' text window OR
     from text in another window on the desktop.  But a string may be in
     the entry field, from a previous search.

     It can be inconvenient and inefficient to delete the string ---
     by MB1-stroke-highlight and hitting the Delete or Backspace key --- or
     by MB1-locating the insertion cursor in the search entry field and
     repeatedly hitting or holding the Delete and/or Backspace keys.

     Rather, it is more efficient to click on the 'Clear' button and then
     continue with the text-paste operation.

              (A text-paste operation, from-and-to X-windows, can be
               performed by swiping, i.e. high-lighting, a string of text with
               MB1 held down.  Then establish an insertion cursor with a poke
               of MB1 in the location where you want the captured text to
               begin inserting.  Then drop, i.e. paste, the text by a click
               of MB2.  This can be called an MB1-MB2 copy-and-paste or
               MB1-MB2 text drag-and-drop operation.)

                             MB1 = mouse button 1  ;  MB2 = mouse button 2
---

     If you MB1-click on 'Clear' and realize that you want back the string
     that was in the entry field, MB1-click on 'Clear' again.  The string
     will be restored.

     I.e. there is a one-step un-do capability built into the 'Clear' button.
     One click clears the entry field --- a second click restores the contents
     of the entry field.


                                                                Page 9
 ************************
 The 'xpg' PRINT FACILITY --- how to specify a print command
 ************************

     Th 'xpg' utility includes a Print button that starts up
     a printer command with the name of the text file that the user
     is browsing as an input parameter to that print command.

     In the 'stand-alone' version of the 'xpg' subsystem (that was
     contributed to the wiki.tcl.tk site), you can set a print
     command of your choosing, as follows.

     A variable named 'fePRINTcmd' is in the 'shofil.tk' script.

     Quite a few example print commands are provided --- in comment
     statements that can be de-commented and commented as the user pleases.

     Examples:
   
   #   set fePRINTcmd "kprinter"
   #   set fePRINTcmd "hp-print"
       set fePRINTcmd "cupsdoprint -P lp1 -H localhost:631"

   Choose one of these, or supply a command suited to your
   operating environment.



                                                                Page 10

 **************************************
 SOME 'xpg' SCROLLING/PAGING FACILITIES
 **************************************

 Mouse scrolling:

     The 'xpg' GUI offers a y-scrollbar (vertical scrollbar), to allow
     for rapid vertical scrolling through the text.

     There is a button labelled '<-Ybar->' that can be clicked to
     rapidly toggle (move) the vertical scrollbar between right and left
     sides of the GUI.

     At the bottom of the GUI, there is also an x-scrollbar (horizontal
     scrollbar) to allow for scrolling to see the ends of very long lines
     of text.

 Keyboard scrolling:

     In addition to mouse scrolling, with the vertical & horizontal scrollbar
     buttons, there are some keyboard controls for vertical navigation.

     The 'End' and 'Home' keys, when struck, pop the text display to the
     bottom or top of the text, respectively.

     The 'PageDown' and 'PageUp' keys allow for paging 'forward' and 'backward'.

     And the 'down-arrow' and 'up-arrow' keys allow for 'advancing' or
     'retreating' a line at a time.

     These 'keyboard-scrolling' functions can be very useful on huge text files
     where 'mouse-scrolling' is too sensitive.  The 'keyboard-scrolling' 
     allows for 'fine-tuned-scrolling'.

  -------------------------------------------------------------------------

*****************
SOME APPLICATIONS of 'xpg' :
*****************

  The 'xpg' utility was meant to be used to display the many
  text-file helps in the FE (Freedom Environment) system.

  'xpg' was also meant as a means for application supporters and developers
  (as well as 'Unix/Linux system administrators')
  to quickly browse/search/print text files, scripts, configuration files,
  message logs, lists of files or directories, license log files, etc.

  And engineers, physicists, chemists, and others could use 'xpg' to browse
  large (or even huge) files of scientific, financial, or other data ---
  such as data from CAE (Computer Aided Engineering) simulations, satellite
  collection data, weather data, stock price data, etc. etc. etc.
 
  They can use the 'xpg' utility 'stand-alone' (outside of any
  application or script) --- to browse/search/print plain text files.

  In addition, the 'xpg' or 'shofil.tk' script could be incorporated within
  any Unix/Linux/BSD application (in particular, scripts). The application
  could use the 'xpg' script to present a text file to users, in a scrolling
  mode, via the 'xpg' GUI --- and provide the powerful 'ShowAllMatches'
  capability.

  See the 'Implementation' section below. 



                                                                Page 11

*************************
*************************
INVOCATION/IMPLEMENTATION of 'xpg' :
*************************
*************************

  ***************************************
  'xpg' IMPLEMENTATION
  VIA 'alias', for command-line execution
  ***************************************

     If the site 'xpg' command does not work for you at the command line
     of a terminal window (you get a message like "sh: xpg:  not found"),
     you can make an alias, like 'xpg', for the script that starts up
     the 'xpg' text-browser window, by putting the following alias

               alias xpg="$XPGINSTALL/xpg"

     in your shell tailoring file --- typically $HOME/.bashrc --- or
     in Ubuntu 9.10, $HOME/.bash_aliases.

                     [$XPGINSTALL represents the install directory of the
                      'xpg' set of about 8 files. It is recommended that
                      an 'apps' directory in your home directory be used,
                      and install the 'xpg' system in a subdirectory
                      of 'apps', such as $HOME/apps/xpg.

                      In that case, the alias above could be written as

                        alias xpg="$HOME/apps/xpg/xpg"

                      Note that putting the installation in your home directory
                      is a good strategy, because when many people do their
                      Linux OS upgrade, they preserve their home directory,
                      while directories such as /usr get wiped out and replaced.
                      I.e. you don't have to re-install 'xpg' after doing an
                      operating system upgrade, if you preserve your home directory.]

     You can log off and log on to make the alias available to ALL terminal
     windows in your session.

     Then, at a shell prompt in a terminal window, type 'xpg'
     followed by a filename, and press Enter.

           NOTE: The shell script 'xpg' calls the Tcl-Tk script 'shofil.tk'. 
                 The main difference between calling on the
                 'shofil.tk' script and calling on the 'xpg' script is
                 that the 'xpg' script includes some code allowing
                 for starting up 'xpg' on several different files,
                 if you pass several filenames to 'xpg'.

                 In fact, 'xpg' protects you from accidentally starting up
                 too many 'xpg' GUI windows, by limiting the number of
                 filenames accepted to 8. Of course, the user could easily
                 change that limit by changing one number in the 'xpg' script.

     'xpg' runs as a 'background' process, making available the
      command-interpreter in the window in which the 'xpg'
      command was issued.

                 [The author gets frustrated when failing to
                  remember to put an ampersand (&) after the
                  command to start an application like a text
                  editor. The terminal is 'tied up' until exiting
                  the application. No such frustration with 'xpg'.
                  By default, it supplies the ampersand.]

     If you want to start 'xpg' as a 'foreground' process,
     you can use the '-f' option. Example:

                             xpg -f <filename>

     Type 'xpg' with no filename to see some brief syntax help.


                                                                Page 12

*************************************************************
'xpg' IMPLEMENTATION Via RIGHT-CLICK-ON-TEXT-FILE in Nautilus
*************************************************************

   You can simply add 'xpg' as the default application to use on a
   large number of text-type files, via your file manager, such as
   Nautilus. 

   In Nautilus, right click on an appropriate type of file
   and choose 'Properties'.   Go to the 'Open With' panel on the
   'Properties' options window, and 'Add' 'xpg' by browsing to
   the script named 'xpg' in the install directory.


*************************************************************
'xpg' IMPLEMENTATION Via the Nautilus 'Open With' menu of apps
*************************************************************

   In Nautilus, you can add 'xpg' to the 'Open with' list of
   applications. You see that list when you right click on
   essentially any file and put your mouse cursor over
   'Open With' on the Nautilus popup menu.

   You can use the 'Other Application...' option, at the bottom of
   of that list, to add 'xpg' to the list by browsing to the
   script named 'xpg' in the install directory. 


 ******************************************
 'xpg' IMPLEMENTATION
 Via Nautilus RIGHT-CLICK-ON-FILE(S) to
 start a 'Nautilus script' that uses 'xpg'
 ******************************************

   You can use 'xpg' in a 'Nautilus script', to browse files.

   For example, you can make a utility script that calls the 'xpg' script
   to show text file output from a compiled program, like the 'ls' command.

   After you put such a script in the 'hidden' directory

         '.gnome2/nautilus-scripts'

   in your home directory, you can apply that script to one or more
   selected files, as follows.

   You can navigate to any directory containing files of interest, via
   the Nautilus file manager.  Then select one or more files and
   right-click on any of the high-lighted filename(s).  Move the mouse
   cursor to the 'Scripts  >' option near the bottom of the Nautilus
   popup window.  Then slide the mouse cursor over to your script
   and click on its name.

   The script will execute and, if 'xpg' was being used within the
   script to show a set of execution messages, the 'xpg' GUI will
   popup showing the message lines.



                                                                Page 13
 
 *************************************
 'xpg' IMPLEMENTATION BY DESK-TOP ICON
 *************************************

      You can make the 'xpg' utility an icon on your desktop in the
      usual way for your desktop environment (say Gnome or KDE).

 Gnome:

      For Gnome 2.x, you can right-click on the desktop and choose
      'Create Launcher ...'.

      In the 'Create Launcher' window that pops up, in the
      'Name:' field enter a name like 'xpg', and in the 'Command:'
      field, enter the full name of the 'xpg' script. Example:
             $HOME/apps/xpg/xpg
      where $HOME represents the name of your home directory.

      To avoid keying in that fully-qualified filename, you can
      browse to the script in the install directory and simply
      click on its name.

      Then click 'OK'. (If you want to use a different icon from the
      standard Gnome 2.x launcher icon --- a platform on a spring, or
      perhaps a rocket ship --- click on that icon in the
      upper left of the 'Create Launcher' and choose a
      different icon, before you press OK.)

 KDE:

      For KDE 3.x (and 4.x?), you can right-click on the desktop and choose
      CreateNew -> Link to Application.  In the 'General' panel that pops up,
      fill in a short name for your application icon, say 'xpg'. (You can
      click on the default gear-icon in the panel, and choose a different
      icon from a large array of icons.)

      Then click on the 'Application' panel and click on the 'Browse' button
      to find the 'xpg' script you want to associate with the icon.
      (Since the 'xpg' script requires an input file, you will have to
      drag a file icon/name onto the desktop icon for your script to function.
      If you simply click on the icon, probably nothing will appear.)

      Let us assume that the 'xpg' system files were installed in the directory
      $HOME/apps/xpg.  Then, for KDE, you can use the 'Browse' button
      mentioned above, to navigate to
                        $HOME/apps/xpg
      to find (click on) the "xpg" script file.

 After you have your desktop icon:

      You can drag icons representing text files onto the
      'xpg' icon --- for browsing, searching, and/or printing.

 (Since the 'xpg' script requires an input file, you will have to
  drag a file icon/name onto the desktop icon for the script to show
  the GUI. If you simply double-click on the icon, probably nothing
  will appear --- although like 'zenity' utility, if available, will
  pop up a message window when the script is started with no
  filename supplied.) 


  *****************************
  'xpg' IMPLEMENTATION
  WITHIN APPLICATIONS (SCRIPTS)
  *****************************

    The 'xpg' GUI is generated by a Tcl-Tk script 'shofil.tk'.
    This Tcl-Tk script can be called from within a Unix shell script
    or a Tcl-Tk script.

    Since the Tcl-Tk 'wish' (window shell) interpreter is available on many
    Linux desktop/laptop/server distributions, the 'shofil.tk' Tcl-Tk script 
    can be implemented in any shell or Tcl-Tk script that runs on such a
    Linux machine.

    You can look at the 'xpg' shell script for an example of calling
    'shofil.tk' from within a shell script. That's the main part of the
    'xpg' script.  AND ...

    You can look at the 'shofil.tk' Tcl-Tk script for an example of calling
    'shofil.tk' from within a Tcl-Tk script --- because 'shofil.tk' calls
    itself to show this 'xpg' help file.

    The calling application would feed the 'shofil.tk' Tcl-Tk script the
    fully-qualified name of a text file.
 
    The 'shofil.tk' script contains many comment lines describing the
    input-to & output-from the script -- and describing the call format.

    See the 'shofil.tk' script itself for more information on
    implementation.

        (That is one of the great things about scripts. The executables
         are the source. They are human readable. So you can see
         exactly how the executable is implemented.)



                                                                Page AF.1
******************
******************
ADDITONAL FEATURES of 'xpg'
******************
******************

  - Three 'Search (again)' options - Backward, CaseSense, RegExp.

  - Two 'Show All Matches' (SAM) options - CaseSense, NOT

  - The 'WinColor' and 'TxtFont' buttons
 
  - user-notifications as a big file is read (loaded) into the xpg GUI

  - single click highlight of ENTIRE full-filenames (for quick paste)


******************************
THREE 'Search (again)' OPTIONS:
******************************

   There is an 'OtherOpts' button on the top of the GUI.
   It is a 'toggle' button.

   Clicking on the 'OtherOpts' button, shows/hides a tool bar that shows
   some check-buttons --- that can be used to modify the function of
   the 'Search (again)' button:

       - Backward  (changes the search from forward to backward)

       - CaseSense (changes the search from case-INsensitive to
                    case-sensitive)

       - RegExp    (turns on regular-expression search, instead of
                    'exact' search)

                    Then, for example, you can use '^' to indicate
                    the start of a line and '$' to indicate the end of
                    a line.

                    And you can use ' *' (space-then-asterisk) to indicate zero
                    or more spaces and '  *' (2-spaces-and-asterisk) to indicate
                    one or more spaces.


************************************
TWO 'Show All Matches' (SAM) OPTIONS:
************************************

   To the right of the 'Search (again)' checkbuttons on the 'hidden' toolbar,
   there are two more check-buttons --- that can be used to modify the function
   of the 'Show All Matches' (SAM) button:

       - CaseSense (changes the SAM-search from case-INsensitive to
                    case-sensitive)

       - NOT       (changes the SAM-search FROM extracting the match lines
                    that have a match to at least one of the one-or-more
                    search substrings --- TO extracting the lines that DO
                    NOT have a match to ANY of the search substrings)

   There are some examples of how these buttons can be used, in text at the
   bottom of any of the extract listings.

                   NOTE: At this time (2010sep), the plus-or-minus-N-lines
                         setting in the GUI has no effect when the 'NOT'
                         button is used in a SAM-search. The author has not
                         encountered a case where he really needed to show
                         plus-or-minus N lines on either side of the
                         NOT-a-match extracted lines.

************************************
The 'WinColor' and 'TxtFont' buttons:
************************************

   A 'WinColor' button and a 'TxtFont' button are on the right end of
   the 'hidden' 'OtherOpts' toolbar.

   Clicking on 'WinColor' brings up a 3-slider GUI, for specifying Red,
   Green, Blue --- for a new color theme for the 'xpg' window.

   Clicking on the 'TxtFont' button brings up a 'tk Font Selector' GUI
   --- allowing for selecting a different font for the main text widget
   of the 'xpg' GUI.

   These Colors and Fonts changes are 'temporary'. They just exist for
   that instance of the 'xpg' window. Those changes can be used for 
   experimenting to see what 'permanent' changes to colors or fonts
   you might want to make.

   The color-selector and font-selector are separate Tk scripts that
   are called by the 'shofil.tk' script. Those two scripts are
   available from the wiki.tcl.tk site:

   https://wiki.tcl-lang.org/36753 - 'A non-obfuscated color selector GUI'

   and

   https://wiki.tcl-lang.org/36788 - 'YAFSG - Yet Another Font Selector GUI'

   The 'shofil.tk' script calls on them by the names
   'sho_colorvals_via_sliders3rgb.tk'
   and
   'select_tkFont.tk'.

   If you cut-and-paste the code from those web pages into text files,
   simply put the files in the same directory with the 'xpg' and
   'shofil.tk' scripts, under these filenames --- and remember to
   give the color and font selector files execute permissions.


***********************************
NOTIFICATIONS AS A BIG FILE IS READ:
***********************************

   When 'xpg' reads a LARGE file:  After every-so-many-Megabytes,
   the user is shown how many Meg have been loaded into the
   text widget of 'xpg' --- and the user is prompted to read 'More',
   or 'Stop', or 'Exit(Quit,Cancel)'.


**********************************
SINGLE CLICK HIGHLIGHT OF A STRING in 'xpg':
**********************************

   A SINGLE-MB3-click on a filename, in the text area of an 'xpg' window,
   selects and highlights the entire filename
   --- making it easy to paste the FULL name into another window.
         (MB3 = mouse button 3)

      [In contrast, a DOUBLE-MB1-click on a (full) filename, in almost
       any X-windows or MS-Windows application, only highlights
       the text to the first special character to the right and left,
       like the 'slash' (/) character.

       It takes a shift-MB1 action to 'extend' the selection --- to
       a starting and/or ending character.]

   Use single-click of MB1, then MB2, to do the paste --- into another
   window, like an 'xterm' or 'gnome-terminal' window.

     (A single MB1 click sets the location of the 'insertion cursor'.
      A single MB2 click 'drops' selected(highlighted)-text
      at the location of the 'insertion cursor'.

      At the bottom of the 'man' help for the Tcl-Tk command 'text',
      there is a description of about 30 functions of mouse buttons
      and control keys in a 'text' Tk widget.

      These functions are pretty typical in other X-windows, like 'old' editor
      and 'xterm' windows.  The working of the 'Home' and 'End' keys has been
      changed a little bit in 'xpg'.  Instead of those keys showing text to the 
      left and right, they show text at the top and bottom of the file.)

   Actually, if you want to paste highlighted text, from 'xpg', into an 'xterm'
   window, a simple MB2 click (anywhere in the 'xterm' window) will suffice
   --- to paste the text at the end of current characters on the
   command-prompt line in the 'xterm' (or 'gnome-terminal' or whatever) window.

   No MB1 action is needed ... since there is only one insertion point in
   the 'xterm' window. 

   [NOTE: This MB3 highlight function in 'xpg' could be easily changed to
          'trim' special characters --- like parentheses, quotes, colon,
          comma, semicolon, question mark --- from the right and/or
          left end of the highlighting.  It remains to be seen whether this
          is advisable to implement, and for which characters.

          I have in mind here the case of clicking on a filename with left
          and right parentheses on either side of the name. As the MB3-copy
          is currently implemented in 'xpg', the parentheses would come along
          with the filename.

          You can always 'swipe' with MB1 --- press MB1 at the character you
          want to start copying and release MB1 at the last character you
          want to copy. So spending a lot of time on a single-click copy
          that will satisfy everyone is probably time that could be better
          spent on some other aspect of 'xpg'.]


*****************
A BRIEF LOOK BACK (an overview)
*****************

The really unique & handy feature of 'xpg' --- is the 'Show All Matches'
button.

Clicking on that button causes 'xpg' to extract ALL 'match' lines from
the text file currently being browsed with 'xpg' --- and show those
match-lines in a new instance of 'xpg'.

The 'Show All Matches' search supports looking for multiple strings,
if they are separated by the vertical-bar character (|).

Example search string:    search|match|string

If you are reading this help document with the 'xpg' utility, you
can paste that search string above, into the Search-string entry field,
and click on the 'Show All Matches' button.

See what comes up. (A couple of hundred lines.) Fast isn't it?

---

As another example, if you want to see the lines having to do with printing,
you could 
       - put 'print' in the search field
       - change the plus-or-minus-N-lines value from 0 to 4
       - click on the ShowAllMatches (SAM) button.

This is a REALLY fast way to see what this help file has to say about printing.

Similarly, you can use the search string 'match' and N-lines equal to 4 or 5
to see most of the help about the 'Show All Matches' feature.

---

Hopefully, system and application administrators, on Linux/Unix
systems, will find this 'xpg' utility of help in dealing with 

- big operating system or application files ... configuration files,
  log files, program/script code, etc.

- lists of many (hundreds of) thousands of files

- big README files in which you are searching for information on a
  particular issue, and the ShowAllMatches button will show, in an
  instant, whether that issue is addressed

- etc. etc.


The same goes for Engineering users, who typically deal with huge
data files generated from CAE and CAD/CAM applications.

Similarly, developers and users of 3D modeling applications may find
the 'xpg' utility handy to search/extract-from huge files of
geometry and animation data.

Happy text browsing!

##+############
## END OF GUIDE to the 'xpg' GUI TEXT BROWSE/SEARCH/EXTRACT-MATCHES utility
##+############

This help --- and the scripts and auxiliary files of this FE subsystem ---
are copyright 2006+, by Blaise Montandon.

You can see the help file of the FE AppMenus subsystem for a discussion
of the 'FE License' --- and a standard disclaimer.