NAME
seetxt/seeman - GUI text file and manual page ("manpage") viewer for X
windows.
SYNOPSIS
seetxt [textfile] [-x search term]
seeman [manpage] [-s section] [-x search term]
DESCRIPTION
Seetxt and seeman (collectively, "see") are the same program, but the
name you use to call it indicates whether you are opening a man page or
a regular text file. If there is no filename on the command line, both
words mean the same thing. See is a lightweight, read-only text file
viewer capable of displaying unix-style manual pages. It has a number
of unique features, such as saving mark-up for viewed files while
leaving them unaltered. Document "meta-data" is maintained
independently for each user and loaded automatically, allowing you to
keep bookmarks and highlights for read-only system files (including man
pages) in a simple and intuitive manner. See also does layered finds,
hyper-linked apropos searches, and can be set to monitor an existing
file (such as a log) for changes.
By default, see runs in "server mode": command-line requests will be
sent to the running server rather than starting a new instance. This
is explained in more detail under "SERVER MODE", below. The primary
intent is to facilitate integration with file browsers, most of which
allow you to register a command to use for viewing a text document.
See uses the titlebar to issue some program messages, so pay attention.
You can DRAG AND DROP a text file from another application window into
the see text area to view it (this does not move or copy the file
anywhere, and is not applicable to man pages).
INVOCATION OPTIONS
To start "see" (or to send a request to the existing one), use either
seetxt or seeman, then the file name, then any options. If no filename
is given, a new instance of see is launched. If the filename itself
begins with a dash, use the full pathname or "./". You can also view
out-of-path manual pages by using the full pathname or "./". See will
refer to such pages (in the filelist, etc.) as belonging to section
"***".
All options are a single character preceded by a dash.
-s section
Used to indicate a manual page section to use instead of the
default, eg. "seeman printf -s3". Obviously, do not use this
with out-of-path manpages.
-x term
See will perform an initial find-all text search for "term",
highlighting all instances.
-K The see server is actually a forked process which should shut
down when it’s parent process (the GUI) does (so when running in
server mode, there will be two pid’s). "-K" literally issues a
"killall -9 seetxt & killall -9 seeman" which will destroy all
running instances, visible or not, in order to free the local
socket used by the server. Generally this is unnecessary and is
simply provided for occasional convenience.
-v Show version. This documentation is for version 0.61.
-h Show a helpful "usage" message.
TOGGLES, INDICATOR LIGHTS, AND THE VISIBLE INTERFACE
There are five toggle buttons on the see interface, two of which look
like little round red lights that blink green when set. Click directly
on the light to activate it. The leftmost light toggles the server on
and off (see SERVER MODE, below). The rightmost light sets a watch on
the current file, which means it will be reloaded at an interval to
include any new changes. The default for this interval is ten seconds
(see CONFIGURATION, below). NOTE: Files over a default 1 Mb are not
reloaded -- they are tailed. This means if the file size has
increased, an amount equal to the difference will be taken from the end
and added to the display. That works fine if "the change" was an
addition to the end (such as occurs with a normal log). But if you
want to monitor a very large text file for other (random) changes, you
will have to reload via the filelist. This does not apply to man
pages. You can change the default 1 Mb limit, see CONFIGURATION.
The three buttons in the center, around the text entry, are controls
for text searching. If you type something into the text entry and
press enter, see will perform a "find all" style search, highlighting
the term in yellow where found and moving the view to include the first
instance. This may take a while for numerous finds in large files (eg,
several minutes for 50,000+ finds in 10 mb of text, depending on your
hardware) -- the titlebar will read "Searching for" while the search is
in progress, and switch back to the file name when finished. You can
now advance the cursor to the next instance with ctrl-n, and back to
the previous instance with ctrl-p (hold these down to scroll). If you
toggle "push" and enter a new search term, all the instances of the
last search will change to a purple highlight and the new term will be
yellow. Reloading, or setting a watch which causes reloading, will
erase the highlights. Don’t worry, there’s a command history (see
below).
Normally, searches are case-insensitive. To make the search case-
sensitive, toggle "case". To process the search term as a regular
expression, toggle "regexp" (eg: to find "for" but not "foreach",
search for "\bfor\b" as a regexp; more information on using regular
expressions is available on the www). The number to the left of the
text entry shows the number of instances found in the last search. The
text entry has a command history which is not saved. To flip through
the history use the up and down arrow(s). If you are feeling lazy and
don’t want to move the mouse, you can use the old "ctrl-/" to set
cursor focus to the command entry after clearing it, ready for your
next move.
There are a few key combinations that may be useful in navigating the
text area: alt-left moves to the beginning of a line, alt-right jumps
27 characters at a time. When you load a file from the file list, see
tries to pick up where you left off, so the normative "ctrl-home" may
be useful as is ctrl-end.
MAIN MENU
The main menu is invoked with the right button when the mouse pointer
is in the main text area. All the entries have ctrl macros or
"hotkeys" which work anywhere, if appropriate. There can be as many as
twenty items on the menu if you have a seedata file and "copy to"
directory defined in ~/.seeconfig. Some items (eg, copy, help), are
self-explanatory and not included here.
file list (ctrl-f)
See maintains a list of previously viewed files, in "last in,
first out" order. You can select a file from this list by
double left clicking on it. See does not use tabbing, but when
you switch files, the last position of cursor is recorded, so
you can switch back and forth between files and maintain a line
position without bothering to place a bookmark, etc. That’s why
I decided to use a crosshair cursor: if you know where you want
to return to, remember to leave the cursor there before you load
the next file. This all depends on the existence of the
"filelist", which if you don’t define one see will use a default
in its runtime directory (see CONFIGURATION).
see bookmarks (ctrl-s)
If any bookmarks previously existed for the current file (in its
current filesystem location!), they will be loaded with the
file. Also included in the view are any fresh bookmarks, which
are automatically saved (if you have a seedata file). Bookmarks
are displayed as a line number and, to help identify them, the
first 31 characters in the line (if the line is blank or
contains less than 31 characters, two or more text lines may
appear next to the number). You move to the bookmark by double
left clicking on it. You can DELETE a bookmark from the list by
using both buttons/button-3. Bookmarks are saved automatically
as they are placed and deleted. See loads bookmarks based on
the full pathname of the file (except for man pages), so if the
file has been moved, the saved bookmarks will not appear.
However, the bookmark index used for all files is itself just
one plain text file which can be easily edited if need be (see
CONFIGURATION, below).
place bookmark (ctrl-m)
Add a new bookmark for the line containing the text cursor.
Bookmarks are automatically saved (if you have a seedata file).
reload (ctrl-l)
This updates the display to reflect the current state of the
file. With files over 1 MB, the file is "tailed" (see NOTE in
the previous section), which is useful for long logs, etc. To
actually reload the entire file (if it is that big), use the
file list (the first file in the file list is always the last
file loaded). The cursor and view will return to the same line
number as before (which may or may not be the same line,
obviously), unless this is a large "tailed" file, in which case
the view moves to the end.
apropos search (ctrl-a)
List the results of an "apropos" search for man pages in the
main text area, using whatever term is in the bottom text entry.
Individual page names are double underlined green and hyper-
linked. Double left click (with the familiar little hypertext
hand pointer) to display.
(un)number lines (ctrl-3)
Add or remove line numbers on the left. Line numbers are only
available on files with less than 100000 lines. When performing
searches on files longer than ten thousand lines, it is
recommended you turn line numbering off first.
bold blue (ctrl-h)
This applies a "bold blue" tag to the currently selected text.
This mark-up will appear again in see whenever you load this
file (if the path is the same), until you "untag" it.
italic red (alt-r)
Applies an "italic red" tag to the currently selected text.
What was just said about italic red is equally true of bold
blue.
untag (ctrl-u)
Removes any tagging/mark-up from the currently selected text.
wrap mode (ctrl-w)
Gives you three choices for breaking lines longer than the
display: no wrap, wrap on word, or exact wrap. The default is
wrap on word.
send to editor (ctrl-e)
This issues a user defined command to send the file to a text
editor. Personal fav: "vim --remote". However, since most
installations do not have vim compiled this way, the default is
"gedit". To find out how a user can define this command, see
CONFIGURATION, below.
copy out (ctrl-o)
This will appear if you have a valid "copy to" directory defined
in your ~/.seeconfig file. It takes whatever is in the text
entry as the name for the file and copies the contents of the
text buffer to this file, with the "copy-to" path appended (you
can include subdirectories, and parents via ../../). If the
buffer contains a text file, the new file will be an exact copy.
NOTE: If you have text selected, see will only include the
selected text in the new file, so you can save part of the
buffer rather than all of it. Copy-out is most useful in
combination with the next option...
execute (ctrl-x)
This executes whatever is in the text entry as a command via the
shell and prints the output in the text view buffer. You are
welcome to attempt any command you wish here; see updates the
display, so you can view the output of (for example) wvdial as
it happens. However, you cannot interact and this is not really
intended for use as an actual terminal or console, but more for
performing operations on the content of the text buffer, which
see will write out to a temporary file, substituting the temp
file name (~/.seeTMP) for SEEBUF if you include "SEEBUF" in the
command. EXAMPLE: if you want to see only the lines in the
buffer containing the word "word", type ’grep word SEEBUF’; this
will clear the display and print the result as if the previous
display were a file you just grepped. But watch out: SEEBUFF
does not count! IMPORTANT: If you have text selected in the
display, see will only use the selected text for the temp file,
so you can perform such an operation on only part of the buffer
rather than the whole thing. You can save your results using
"copy-out", above, and in fact this option will only appear in
the menu if you have a "copy to" directory defined (see
CONFIGURATION). By default, see redirects stderr to the display
as well by appending "2>&1" to the commmand. If for some reason
you do not want this, set "no redirect" (see CONFIGURATION
again). You also get the return value (usually 0) in the
titlebar.
reconfigure (F2)
This reprocesses your configuration file (~./seeconfig) and
shows you the "Configuration" screen again. If the choices that
appear there are not what you wanted, there is a mistake in the
file. See does not reset everything first, so if you remove a
line such as "seedata:" or "text font:" they will remain set to
the same value as previously until you restart.
SERVER MODE
The only way to load a new file into a running instance of see (unless
it’s in the "file list", above) is to use drag n’ drop, an apropos
search (for manpages), or the server.
"Server mode" allows you to send remote commands to see, primarily so
that it can be included in the user menu of a file browser, operated by
some other application, or operated from a command-line. EXAMPLE: To
use see with GNOME’s nautilus file browser, click "open with" on a text
file, select a custom command, and type "seetxt". From now on,
nautilus will offer you the option of viewing text files with seetxt.
While the server is running, a green light on the left will be
blinking, and any command line invocation which includes a filename or
manpage will affect the server, and a new instance of see will not be
launched (this includes requests from other applications such as
nautilus). Most web browsers work this way -- if you click on a link
in your email client, it will appear in the running web browser and not
launch another one. So, using the F2 user menu of midnight commander
(another example), you could run see and mc side by side and opt to
view selected files in see rather than using mc’s internal viewer.
The server uses a local socket which defaults to ~/.seesock but it can
be set in the configuration file -- this way, users on a network can
each run their own server. Although it should not usually happen, if
you try to start see and keep getting told that a server is already
running when you don’t see one anywhere, try "seetxt -K" (see
INVOCATION OPTIONS, above).
Only one server is allowed per socket. Requests are sent to the socket
listed in .seeconfig, if there is one. You can turn a server off by
clicking the flashing green and red indicator on the left side of the
interface. If there is no server running, a command line invocation
will start a new instance of see with a running server. Drag and drop
works with or without the server on.
CONFIGURATION
See does not require any configuration to work, although without it you
cannot save any bookmarks. An example configuration file is installed
into INSTALLDIR/share/seetxt-runtime (INSTALLDIR is set at build time,
probably /usr/local if you built from source and didn’t choose anything
different, or /usr if you installed from a pre-built package). Copy
.seeconfig into your home directory and adapt it to your needs.
Configuration can affect the following:
· text font (eg, "text font: helvetica 12")
· text area dimensions (eg, "dimensions: 1200 800")
· file load confirmation: normally, see asks you to confirm when a
new file is to be loaded. You can skip this by including "no
confirm:" on a line by itself in ~/.seeconfig; file load
confirmation windows should appear on top of the see main window,
but when working across different workspaces they may appear in one
place or the other. Using "no confirm", the file will just load
without the user being asked anything.
· "seedata:" this is the location of a text file to store mark-up and
bookmarks in, eg. "seedata: /home/user/seedata". DO NOT USE THE
TILDE (~) anywhere in ~/.seeconfig. With or without a config file,
the first time you use see, it will create a seedata file for you
(defaulting to ~/.seedata). This is the only permanent file
automatically created in your home directory.
· "filelist:" this is the location of a text file to keep the history
of viewed files in. It defaults to INSTALLDIR/share/seetxt-
runtime/filelist, which is world read/writable. Multiple instances
of see may share the same filelist; it is not locked or held open.
· "seesocket:" a path and name to use as the socket for the server;
the default is ~/.seesock (again, do not use a tilde). The full
length of this pathname cannot be more than 106 characters. DO NOT
ACTUALLY CREATE THIS FILE.
· "watch interval:" is the number of seconds between updates when a
file is "watched" (using the right side blinking toggle, see
TOGGLES AND INTERFACE, above); the default is ten seconds. NOTE:
The light blinks at a constant rate unrelated to the watch time.
· text area background (eg, "background: CornflowerBlue") The color
tags used by see (red, blue, green, and cyan) are reasonably high
contrast, but if you want to adjust the background for any reason
pick a color from /usr/share/X11/rgb.txt (except ones with spaces
in the name), or use the hexbyte RGB format (#ffffff).
· the file size boundary at which to use "tailing" rather than a
complete reload (eg, "tail at: 5000000"). By default 1000000
bytes. See the NOTE at the beginning of TOGGLES, INDICATOR LIGHTS,
AND THE VISIBLE INTERFACE.
· a directory into which to place files from a "copy out" operation
using the MAIN MENU. eg, "copy to: /home/user/Desktop". If you do
not have a copy-to directory, you cannot perform any copy-outs.
· stderr redirection with the "execute" menu option (see above). To
turn stderr redirection off, include "no redirect" on a line by
itself.
· editor command (eg, "editor: vim --remote"); see MAIN MENU above
for a more detailed explanation. Incorrect values in your
.seeconfig file may cause a malfunction ;)
ERRORS
Most error messages, either in the titlebar or a pop-up, should be
self-explanatory.
Short Read on file
This can happen if you try to load a non-text file, since see
will stop at a zero byte, meaning the amount of text read is
less than the actual file length.
Could not create temp file
See uses your home directory for two very short lived possible
temporary files, .seeTMP and .seeTP (these should never be left
behind as garbage and you can erase them if you find them).
Without the permission to do this, functionality will be
reduced.
Unable to update filelist! (Error #3)
This will only happen if see is able to read the filelist, but
not write to it. In that case you either need to change/add the
"filelist:" entry in ~/.seeconfig or have the permission to
write the file. The default system wide file list should have
been set mode 666 at installation; if not, your system
adminstrator needs to "chmod 666" the filelist.
Can’t Validate Text (Error #4)
There is a non-utf8 character (something unprintable) in your
file.
Out of Memory
Your computer will never run out of memory, I promise.
COPYRIGHT
Copyright (C) 2008, 2009 Mark Eriksen. Permission is granted to copy,
distribute and/or modify this document under the terms of the GNU Free
Documentation License, Version 1.3 or any later version published by
the Free Software Foundation (http://www.gnu.org/licenses/fdl.html).