seeman - Online in the Cloud

PROGRAM:

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

Use seeman online using onworks.net services