Ubuntu Manpage: gentoo - A highly configurable file manager for X

NAME

       gentoo - A highly configurable file manager for X

SYNOPSIS

       gentoo  [--version]  [--locale-info] [--root-ok] [--no-rc] [--no-gtkrc] [--no-dir-history]
       [--left=path] [--right=path] [--run=ARG]

DESCRIPTION

gentoo is a file manager for Linux and compatible systems. It allows you to interactively
navigate your file system using the mouse, and also to perform various fairly standard
operations (such as copy, move, rename, ...) on the files and directories contained
therein.

gentoo always shows you the contents of two directories at once. Each of these is
displayed in its own scrollable list, called a pane. At any time, exactly one pane is the
current pane, and has a highlighted bar running across its top region. The current pane
acts as the source for all file operations, while the other pane is the destination. You
can select rows in panes using selection methods of varying complexity (from simply
clicking a row, to selecting rows by name using a regular expression). Once you have a
selection, you can click a button to perform some command on the selected files.

All file operations performed by gentoo are implemented natively. When you use gentoo to
copy a file, for example, gentoo does not simply execute the system's cp(1L) command.
Rather, gentoo contains its own code for opening source and destination files, and then
reading and writing the right amount of data between them. This way of doing things makes
gentoo independent of the availability of shell commands to do things.

gentoo incorporates a fairly powerful, object-oriented file typing and styling system. It
can use a variety of ways to determine the type of the files it is displaying. Each type
is then linked to something called a style, which controls how rows of that type are
rendered in panes. You can use this system to control icons, colors, and various
operations on the rows. For example, it is easy to make gentoo display all PNG images in
red, and to invoke The GIMP(1) on them when double-clicked.

A design goal with gentoo has been to provide full GUI configurability, removing the need
to edit a configuration file by hand and restart the program to see the changes, as is
otherwise common in many programs for Un*x. As a result of this, gentoo features a
Configuration dialog window where you can configure most aspects of its operation
directly, using the mouse and standard GUI widgets.

gentoo borrows its basic look'n'feel from the classic Amiga file manager Directory OPUS,
but is not a "clone" of any kind.

OPTIONS

gentoo is not primarily driven by command line arguments, but the following are available:

--version
Causes gentoo to print its version number (a string of the form MAJOR.MINOR.MICRO,
like 0.19.13) to the standard output, and then exit successfully. Numbers having an
odd MINOR component indicate development versions of the program. So far, all
versions of gentoo have been classified as being development versions.

--locale-info
Makes gentoo print a couple of localization settings, and then exit. This is
mostly useful during development and debugging, and not of a lot of interest when
just using the application.

--root-ok
Makes gentoo accept being run by the root user. Normally, this is not allowed since
it is considered a big threat to system security. Note that gentoo has the ability
to execute user-defined strings using the execvp(3) function. This is generally
considered harmful. However, if you really want to run gentoo while logged on as
root, supplying this option allows you to. It is not recommended, though.

--no-rc
Starts up gentoo without loading any configuration file. This makes it run using
the built-in defaults, which are very Spartan indeed. Seldom comfortable, but
occasionally handy when trying to determine if a problem is with the configuration
or with the core code.

--no-gtkrc
Avoids loading the GTK+ RC file, thus disabling any widget customizations, and
forces all widgets to use the default GTK+ look.

--no-dir-history
Avoids loading the file that holds the history, i.e. which directories have been
previously visited by the two panes. Very rarely needed, included mostly for
completeness' sake.

--left, --right (or -1, -2)
Sets the initial path for the left and right pane, respectively. If present, the
path specified with one of these options overrides any other path for the pane in
question. See below (Initial Directory Paths) for details.

--run ARG (or -rARG)
Runs ARG, a gentoo command. Commands specified this way are executed before gentoo
accepts any user input through the graphical interface, but after the configuration
file has been read in. You can use it many times in order to make gentoo run a
whole series of commands. Remember that gentoo's command names are case-sensitive,
and that built-in commands (like "About") always begin with a capital letter.

Any non-option command arguments will be silently ignored. If an argument "-h" or "--help"
is given, gentoo will give a summary of its supported command line options and exit
successfully. If an unknown option is given, or a option is missing a required argument,
gentoo will whine and exit with a failure.

