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.