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 used to call it indicates whether a man page or a regular text file is
being loaded. Subsequently, the invocation name is irrelevant ‐‐
the GUI can always be used to view both kinds of files. See maintains document
"meta‐data" independently for each user, 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
helps facilitate integration with file browsers, most of which allow you to
register a command to use when viewing a text document.
See uses the titlebar to issue some program messages. You can drag n' drop a
text file from another application window into the 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 server), use
either
seetxt or
seeman, then the file name, then any options.
The filename must be before the options. If no filename is given, a new
instance of see is launched, even if there's a server running. If the filename
itself begins with a dash, make sure to use the full path 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 -s 3". 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. To search for a phrase, (ie,
a term including spaces), enclose the term in quotation marks.
- -v
- Show version. This documentation is for version 0.72.
- -h
- Show a helpful "usage" message.
NOTE ABOUT SYMLINKS IN FILE PATHS: If you load a file in your current
working directory with no path, see uses the real path to that file. However,
if that directory is also symlinked, and you later load the file using a full
path to the file
with a symlink somewhere in it, see will use that
path. This matters with regard to the filelist and seedata
(bookmarks/highlighting), since that information is saved by file name
including the path, and a symlinked path will not match "the real
one".
THE NAVIGATION BAR AND FILELIST¶
Top left on the GUI are three buttons: a "Back" button, a button
containing the name of the current file, and a "Forward" button. The
middle button will present the Filelist. This is 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 (which moves that file to the top of
the list). You can also use the Back and Forward buttons, with or without the
Filelist window open, to skip through the list (files loaded this way do not
change position). When you switch files, the last position of the cursor is
recorded, so you can switch back and forth between files and maintain a line
position without bothering to place a bookmark. This information is saved for
all files in the list, even between invocations, and is shared between
instances. The Filelist is kept on disk and you should define a location for
this in your configuration (see below); if not, see will use a global list
from its runtime directory.
You can edit the Filelist on disk manually if desired. Note that the format
changed between 0.61 and 0.70, and your old Filelist will not be compatible.
To correct it: all file and manpage names must be followed by a |, then the
(section) in parentheses for man pages. Optionally, there is then a $NUM where
"NUM" is an integer ‐‐ this is the character position of
the cursor on load. The bar itself (|) is mandatory as is a section for
manpages. You will be warned about invalid entries. Also read the NOTE ABOUT
SYMLINKS IN FILE PATHS under INVOCATION OPTIONS, above.
BOTTOM TOGGLES AND TEXT ENTRY¶
There are five toggle buttons along the bottom of the see interface, two of
which look like little round lights that blink green when set. Click directly
on the light to toggle it. The left light toggles the server on and off (see
SERVER MODE, below). The right 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 adjust the default 1 Mb limit, see
CONFIGURATION. This does not apply to man pages. If the cursor is at the end
of a watched file, the display should remain there even if the file has grown.
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. You can now
advance the cursor to the next instance with ctrl‐n, and back to the
previous instance with ctrl‐p. 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, making it easy to repeat searches by using the arrow keys
in the text entry (this history is not shared or saved between invocations).
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). These
are POSIX style regular expressions, as with the "grep" command. The
number to the left of the text entry shows the number of instances found in
the last search. You can use "ctrl‐/" to set focus to the text
entry instead of clicking in it with the mouse.
There are a few key combinations that may be useful in navigating the text area:
alt‐left or Home moves to the beginning of a line, alt‐right jumps
27 characters at a time, End moves to the end of the line. Ctrl‐home
moves to the very beginning of the document, ctrl‐end to the very 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, quit), are self‐explanatory
and not included here.
- file list (ctrl‐f)
- This opens the Filelist window (see FILELIST above).
- see bookmarks (ctrl‐s)
- If any bookmarks exist for the current file they will be
loaded with the 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). This requires that you have a
"seedata" file defined in your configuration.
- 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 to display the page.
- (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. Tip: when untagging, use a decent swath around the tag you
want to remove in case there is whitespace included. This may seem
irrelevant, but if the file changes and you have groups of one or two
whitespace characters highlighted by accident, those "hidden"
highlights will suddenly appear. They can also be confusing in the seedata
file (see CONFIGURATION, below).
- 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 *nix installations do not have vim compiled this way, the
default is "gedit". 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). If the buffer contains a text file, the new
file will be an exact copy. 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. See keeps the
display updated until the command exits. You cannot interact and this is
not really intended for use as a console. However, what you can do is
apply a command to the content of the text buffer as if it were a file,
using "SEEBUF" instead of a filename (in fact, this is written
out to a temporary file). For 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. If you have text selected
in the display, see will only use the selected text for SEEBUF. 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. 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. Geometry changes via
"dimensions:" may not take place until you restart see.
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
in nautilus, 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 go to it
(including requests from other applications such as your file browser). 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.
The server uses a local socket which defaults to ~/.seesock but it can be set in
the configuration file. If the server refuses to start for some reason, quit
see and erase this socket file (it should only exist when a server is
running).
There can only be one server running at a time. You can turn the server off by
clicking the flashing indicator on the left side of the interface.
CONFIGURATION¶
See does not require any configuration to work, although without it you may not
be able to use all features. 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. Field names
are case insensitive and lines beginning with a # are ignored. Configuration
can affect the following:
- •
- "text font" eg, "text font: helvetica
12"
- •
- "dimensions" eg, "dimensions: 1200
800". This is the dimensions of the text area in pixels.
- •
- 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.
- •
- "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 (~). You can edit the
seedata file, but be careful to follow the structure there: manpages
require a section number in parentheses. Versions prior to 0.70 did not
require this and you may have to add the section manually if your
bookmarks for a page do not load with version 0.70+. After that there is
an asterisk separated list of line numbers for the bookmarks. The first
number is the number of bookmarks. Then there can be an "R" (for
red) and or "B" (for blue), with more asterisk separated
integers. These are pairs of character positions (begin and end) for
highlights. For example, try inserting this into your seedata file:
seetxt(1)*2*143*263*B*15226*15269*R*15464*15659*
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. Also read the
NOTE ABOUT SYMLINKS IN FILE PATHS under INVOCATION OPTIONS, above.
- •
- "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 (this is a
limitation of local unix sockets). 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. The light blinks at a constant rate unrelated to the watch
time.
- •
- "background:" sets the text area background color
(eg, "background: CornflowerBlue"). The text highlights 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 (eg, #ffffff).
- •
- "tail at:" sets the file size boundary at which
to use "tailing" rather than a complete reload, in bytes. (eg,
"tail at: 5000000"). The default is 1000000. See the NOTE at the
beginning of BOTTOM TOGGLES, above.
- •
- "copy to:" is a directory into which to place
files from a "copy out" operation (see MAIN MENU above). 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:" sets an editor command to use (eg,
"editor: vim ‐‐remote"); see MAIN MENU above for a
more detailed explanation.
Incorrect values in your .seeconfig file may cause a malfunction o_O
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, 2010 Mark Thomas 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).
Visit the seetxt homepage:
http://seetxt.sf.net