BASIC USAGE

When gentoo starts up, it will open up its single main window, which is split vertically
(or horizontally; it's configurable) down the middle, forming the two panes mentioned
above. It also contains a bank of buttons along the bottom.

Initial Directory Paths
The actual paths shown in the two panes upon start-up can be controlled in various ways.
There are four ways of getting a path to show up in pane. In order of decreasing priority,
they are:

1. Command-line Argument
Using the --left and --right (or their short forms, -1 and -2) command-line
arguments overrides any other setting.

2. Configured Default Directory
If no command-line argument is present, and the "Default Directory" configuration
option is set, that directory is used.

3. Most Recently Visited Directory
If no default directory exists, the most recently visited directory is taken from
the directory history for each pane. This only works if a directory history file
has been found and loaded.

4. Current Directory
If all else fails, gentoo uses the current directory (".").

Navigating
Navigating around the file system using gentoo is very simple. The two panes act as
independent views of the file system, and both are navigated in exactly the same way.

You can always see which directory a pane is showing by reading its path, shown in the
entry box below (by default--you can change the position to above) the pane.

To enter a directory, locate it in the pane and double click it with the left mouse
button. gentoo will read the directory's contents, and update the display accordingly.

There are several ways of going up in the directory structure. To enter the directory
containing the one currently shown (the current dir's parent), you can: click the parent
button (to the left of the path entry box); hit Backspace on your keyboard; click the
middle mouse button; select "Parent" from the pop-up menu on the right mouse button, or
click the downward arrow to the right of the path box (this pops up the directory history
menu), then select the second row from the top.

Selecting Files
Before you can do anything to a file, you need to select it. All file-management commands
in gentoo act upon the current selection (in the current pane). There are several ways of
selecting files, but the most frequently used are mouse-based. Note that the word "file"
used below really should be taken to mean "file or directory", since selection doesn't
distinguish between the two.

To select a file (or directory), just point the mouse at the name (anywhere in the row is
fine), and click the left mouse button. The colors of the clicked row will change,
indicating that it is currently selected. To select more rows, keep the mouse button down,
and drag the mouse vertically. gentoo extends the selection, including all rows touched.
If you drag across the top or bottom border, the pane will scroll, trying to keep up.
This is a very quick and convenient way of selecting multiple files, as long as they are
listed in succession.

If you click again on an already selected file, you will unselect it. You can drag to
unselect several files, just as when selecting.

To select a sequence of files without dragging, first click normally on the first file
that you wish to select. Then release the mouse button, locate the last file in the
sequence (it can be either above or below the first one), hold down shift on your
keyboard, and click the wanted file. gentoo now adds all files between the first and the
last to the current selection.

If you follow the instructions given above to select a sequence, but press control rather
than shift before clicking the second time, gentoo will unselect the range of files
indicated.

If you click on a file with the meta key held down (that's actually a key labeled Alt,
located to the immediate left of the space bar, on my PC keyboard), gentoo will do
something cool: it will select (or unselect, it's a toggle just like ordinary selection)
all files, including the clicked one, that have the same type as the one you clicked. This
can be used to select for example all PNG image files in a directory even if you can only
see one. Occasionally very useful.

If you click on a file with both the shift and control keys held down, gentoo will toggle
the selected state of all files having the same file name extension as the one you
clicked. This can sometimes be useful to select files that you don't have a proper type
defined for, as long as those files do share an extension, that is.

Changing Sort Order
The files and directories listed in each of gentoo's two panes are always sorted on some
column: typically file name. You can chose to sort on some other field by clicking the
appropriate column title once. If you click on the field that is already current, the
sorting will be reversed (i.e., for names it will be Z-A rather than A-Z).

If your display includes icons, try sorting on that column: gentoo will then order each
row according to its File Style, grouping the rows based on their parent styles, all the
way up to the root of the Style tree. This means that, for example, JPEG and PNG pictures
(both having an immediate parent style of Image) will be shown together, and before all
Text files (HTML, man pages and so on). It's quite cool, really. :)

Executing Commands
Commands are used to make gentoo do stuff. The typical command operates upon the set of
selected files in the current pane, so it's usually a good idea to first select some
files. See the previous subsection for details on how to select files. Once you have a
bunch of files selected, you need to tell gentoo which command to execute. There are
several ways of doing this.

Most basic file operations (e.g. copy, move, rename, and so on) are found on the (cleverly
labeled) buttons along the bottom of gentoo's main window. To copy a file, just select it,
then click the button labeled "Copy". It's really that simple. Most of these built-in (or
native) commands automatically operate recursively on directories, so you could copy (or
move) a whole directory of files by just selecting it and then clicking "Copy".

If you can't see a button that does what you want to do, there's a chance that the command
exists, but isn't bound. Click the right mouse button in a pane, this opens up the "pane
pop-up menu". Select the "Run..." item. This opens up a dialog window showing all
available commands. Select a command, and click "OK" to execute it.

CONFIGURATION

       gentoo is a pretty complicated program; it has a rather large amount of configuration data
       that it needs in order to be really useful. For example, my current personal configuration
       file contains well over a thousand different configuration values.

       To store this hefty amount  of  configuration  data,  gentoo  uses  a  heavily  structured
       configuration file. In fact, the file is (or at least it should be) legal XML!

       When  new  features  are  added  to  gentoo,  they  will  typically  require  some form of
       configuration data. This data is then simply added somewhere in the existing configuration
       file  structure.  Effort is made to assign reasonable built-in default values for all such
       new features, so older configuration files (that don't contain the values required by  the
       new features) should still work. The first time you hit "Save" in the configuration window
       after changing your version of gentoo, your personal configuration file will be updated to
       match the version of gentoo.

       Describing  how  to  go  about  configuring gentoo is too big a topic for a manual page to
       cover. I'll just say that the command to  open  up  the  configuration  window  is  called
       "Configure".  It is by default available on a button (typically the top-right one), in the
       pane pop-up menu, and also by pressing the C key on your keyboard.

FILES

~/config/gentoo/gentoorc
A user's personal configuration file. When gentoo starts up, it will try to load
this file. If the file isn't found, the old name ~/.gentoorc is tested, and if that
also fails a site-wide configuration (see below) will be tried instead.

/etc/gentoorc
This is the site-wide configuration file. If a user doesn't have a configuration in
his/her home directory, gentoo loads this file instead. The actual location of this
file is slightly system-dependent, the above is the default. As an end user, you
typically won't need to access this file manually.

~/config/gentoo/dirhistory
This file contains lists of the most recently visited directories, for both panes.
These are the lists that appear in the drop-down menu when the arrow next to the
path entry box is clicked. Can be disabled in the Dir Pane configuration.

~/config/gentoo/gtkrc
This file allows you to control the look of the widgets used by gentoo, through the
GTK+ style system. You can change the actual path in gentoo's Configuration window,
the above is the typical default for a modern Linux-based system. If a file named
gtkrc is not found in the configured path, the names gentoogtkrc and .gentoogtkrc
(note the period), in that order, are also tested.

/etc/passwd, /etc/group
These two files normally hold the system's password and group information. These
are (probably) the ones gentoo uses to map user IDs to login names, to do tilde-
expansion (mapping of user name to directory path), and to map group IDs to group
names. That is probably, because gentoo doesn't actually refer to these files by
name. Instead, it uses the (BSD-style) API function calls getpwent(3) and
getgrent(3) to access this information.

/etc/fstab, /proc/mounts, (or /etc/mtab)
These files contain data on available and mounted file systems. They are read by
gentoo's auto-mounting code. You can configure the exact file names used, on the
"Mounting" tab in the main configuration window. Note that using /proc/mounts
rather than /etc/mtab is recommended on Linux systems; they contain roughly the
same data, but the one in /proc is always up to date, and faster to read!

BUGS

All releases of gentoo numbered 0.x.y, where x (the so called minor version number) is
odd, are to be considered development releases, as opposed to stable ones. This means that
the software will probably suffer from bugs. If you find something that you suspect is
indeed a bug, please don't hesitate to contact the author! For details on how to do this,
see below.

If you're concerned about using potentially buggy and completely unwarranted software to
manage your precious files, please feel free not to use gentoo. The world is full of
alternatives.

The chances that a bug gets fixed increase greatly if you report it. When reporting a bug,
you must describe how to reproduce it, and also try to be as detailed and precise as
possible in your description of the actual bug. If possible, perhaps you should include
the output of gdb(1) (or whatever your system's debugger is called). In some cases it
might be helpful if you include the configuration file you were using when the problem
occurred. Before reporting a bug, please make sure that you are running a reasonably
recent version of the software, since otherwise "your" bug might already been fixed. See
below for how to obtain new releases.

Also, you should locate and read through the BUGS file distributed with gentoo, so you
don't go through all this hassle just to report an already known bug, thereby wasting
everybody's time...

AUTHOR

       gentoo was written, from scratch, by Emil Brink. The first line of code was written on May
       15th, 1998. It is my first program to use the GTK+ GUI toolkit, my  first  program  to  be
       released  under  the GPL, and also my first really major Linux application. However, it is
       not my first program! ;^) I've been writing (increasingly complex)  code  for  almost  two
       decades  now. I have recently finished my Master of Science degree in Computer Science and
       Engineering at the Royal Institute of Technology in Stockholm, Sweden.

       The  only  efficient  way  to  contact  me  (to  report   bugs,   give   praise,   suggest
       features/fixes/extensions/whatever)    is    by    Internet    e-mail.   My   address   is
       <emil@obsession.se>.  Please try and include the word "gentoo" in the Subject part of your
       e-mail, to help me organize my inbox. Thanks.

ACKNOWLEDGMENTS

       The author wishes to thank the following people for their various contributions to gentoo:

       Johan Hanson (<johan@tiq.com>)
              Johan  is  the  man  behind all icon graphics in gentoo, and also the author of the
              custom widgets used in it. He also comes up with plenty of ideas for  new  features
              and  changes  to  old  ones, some of which are even implemented. Johan has stuff at
              <http://www.bahnhof.se/~misagon/>.

       Jonas Minnberg (<sasq@nightmode.org>)
              Jonas did intensive testing of early versions of gentoo, and  eventually  persuaded
              me into releasing it (back around version 0.9.7 or so).

       Ulf Petterson (<ulf@obsession.se>)
              Ulf  drew  the  main  gentoo  logo  (the  one  shown in the About window), and also
              designed the main HTML documentation's layout.

       Josip Rodin (<jrodin@jagor.srce.hr>)
              Maintainer of the gentoo package for Debian Linux, and also a source of suggestions
              for improvements, as well as a relay for bug reports from Debian Linux users.

       Ryan Weaver (<ryanw@infohwy.com>)
              Maintainer  of  the  gentoo  packages  for  Red  Hat Linux, and probably one of the
              fastest package creators out there. :)

       Oliver Braun, Jim Geovedi and Pehr Johansson
              Maintainers of gentoo ports to FreeBSD, OpenBSD, and NetBSD, respectively.

       Thanks also to all people who have mailed me about gentoo, providing bug reports,  feature
       requests, and the occasional kind word. :^) It's because of people like yourselves that we
       have this wonderful computer platform to play with.

COPYRIGHT

       gentoo is released as free, open-source software, under  the  terms  of  the  GNU  General
       Public  License  (GNU  GPL), version 2. This license is included in the distribution under
       the traditional name of COPYING, and I suggest that you read it  if  you're  not  familiar
       with  it.  If  you can't find the file, but have Internet access, you could take a look at
       <http://www.gnu.org/>.  It is important to realize that the mentioned license  means  that
       there is ABSOLUTELY NO WARRANTY for this software.

OTHER INFO

       Some  unfinished,  outdated,  but  still pretty informative documentation is available, in
       HTML format, in the docs/  subdirectory  in  the  distribution  archive.  If  you  haven't
       installed  gentoo from the original .tar.gz distribution archive, you might need to either
       inspect the distribution you did use (perhaps it came  as  some  form  of  "package"),  or
       contact a system administrator.

       The  GTK+  GUI toolkit that gentoo requires is available at <http://www.gtk.org/>.  gentoo
       uses the slightly outdated stable series, called 1.2.x. The latest known release  in  that
       series is GTK+ 1.2.10. Because of severe performance problems, gentoo will probably not be
       ported to use the current (2.0.x) series of GTK+ any time soon.

       The latest version of gentoo is always available on the  official  gentoo  home  page,  at
       <http://www.obsession.se/gentoo/>.