|
|
| LICENSE | NOTES | GUIDE | INTRO | USAGE | CONFIG | HISTORY | CONTRIBUTING | ACKS |
This section covers gentoo's considerable configuration options. All configuration is done in the same window, which is (rather ingeniously) called the configuration window. The configuration window consists of a number of pages. Below, all links except for the first two take you to the documentation for one such page.
Note! |
This early release of gentoo doesn't have the configuration system fully documented. Very much has been implemented, though; each of the nonactive links below refers to a configuration "page" that is fully implemented in the program today. I believe gentoo to be truly useful, if you can figure out how to do it... There will be upcoming releases with more documentation and, generally, more of everything else too. Hold on. |
| 1. The Configuration Window | More on the base configuration window, its stock buttons etc. | ||
| 2. The Configuration File | Talks about the location and format of the gentoo config data file. | ||
| 3. File Styles | Describes the file style configuration page. | ||
| 4. File Types | Talks about the file type page. | ||
| 5. Directory Panes | Tells you how to configure the contents of the directory panes, sorting, etc. | ||
| 6. User Commands | Describes how you set up your own commands. | ||
| 7. Buttons | Talks about the buttons page, where you can add/change/remove buttons from the button bank. | ||
| 8. Shortcuts | Information about how to set up your own shortcut buttons. | ||
| 9. Paths | Gives information about the program-wide paths settings. |
|
|
| LICENSE | NOTES | GUIDE | INTRO | USAGE | CONFIG | HISTORY | CONTRIBUTING | ACKS |
The directory panes are possibly the most important single GUI elements in gentoo. It's in the directory panes that disk contents are shown; it's where you select and operate upon items; it's where all your glorious styles get to show off their groovy colors and fancy icons. To put it short, the panes is where it all happens. So, what can you do about what is being displayed in these panes? As it turns out, you can do quite a lot. Read on!
To conserve some vertical space, the screenshot has been suppressed. It's all here though, if you really want to see it. It might be good to take a look (or, better, peek at a running gentoo's config window) before reading the rest of this page.
At the top of the dirpane config page, there's a row with some general control buttons making life easier. The single most important one is the option menu button to the left; it controls which pane you're editing. There are two panes, one called "Left" and one "Right" - each has its own set of completely independent settings.
Besides the pane option menu, there are a couple of buttons that let you swap the configurations around and copy one to the other (and "the other to the one", sort of :). You don't need to use these often, but when you do, you typically really need them!
The major part of the dirpane config page is taken up by the a big frame labeled "Columns". This is where you control what gets shown in the panes, and where.
The basic "unit" of pane output is the column. Each pane must have at least one column of content, but typically there's much more. You control what gets displayed by assigning content to the columns. You can do this assigning any way you please; there's nothing stopping you from letting a pane contain six columns of file names, then a column showing the name of the files' owners, and then another six columns of file names. Of course, such a display would probably look very silly and be next to useless, but you can do it!
The number of columns in a pane can currently not exceed 32. This is a fairly arbitrary
compile-time limitation, which only exists to make my life easier, and the program faster
and less error-prone. If you really think that this sucks, you're very welcome to
fix it yourself! ;^)
The columns frame consists of two lists arranged side by side. The one on the left, cleverly labeled "Available Column Content" contains just that. It lists the types of column content that gentoo supports. If it's not in that list, you can't have it. Examples of content types include file name, size (in bytes and blocks), file owner and group, modification dates, and so on.
The list on the right, with the bunch of buttons underneath it, shows the currently selected content types for the current pane. Each row in this list corresponds exactly to one column in the pane. The order of the rows is the order of the columns. Each row shows two fields; a title and a content name. The title is the text that gets shown in the column button in the pane. The content controls what gets shown in the column.
To add a new column to the current pane, locate the content type you want in the list on the left, and double click it. A new row is added to the list on the right.
There are some parameters that you might want to adjust for each column; things such as column width, adjustment (left, right, or center) and title text. Some content types even provide additional content-specific options for you to play with. To access all these fun things, select a column in the list on the right, and click the "Edit..." button below the list. This opens up the column edit window. The window is split in two parts; the top part contains the basic settings that all columns have (title, adjustment, and width), while the bottom part contains any content-specific options. If there are no special options available for the column's content, the bottom frame is not shown. For a run-down on all the various content types and their special options, read here. When done, click "OK" in the window to accept, or "Cancel" to abandon any changes you made.
|
|
| LICENSE | NOTES | GUIDE | INTRO | USAGE | CONFIG | HISTORY | CONTRIBUTING | ACKS |
This section of the manual describes some general features about gentoo's configuration window.
When you wish to make changes to gentoo's configuration, you need to somehow execute the built-in command Configure. When this command is run, the configuration window is opened. With the default (built-in) configuration of gentoo, you can execute this command by either clicking the button labeled "Configure" in the top right corner of the button bank, or by selecting the menu item of the same name in the pop-up menu reached by right-clicking in a dir pane.
The configuration window has a very simple layout. It consists mainly of two parts: a big working area, which only contains a so called "notebook widget", and a strip of buttons along the bottom of the window. Here's a screenshot:
The notebook widget is a container; it holds other widgets. It divides its contents into pages, and always displays exactly one page at any particular moment. The things at the top (labeled "File Styles", "File Types" and so on) are known as tabs. Each page has a tab: click on a page's tab to cause it to be displayed.
Most configuration pages share some common features, to make them easier to use. A typical configuration page contains quite a lot of different widgets; it is easy to get confused about which widget to use (and when). In an attempt at reducing this confusion, most configuration pages make all widgets that are not immediately useful insensitive to user manipulation. Insensitive widgets are drawn in a distinct way, making them easy to spot. They also don't react to having the mouse pointer over them, like most other GTK+ widgets do. In the screenshot above, all widgets but two are insensitive.
The "Add" and "Delete" buttons that appear near the bottom of the page in the picture are very common in config pages. Not all pages use these two buttons, but those that do always place them in the exact same position, thus making them easy to spot.
The three buttons along the bottom ("OK", "Save" and "Cancel") are not part of the current page, but are always visible. All three close down the configuration window, with various side effects:
$HOME/~.gentoorc. For more information about the configuration file format,
read here. |
|
| LICENSE | NOTES | GUIDE | INTRO | USAGE | CONFIG | HISTORY | CONTRIBUTING | ACKS |
You use file styles to control the way files of different types are displayed and generally dealt with. For more information about styles and their various properties, the tree structure applied to styles, and all other fun details, check out the styles chapter!
Configuring styles is important in order to get gentoo to look the way you want it to, and also to act the way you want it to.
Here's two (cropped) pictures how what the file styles configuration page looks like. The picture to the left shows the page as it looks when no style has been selected, while the right hand picture shows it with a style ("Root") selected.
The dominant part of the style page is taken up by a single widget; a display of the style tree. The tree widget is hopefully more or less selfexplanatory; it shows the different styles and the parent-child relationships between them. You can click on the (tiny) boxes to the left of an item to show or hide its children. The default is to expand the tree fully, showing all styles.
The styles are listed in alphabetical order on each tree level, to make finding a certain style a little easier.
Right below the tree view, there's a text entry widget labeled "Name". Not surprisingly (I hope), that's where you enter the name of the style. The name of a style must always be unique, since the name is used to link styles to types. When you edit the style name, gentoo will ignore any changes that make the name a duplicate, keeping the last unique name. This might seem confusing, but chances are you'll never even notice it.
Under the name entry widget, there's another text entry widget, this time labeled "Parent". Unlike the name, you can't edit the parent name directly; the widget is used just to display the name. To change the parent of a style, click the tiny button labeled with the ellipsis. This will open up a dialog window where you can choose a new parent style. None of the current style's children will be in the dialog, of course. Once you change the parent, the tree display changes to reflect the new hierarchy.
The rest of the page is taken up by a big frame labeled "Preperties". It gives you a chance to edit and view the style's properties. Properties are inherited from parent to child, so when editing a style high up in the hierarchy, the changes might be visible far down. You can always click on a style to see its current property values.
Each property has a check button; if the button is active (I would say "checked", but GTK+ doesn't render check buttons with check marks in them), that means that the property in question is being overridden by the current style; i.e. the parent's value is not being used. When a property is overridden, the style provides its own value for the property. When you deactivate an override check button, the style reverts to using its parent's value for the property in question.
In the right picture above, you can see that all the check buttons are indeed active, but also that they are "insensitive"; you can't manipulate them. This is simply because the style selected is the root style; it must always override all properties, since it has no parent to inherit values from.
There are 6 different visual properties, divided into two groups: unselected and selected. Since the meaning and use of these has been covered in the styles chapter, I won't repeat that here. I'll just tell you what you can do when configuring a style's visual properties.
The list containing the rows "Unselected" and "Selected" is the style preview. It shows how the current visual property values would look in a pane. The preview is not interactive.
Below the preview are two sets of property editing frames; one for the unselected state and one for the selected. Each frame contains widgets to control override and value of the three state-specific properties (background and foreground colors, and icon).
To set a color property, first make sure its override button is active. When active, the "Edit..." button becomes available. Clicking it opens up the GTK+ standard color selection window. Manipulate the widgetry in this window until you find a color you like, and accept the changes by clicking the "OK" button. While manipulating, watch the preview as it updates to show an accurate preview.
To set an icon property, click the "Pick..." button (after making sure that the style being edited actually does override the property in question, of course). This brings up (after a small delay during which you get to view a nice progress indicator) an icon selection window. Select an icon and click OK, and the style is modified. It's as simple as that. Currently, there's no "active preview" while choosing icons, but you really shouldn't need one IMO.
Between the unselected and selected property frames is a narrow frame labaled "Copy>>". It contains some buttons that can be used to perform often-wanted operations a bit faster. The buttons are:
Again, the concept of action properties has been explained in the styles chapter, here we'll concentrate on how you go about setting them to values you like. The first thing you need to do is access the action properties notebook page; you do this by clicking the tab labeled "Action". The display then changes to look something like this.
The action property notebook page contains one row for each available action property. To
the left is a check button which you use to control override, as usual. Next on the row comes
a simple "preview" of the action command sequence; it'st just a list of commands. Not very
useful, but I wanted to put something there, to fill out the window a bit. ;^)
The last thing on the row is an "Edit" button, which when pressed brings up the standard
command sequence editor.
That's basically it.
Of course, style editing wouldn't be so interesting if you only had the two styles shown in the screenshots here to work upon. Of course, you want to add your own styles, and experiment.
To add a new style to the tree, click the "Add" button (surprise!). If no style was selected when you clicked, the new style will be added with "Root" as its parent. If a style was selected, it will be used as the parent. The new style appears in the tree under the temporary name "(New Style") or something similar; make sure you change this to your wanted, unique, name as soon as possible.
To delete a style, select it in the tree, then hit the "Delete" button. If the style selected is a parent, a dialog box will appear requesting you to confirm that you really want to delete it, since deleting a parent style deletes all the children too! Beware. Of course, you cannot delete the Root style.
gentoo-0.19.13/docs/config/gentoorc.html 0000644 0001750 0001750 00000016201 11547706437 020213 0 ustar demarchi demarchi |
|
| LICENSE | NOTES | GUIDE | INTRO | USAGE | CONFIG | HISTORY | CONTRIBUTING | ACKS |
Like most applications, gentoo needs somewhere to store its settings when it is not running, so you don't need to reconfigure it every time. The natural choice is, of course, to store the settings in a file in the file system, and this is exactly what gentoo does. This page describes the location and format of this configuration file. Unless you're a system administrator, there should be no need to read this. Unless you have a special interest in config files, that is...
In keeping with good old Un*x tradition, gentoo calls its configuration file ".gentoorc".
Starting the name with a period hides it from (most) shell file listings, which is convenient.
Ending the name with "rc" identifies it (to Un*x people, anyway) as being a configuration file,
which is also very convenient.
When gentoo starts up, it tries to load a configuration from the file "$HOME/.gentoorc".
That is, it looks in the home directory of the user who started it. If the HOME environment
variable isn't set, or if there is no config file to be found, gentoo checks for a file
in "/usr/local/etc/.gentoorc". It is convenient to place a site-wide standard configuration
there, since it will be loaded the first time a "new" users runs gentoo. If none of these files
can be found, gentoo complains and then uses a minimal built-in configuration.
The configuration file is always written to the user's home directory - there is no way of specifying
a different file name. If you're installing gentoo for use by several users, just copy your
configuration file from your home directory to /usr/local/etc/, so it can be used as the
default for users.
Again, like most other Un*x programs, gentoo uses a plain-text configuration file. Unlike some other programs though, the file format used is highly structural: it's (almost) XML! Actually, since the code that loads the file definitely doesn't qualify as being a full-blown XML loader, the file isn't really XML either. But is sure looks like it... Basically, the file uses tags plus a case-convention to define a tree of values for all configuration options.
You are not encouraged to edit around in this file by hand; let gentoo be the only entity reading and writing it! The loader code is fairly armored, but still far from bullet-proof, so don't provoke it by hacking the file.
gentoo-0.19.13/docs/config/cfg_types.html 0000644 0001750 0001750 00000025265 11547706437 020370 0 ustar demarchi demarchi |
|
| LICENSE | NOTES | GUIDE | INTRO | USAGE | CONFIG | HISTORY | CONTRIBUTING | ACKS |
File types are used to identify the files on your disks, and classify them into different types. Before you read about how to set up your own types, I really recommend that you check out the usage section on file types, so you know what a type is, how they work et cetera.
Here's a couple of screenshots of the configuration for file types, cropped as usual. The one on the left shows the page when no type is selected, the one on the right with a type selected:
Dominating the page is a big list of all currently defined file types. They are listed in alphabetical order, to make finding a given type simpler. Also, if you name your types in the way suggested in the types chapter, the sorting helps keep related types together. Since there's no complex structure imposed on file types (as there is with file styles), this can really help keep things organized.
Below the list is a text entry widget labeled "Name". Not surprisingly (I hope!), this is where you give the name of the selected type. Type names need not be unique, so you can just about enter anything you like.
Below the name field, there's a large frame labeled "Identification". This is where you control how the type attempts to identify files. There are five levels of identification available: intrinsic type, protection, suffix, name RE, and 'file' RE. Read all about it in the types chapter, as usual. Of these methods, all but the first are optional; you don't need to specify them. You can select any combination of the four latter; to include a rule, just click its check button and fill in any parameters required by the rule. Details on the parameters available:
Defining the intrinsic type to require is pretty simple; just click one of the radio buttons. Note that each type must require exactly one intrinsic type. "Link" stands for soft (a.k.a. "symbolic") link, "B-Dev" and "C-Dev" are abbreviations for block and character device, respectively.
To use protection matching, first activate the rule by clicking its check button. Then operate the six toggle buttons on the right until the combination you want is shown. Remember that if you select a protection flag (such as "Sticky"), you are requiring files to have the Sticky bit set. There is no way of specifying negative protection requirements.
If you wish to require files of this type to have a common suffix in their names, activate
this rule and type the suffix in the text entry box. Remember that gentoo doesn't
have a very complex notion of what a suffix is; it's just the last part of a name. Often,
a dot (.) is used to separate a type-indicating suffix from the rest of the
name. Since gentoo doesn't know about this, you simply need to include that dot in
the suffix specification. For example, enter .gif to find GIF images.
If a simple suffix isn't enough to identify the files you're after (Amiga tracker modules,
anyone?), chances are this rule will do the job. It allows you to specify a full regular
expression, and then attempts to match that against file names. This is incredibly powerful,
since it can be used to find (quite) arbitrary names. The most typical use is pretty
mundane, though; RE matching is very handy when you need more than one suffix. A classic
example is .+\.jpe?g, which matches against file names that end in a dot
followed by jpeg or jpg. For more information about regular
expressions and what they can do, read on.
If you don't need quite the power of regular expressions, you can use patterns of the same type as used in many shells. These patterns are (for reasons unknown to me) called glob patterns. If you want gentoo to treat your RE as a glob pattern, click the check button labeled "Glob?" to the right of the input field. For the details on how the glob->RE translation is done, read here.
The last kind of rule is the most powerful. This envokes the external command 'file' on
files, and allows you to specify a regular expression which when checked against the
output of 'file' must produce a match. As with the name matching, you can specify that
the expression you entered is actually a glob pattern by activating the button next
to the input field. For more information about 'file', see the
file types chapter, and these manual pages: file(1) and magic(4)
on your system.
Once you have the type's identification rules nailed down, it's time to specify how you want matching files to be treated (displayed, viewed, etc). You do this by linking the type to a style. Hopefully you have already defined the style you want, otherwise it's a good idea to do that now. When you know that the style you want for this type exists, click the big button in the "Type's Style" frame. This brings up a simple dialog where you can select the style you want. The name of the selected style is shown in the button. If no particular style has been selected, it says "Root".
To add a new type, click the "Add" button. This creates a new, empty type, and makes it the current one. The first thing you should do after creating a new type is to rename it; therefore the name entry box is focused automatically.
To delete a type, select it and then click the "Delete" button. The type is immediately killed, no questions asked. You cannot delete the "Unknown" type.
gentoo-0.19.13/docs/config/template.html 0000644 0001750 0001750 00000010677 11547706437 020221 0 ustar demarchi demarchi |
|
| LICENSE | NOTES | GUIDE | INTRO | USAGE | CONFIG | HISTORY | CONTRIBUTING | ACKS |
gentoo-0.19.13/docs/scratch/filestyles.txt 0000644 0001750 0001750 00000021303 11547706437 020612 0 ustar demarchi demarchi 1999-05-31 Emil Brink gentoo File Styles 1. INTRODUCTION This file documents the file style subsystem in gentoo. A good understanding of file styles is important in order to maximize your comfort in gentoo. 2. NEW vs. OLD STYLE SYSTEM If you've never used gentoo prior to version 0.11.7, you can skip this section entierly, since it deals with changes to the style system that occured with the mentioned release. As of 0.11.7, file style properties are fully dynamic. This means that there are no "built-in" properties of any kind, neither visual nor action. Prior versions of gentoo featured a set of built-in properties (they were Default, View, Edit, Print and Play). There was a need to support user-defined actions, but I couldn't find a clean way of extending the old code to support that. So I tore it all away, designed a style system with fully dynamic properties, and implemented that instead. The style system in gentoo 0.11.7 is the result. If you want a particular property to be available, just add it at a suitable point in the style tree. It will be propagated by inheritance to all styles below the one where you added it. If you want to change the value of an inherited property at some point in the tree, just override it. The new value will propagate downwards. Older versions of gentoo featured a command for each built- in property (the FileDefault, FileView, ... commands). Since I don't want to dynamically add commands as properties are created, these commands have been replaced by the single FileAction command. If called with no parameters, this command will run the Default action property. If called with an "action=X" argument, it will run the property called X. 3. WHAT IS A STYLE? A style is an abstract object. Its main purpose is to serve as a container for a set of related "properties", and to provide an inheritance hierarchy for these properties. Styles are tightly coupled to the concept of "types"; each type is always connected to exactly one style. Styles are arranged in a tree. The tree has a single root style (commonly called "Root", although you can rename it if you want to) and as many child styles as you need. The tree can have any depth; you can add child styles to child styles to build the hierarchy up recursively. 4. WHAT IS A PROPERTY? Properties are what make styles useful. A property is a named value of a certain type. Currently, three different types of properties are supported by gentoo: colors, icons and actions. The two former are usually refered to as "visual" properties. The point of properties is to contain the information gentoo needs to display and handle dirpane rows of various types in a use- ful and correct way. 4.1 Property Inheritance The properties are inherited downwards in the tree, from the first style that define them, down to all its children. This means that if the root style defines a property called "A", all child styles (i.e., all other styles) will also have a property called "A" with the value defined by the root. At any style, you can override the inherited value of a property, thus causing the new value to propagate instead of the old. Using inheritance saves work, and makes maintaining the styles much easier and less error-prone. Basically, it is a good thing. :) 4.2 Visual Properties Visual properties control how gentoo renders the rows of a pane. There are three visual properties in use: background and foreground colors, and icon. The two former control the colors used for row background and text (foreground), when the row has not been sel- ected by the user. As soon as a row is selected, it reverts to using GTK+'s standard selection colors. The icon property contains the name of the icon graphics to use for the style. 4.3 Action Properties Action properties specify commands that can operate on files of a given type. You then use the FileAction command to envoke these commands by property name. All styles should have a default action property (typically called "Default"), inherited from the root. The "Default" action is what is executed when you double click on a row in a pane. For many styles, it makes sense to make the default action cause the files contents to be viewed, by setting the property to "FileAction action=View" and defining a suitable View action. 5. CONFIGURING STYLES To modify the current style tree, open up gentoo's configuration window (execute the builtin command Configure). Then click the tab labelled "File Styles". It might be helpful to have the window open and visible while reading this, since there will be many references to various things in the window. The style config page can be divided vertically into four areas of interest. At the top is the style tree itself. It shows, using a nice tree widget, the current style tree. At the top of the tree is the root style, and below it are all its children. The connections bet- ween styles are shown with lines. 5.1 Name and Parent Below the style tree are two text entry fields, labelled Name and Parent, respectively. The Name entry field shows the name of the currently selected style, and lets you type directly to rename the style. The Parent text field is not editable. When a style is selected, it shows the name of the style's immediate parent. You can click the button to the right of the field (with the magnifying glass) to pop up a dialog that lets you select a new parent for the style. If the current style has any child styles of its own, the entire branch will be moved if you change the parent. 5.2 Properties Underneath the name & parent fields is a frame titled "Inherited Properties". It contains a notebook with two pages: one for visual properties, and one for the actions. 5.2.1 Visual Properties The visual property page contains a little preview, showing you how the colors and icon look together. It also holds three frames, one for each of the three standard visual properties (background color, foreground color, and icon). To set a visual property, make sure the "Override Parent's?" check button is checked (depressed). Then click the button below the check button, the one with the "Edit..." or "Pick..." label. This will pop up a dialog where you can make the desired changes. To revert back to the parent's value for a given property, simply uncheck the override check button. 5.2.2 Action Properties The action property page contains a list of all action properties the current style has. Note that not all of these are actually set in the style itself: the list shows inherited properties as well. To modify an action property's value (its command), just select it in the list and type the new value in the entry box labelled "Command". Clicking the magnifying-glass button to the right of the entry field pops up a dialog where you can choose from the currently defined commands. Changing the command of an action property automatically overrides the property, i.e. the new value will be propagated to any child styles, and the inherited one will be ignored from this style on. Note that even if you change it back to the same value as the parent has, it will remain overridden. You can add a new action property by clicking on the button labelled "Add Action...". This will pop up a dialog asking you for the name of the action to add. I suggest using a single word, with an uppercase initial (like "Default", "View", "Edit", and so on). Initially, the property will not have a useful value assigned to it. Select it in the list, and follow the instructions given above to set the value you want. Removing a property you added is simple: just select it, and then click the button labeled "Delete Action" (it's to the right of the "Add Action..." button). This will immediately remove the action from the current style and all its children. If the delete-button reads "Revert to Inherited Command" rather than "Delete Action", the selected action is an overridden inherited one. You cannot remove inherited properties, but you can make them assume the inherited value rather than the one set locally in the current style, by clicking this button. If the button is ghosted (drawn greyed out), the property is a normal inherited one, and can be neither removed nor reverted. This is the normal state, and probably the one you'll see the most often. 5.3 Adding and Deleting Styles To add a new style, first select the style you wish to have as parent for the new one. Then click the "Add" button in the bottom of the page. This will add a new style as a child to the previously selected one. To delete a style, select it and click the "Delete" button in the bottom-right corner of the page. If the selected style has any children, deleting it will also remove the children. This might be very inconvenient if done to the wrong style, so there will be a confirmation dialog if the style has children. gentoo-0.19.13/docs/scratch/README 0000644 0001750 0001750 00000000200 11547706437 016537 0 ustar demarchi demarchi These files contain various pieces of information about gentoo. The technical level might be very high in some of these. /Emil gentoo-0.19.13/docs/scratch/dirhistory.txt 0000644 0001750 0001750 00000014071 11547706437 020633 0 ustar demarchi demarchi 1999-06-08 Emil Brink Directory History 1. INTRODUCTION This little document talks about the "directory history" mechanisms in gentoo. These mechanisms are responsible for keeping track of which rows were selected in a certain directory the last time you visited it in a given pane, the vertical position last used, and such. This document was written during development of gentoo 0.11.8, since that version (hopefully) includes a reworked directory history system. 2. PROBLEMS WITH PRE-0.11.8's HISTORY HANDLING The history code included in releases prior to 0.11.8 has several problems. Perhaps the most severe is that it always keeps the list of paths you have visited sorted in reverse chronological order, leaving the most recent path on top. This is fine for simple inter- action, but makes it difficult to step backwards through the history (since each step causes it to re-sort). As of version 0.11.7, symbolic links are fairly well supp- orted by gentoo, and it becomes necessary to have some way of following links "backwards". The old directory history system doesn't do this very well, so a new one is needed. 3. THE NEW HISTORY The new directory history is modeled after the URL history in programs such as Netscape Navigator. It will not be exactly like a browser's history, however. There are certain differences between file system directories and web pages (yes, really, no matter what Micros~1 says!). The main idea of the dirhistory system is to keep the data that describes a directory around until the next time you enter that directory. A secondary goal is to arrange the data in a way that preserves the order you visited the directories in, thus making it easy to provide back- and forward movement through the history. 3.1 The Current Directory There is always a history data entry for the current directory. It is not on any of the lists (mentioned below); it's stored in a special single-entry "slot" designed for the purpose. This makes it easy to always find the current directory's history entry. 3.2 The Backward, Forward and Cache Lists In addition to the current directory slot, there are three lists that also hold history entries: the backward list; the forward list; and the cache. The backward list holds entries that you have already visited once during a session. The last entry on the backward list is normally the directory that was current previous to the one that is currently current (!), and so on. If it sounds comp- licated, that's entierly my fault. :) The forward list holds entries for directories that you entered after the current directory. The forward list is only used by the DirBackward and DirForward commands; it is left blank by normal (absolute) navigation. The cache holds entries for directories that have been visited, but are no longer part of the sequence available by moving backward and forward. See the command descriptions below for more details. 3.3 History Commands The following commands operate on the history state: DirEnter Changes the current directory by simply replacing it with a new path. Appends the current dir to the back list first, and then clears the forward list. Detailed steps: 1. Find current dir entry, and update the history state in it. 2. Find entry for target directory. If found on the back list, move all entries _after_ it to the cache list. 3. Enter target dir, apply found entry (if any). 4. Append initial current dir's entry (from step #1) to the back list. 4. Clear forward list. 5. Done! DirRescan Refreshes the display of a directory, by reading the dir's contents back from the disk. Does not alter the length or contents of any history lists, but makes use of the information in them nevertheless. Detailed steps of operation: 1. Find the current directory's history entry. Should be really simple, since it should be in the "current" slot. 2. Update history information. 3. Reread the directory from disk. 4. Apply previously stored history info. 5. Done! DirBack Changes to the previous directory, i.e. the one that is last in the back list. Painfully detailed description: 1. Find current dir's slot. 2. Update history information. 3. Prepend current to forward history list. 4. Change to directory at end of backward list. 5. Done! DirForward Goes one step forward in the directory history, to the dir specified by the first item in the forward list. Steps: 1. Find current. 2. Update it. 3. Append current to backward history listt. 4. Change to directory at beginning of forward list. 5. Done! 3.4 Initial Example Illustration, showing a command, the back list, current dir, and forward list _after_ the command has executed: Command Back Current Forward (start, initial state) () "" () DirEnter "/" () "/" () DirEnter "/home" ("/") "/home" () DirEnter "/home/emil" ("/" "/home") "/home/emil" () DirBack ("/") "/home" ("/home/emil") DirBack () "/" ("/home" "/home/emil") DirForward ("/") "/home" ("/home/emil") DirForward ("/" "/home") "/home/emil" () 3.5 No Duplicates The new history system (just like the old) will not allow duplicate entries in the history. If there is an entry for a path in one of the history lists, that entry will always be used whenever that path becomes current again. This is unlike e.g. Netscape's behaviour, and motivated by two main factors: 1) it's necessary in order to preserve selection info, and 2) it's simpler and I think I understand it. :) 3.6 Second Example The example continues, from the last state shown above: Command Back List Current Dir Forward List (initial) ("/" "/home") "/home/emil" () DirEnter "/usr" ("/" "/home" "/home/emil") "/usr" () DirBack ("/" "/home") "/home/emil" ("/usr") DirBack ("/") "/home" ("/home/emil" "/usr") DirEnter "/usr" ("/" "/home") "/usr" () Note that for the last line here, the "/usr" record on the forward list would NOT be completely ignored: both lists are searched be- fore changing the directory, so that any old selection in "/usr" could be found and applied. When the record has been found and used, though, it will be deleted together with the rest of the forward list. gentoo-0.19.13/docs/scratch/filetypes.txt 0000644 0001750 0001750 00000013624 11547706437 020442 0 ustar demarchi demarchi z 1998-08-09 Emil Brink gentoo FileTypes INTRODUCTION This document describes the gentoo filetyping architecture, i.e. the means by which gentoo clasfsifies each file it shows as belonging to exactly one previously defined file type. This classification is then used to determine how gentoo is to deal with that file; it helps specifying display colors and/or pixmaps, action commands, and so on. In this document, the word "file" is used in a very general sense. A file is anything that can be found in a disk directory. Since gentoo runs on Linux (and perhaps other Unices?), this means that a file can be a directory, a plain file, a (soft) link, a (block or character) device, a socket, or a FIFO. At least I _think_ that's all... THE FILETYPE A filetype is, technically, a named tuple of identification methods. These methods can be applied to a dirpane line to determine if the disk entry described by the line belongs to the type or not. A filetype can use anything from one to four available "levels" of identification methods in order to determine if a given line has the type. These levels are: 1) inode type This is the simplest, fastest, most low-level check. The inode type tells if the line is a directory, a soft link, plain file, device, et cetera. A filetype MUST ALWAYS specify exactly ONE inode type. 2) Protection Using the protection matching rule, you can require files to have a certain combination of protection bits. You can currently only specify which bits must be set, not which must NOT be set (i.e. clear). This means that you can find all files that are writable, but not all files that are NOT writable... I don't know how important this really is, but it feels kind'a incomplete right now. 3) Suffix Match The suffix match is used to require that the file name ends in a certain string. This is very useful to find normal extensions, since a typical extension is just a suffix with a dot first. For example, you could use the suffix match to require that candidate lines have names ending in ".gif". This check is highly specialized and therefore fairly quick. Since the suffix checker is meant to be lean, mean and quick, it only allows one suffix rather than a list. If you need to check against several suffixes (suffici? suffixen?), you'll need to move to the next leve, the regular expression matcher. 4) Name Regular Expression Match If the names you're trying to find have some similarity more complex than just a plain suffix, maybe you can use this level. It lets you specify a full regular expression (using the V8 syntax found elsewhere in gentoo) against which file names are checked. For example, if you where looking for MOD files on an Amiga partition, you might specify a name RE of "^mod\..*". Or you could identify tar+gzipped files with "(\.tar\.gz$)|(\.tgz$)". 5) 'file' Regular Expression Match When none of the previous levels suffice, you can resort to the final secret weapon; the 'file' regular expression matcher. This runs the UNIX standard utility 'file' on the dirpane line in question, and then tries to match the regular expression you supplied against file's output. Using this level, you can perform virtually any kind of file identification necessary, since you can add things to the "magic" file /etc/magic used by file. As an example, you can identify executable files in the ELF format (standard on modern Linuxes) by specifying a 'file' matching RE of e.g. "ELF 32-bit (L|M)SB executable.*", or just plain "ELF.*". Note that the RE you specify is only checked against the part of file's output that is after the first colon. Please remember that using 'file' RE matching in your file typing SEVERLY degrades gentoo's performance. Beware. I'm waiting for a new release of the 'file' package that incorporates a tiny fix which will allow gentoo to use it with much greater efficiency... FILETYPING STRUCTURE Gentoo maintains a set (e.g. a list) of filetype definitions; there is no hierarchy or any other complex structure involved. The definitions are applied one by one in search for a match. As soon as any a match is found, the search is terminated and the line as considered to have the type that matched. If no type matched, the built-in always present type "Unknown" is assigned to the line, in order to guarantee that all dirpane lines always have exactly one type assigned to them. The ordering of the filetypes internally influences the speed of the matching process; this is something I will investigate once the filetyping has been more fully implemented and is somewhat stable. STYLES A filetype is just a way of specifying how to identify files that have things in common. Once the files have been partitioned into groups by their file types, it would be nice to take advantage of this grouping when working with the files. This is done through the use of styles. A style contains information that gentoo uses when rendering the dirpane; colors and pixmaps for example. It also holds data used when you manipulate the file (double-clicking it, or trying to view it with the built-in View command). Styles, unlike filetypes, form a tree structure. There is a single, always-present, "root" style. Other styles then appear as either internal or leaf nodes in the tree based in the root style. STYLE PROPERTIES The following properties can be specified in a style: DISPLAY Unselected Background Color Foreground Color Pixmap Icon Selected Background Color Foreground Color Pixmap Icon ACTION Double-click View Edit Print Play PROPERTY INHERITANCE The reason why the styles are arranged into a tree structure is to facilitate inheritance of properties. For each style (except the root) you specify which properties are to be changed from the ones of the parent style. Those that are not changed are then taken from the parent, recursively. The root style always specifies all its properties. If you're into C++ and object-oriented programming in general, this should be right up your alley. gentoo-0.19.13/docs/scratch/mount.txt 0000644 0001750 0001750 00000011552 11547706437 017576 0 ustar demarchi demarchi 1999-01-31 Emil Brink About auto mounting 1. INTRODUCTION In gentoo version 0.9.23, support for auto mounting was added. This is (like much other in gentoo) most useful on personal systems, and has *ONLY* been tested under Linux. If you're having trouble with mounting on other platforms, don't be surprised. This file gives a brief description of the mount support, and how to configure it. 2. MOUNT MODES A "mode" variable determines when gentoo will attempt to mount directories. There are three modes available: By default, the mode is "never", which causes auto mounting to be disabled. In this mode, gentoo will never mount anything no matter what you do. In the next mode, gentoo will only attempt to mount when you access a directory either by double-clicking it in a pane, or by activating a shortcut pointing at the directory in question. In the last mode, gentoo will attempt to do a mount each time you access a directory. This is perhaps the most comfortable way of doing it, but also the slowest. 3. MOUNT/UNMOUNT COMMANDS Since there is no portable way of mounting file systems, and the mount(2) system call available on Linux is privileged, gentoo uses the normal user-level mount(8) command to do the mounting. For the exact same reasons, unmounting is done by calling the umount(8) shell command. gentoo assumes that it can mount a file system on a mount- point X by issuing the command "mount X", and that it can unmount in the same way. If this isn't true on your system, you must write glue scripts that have this interface. You don't need to call your scripts "mount" and "umount", however, since the actual command names (but not the simple "calling convention") is configurable. 4. AVAILABLE FILE SYSTEM DATABASE gentoo obtains information about which directories are mount points by reading in a (set of) system database(s). On Linux systems, this database is stored in the "/etc/fstab" file. This file contains information about file systems, including which system mounts under directory. gentoo buffers this information and uses it to determine if a directory being accessed is a mount point. As hinted above, gentoo is not actually limited to reading just one of these files. You can specify any number of files, sep- arated by colons, in the "fstab" path (on the Paths config tab). 5. MOUNTED FILE SYSTEMS DATABASE Before issuing a mount command to mount a new file system, gentoo needs to check if the file system is already mounted. This is to avoid errors from the "mount" command. This check is done through another (set of) system data- base(s). On Linux, "/etc/mtab" holds the relevant information. The default is to use "/proc/mounts", however, since the latter is both faster to access, and more up to date. The time required to scan this database (which is not buffered, since you can mount/unmount outside of gentoo) is the reason why the middle mounting mode exists: it reduces the number of accesses that are considered for mounting, thereby saving time. Again, you are not limited to just one of these databases either. You can specify a list of files, separated by colons, in the "mtab" path (on the Paths tab in the config window). 6. CONFIGURING THE MOUNTING There's a tab labeled "Mounting" in the configuration window. This tab holds most of the controls needed to configure the mounting. The tab is split into two frames: one for setting the mode, and the other for setting various flags. You set the mode by clicking on one of the radio buttons in the mode frame. If you set the mounting mode to "Never", the options frame is disabled to indicate that they are not used. Below the mode frame is another frame, labeled "Mount Options". It contains some additional controls that let you fine- tune the behavior of the mounting. The text entry fields labeled "Mount Command" and "Unmount Command" let you specify the names of the shell commands used to mount and unmount file systems. These commands should take, as a single argument, the name of the *mount point*, not the file system! Also, you must specify the path (e.g. "/bin/mount") too. The check button labeled "Only Mount on Toplevel Dirs?" enables a little optimization: if checked, gentoo will not mount on a directory that has more than 2 hard links to it. This means any directory that contains another directory will never be con- sidered as a possible mount point. The "Use Command Error Dialog?" option makes gentoo grab any error output by the mount/unmount commands and show it in a dialog. If not checked, errors will appear in the shell window. The "Unmount at Exit?" option makes gentoo call the un- mount command on all file systems it mounted. This is recommended. NOTE: in addition to the stuff on the "Mounting" tab, you must also set the "fstab" and "mtab" paths (on the "Paths" tab, shockingly enough) to sensible values. For a Linux system, fstab="/etc/fstab" and mtab="/proc/mounts" works well. gentoo-0.19.13/docs/scratch/command_options.txt 0000644 0001750 0001750 00000011074 11547706437 021624 0 ustar demarchi demarchi 2008-07-08 Emil Brink Command Options 1. INTRODUCTION As of version 0.11.4, gentoo includes user interface controls for a number of "command options". These options allow you some control over how some of the built-in commands perform their actions, thus allowing you to further customize gentoo's behaviour. 2. COMMAND OPTION DESCRIPTIONS The command options are presented in the main configuration window, on the page labeled "Command Options". The options are organized on one page per command, with a row of tabs allowing you to choose which command to customize. The interface is automatically generated, which is why it currently might look a little less slick than other parts of the GUI (at least to me, it does). The descriptions here are arranged with one section per option page, ordered alphabetically (as are the pages in the actual interface). 2.1 Copy The Copy command has the following options: Preserve Dates During Copy? When set, this boolean option will cause the Copy command to attempt to also copy the access and modification dates of the original file. This is done using the utime(2) system call. Leave Failed Destination if Full Size? Normally, the Copy command will remove the destination file if an error occurs during the copying operation. This option, however, will (when set) cause the Copy command to leave the destination file, if it has the same size as the source file. This is sometimes useful in combination with the above option, since the date setting might fail on some file systems. Buffer Size This lets you set the number of bytes gentoo reads and writes while copying. Setting it to a large value might increase per- formance (since fewer system calls are being done, and more bytes transferred per call), while setting it lower will help conserve memory. The default setting is 256 KB, which seems to give reasonable performance. 2.2 DpFocus The DpFocus has just a single option: Wrap Around at Top and Bottom? When set, this option will cause the focus bar, when moved by "DpFocus prev/next" commands, to wrap around when you try to move it out of the pane. This means that if you're on the top row of a pane, and run "DpFocus prev", you will move to the last row. If, on the other hand, the option was not set, then the commandw would have no effect. 2.3 GetSize The GetSize command has only a single option: Unselect Rows When Done? When set, this option causes the GetSize command to unselect each (directory) row, after it has computed the size for it. This is the default behaviour, and is consistent with the way all other commands in gentoo work. When not set, rows will be left selected. This is somtimes useful, e.g. when issuing a GetSize command in order to determine if for example a Copy will succeed. In these cases it is nice not having to re-select the rows after the sizes has been computed. 2.4 Information The Information command has the following options: Recurse Directories? When set, this option will cause the Information command to "dive" into selected directories, and recursively compute the size of the contents. When set, an extra row (with the label "Contents") will appear in the Information window for each directory. Access, Modify and Change Date Formats These three strings allow you to specify the how the command shall format the dates it display. There are three dates per file, hence the three formatting strings. For information about the syntax for these format strings, see the strftime(3) manual page. The default format used is "%Y-%m-%d %H:%M.%S", which cause the date to appear in the ISO standard format of YYYY-MM-DD, followed by the time in 24-hour notation. 2.5 MkDir The MkDir command has only one option: CD Into New Directory? This boolean, when set, will cause the MkDir command to enter the freshly created directory. This option is also available in the actual MkDir window, for convenience. 2.6 ViewText The ViewText command, and its relatives the ViewHex and ViewTextOrHex commands, have the following options in common (not all are used by all commands): Buffer Size This lets you set the size of the read buffer used by the ViewText command when mmap() (see above) is NOT being used. As usual, a large buffer might improve performance, while a small conserves memory. Hex-Check First This option lets you set the number of bytes read (from the start of a file) by the ViewTextOrHex command when it is trying to determine how to view the file. A larger value will improve the accuracy of the decision, but take more time. The default value is 512 bytes. gentoo-0.19.13/docs/scratch/command_args.txt 0000644 0001750 0001750 00000032053 11547706437 021065 0 ustar demarchi demarchi 2010-10-06 Emil Brink Arguments to Built-In Commands 1. INTRODUCTION This little text outlines gentoo's support for argument to its built-in commands. This support was first introduced in release 0.11.6, but is likely to grow as more commands are added and/or old commands extended to support it. 2. WHAT'S NEW In releases prior to 0.11.6, gentoo's built-in commands either did not accept any kind of information from the user, or popped up some sort of interactive GUI to get the required parameters. Good examples of these two "types" of built-ins are the DirEnter and SelectRE commands; the former always figured out for itself what it should do, while the latter always presented a dialog for parameters. The addition of arguments to built-in commands changes this; now you can control commands directly from the invocation string. To take SelectRE as an example, you could now specify a command to toggle the selection state of all currently non-selected, non-directory items containing the word "foo" in their name, by giving a command such as: "SelectRE set=unselected action=toggle glob=true *foo*" This will cause the SelectRE command to immediately perform the requested matching and selection action; there will be no dialog window. 3. ARGUMENT SYNTAX The command argument system in gentoo is somewhat different from what is common in e.g. shells. There are two different kinds of arguments that can occur in a command line: keywords and non- keywords (also called "barewords"). Keywords use the keyword=value syntax. A bareword, on the other hand, is a string that does not contain an equals ("=") sign. Commands generally take zero or one bareword argument as their main input on what to do, and then zero or more optional keyword arguments to further control the action. The SelectRE command shown above is a good example; it takes as a bareword arg the regular expression to match against, and up to seven different keyword arguments to modify the way the selection is done. When compared to the syntax used in common command line interpreters like bash, this seems to be an extremely wordy and inefficient syntax. This might be true, but remember that commands in gentoo are generally not issued interactively, rather they are written once when configuring gentoo, and then executed by the click of a button or press of a key. Therefore, IMO, it is not as import- ant to optimize the command lines for speed of entry. 3.1 OVERALL KEYWORD SYNTAX The "keyword" part should be a sequence of non-blank characters. Typically, it will consist of nothing but alphabetical symbols (letters). Keywords are case insensitive. Keyword VALUES are typically NOT case insensitive! The "value" part will typically be an arbitrary string. Separating the two parts is an equals sign (=). There must not be any whitespace on either side of the equals, since that would separate the argument into multiple arguments. 3.2 KEYWORD VALUE SYNTAX Currently, there are three (rather lazily defined) types of value arguments; strings, booleans, and enumerations. 3.2.1 Strings A string is the simplest form of value: it has no special structure known to the command argument system. It's just a string of text. 3.2.2 Booleans Booleans are to be interpreted as either TRUE or FALSE. To make a boolean argument evaluate to TRUE for the command, specify one of "yes", "true", "on" and "1" as the value part of the argument. In fact, "" (the empty string) works just as well. Any other string (like "no", "false", "foo", and "I_do_not_think_so_pal") will render a value of FALSE to the command. 3.2.3 Enumerations Enumerations are arguments whose value part should be one of a small set of predefined strings. The "set" and "action" arguments shown in the SelectRE example above are enumeration arguments. Below, the legal enumerations for each command will be listed. Please note that enumerations are case-insensitive as well. 4. COMMAND ARGUMENTS This section describes the arguments understood by each builtin command in gentoo. If a command is not listed, that means it does not take any arguments. Passing arguments to a command that doesn't take any, or passing the wrong arguments, will (in most cases) have no effect. For each keyword argument below, its type is listed. Enumerations will have the valid set of strings listed. In most cases, these enumerations will have the exact same wording as some GUI controls for the same command, and will therefore (hopefully) be more or less self-explanatory. Bareword arguments are shown as having type "bareN", where N is the index on the command line of the word (counting only the barewords). If N is missing, the command takes only one bareword argument. Keywords that appear in parentheses below are actually barewords (they all have "bare" in the Type column) ! DirEnter Keyword Type Description dir string The path you want to enter. If relative (not starting with a '/'), it will be relative to the contents of the current pane. If not specified, DirEnter will check the selection as usual. (dir) bare You can also specify the path as a bare word. This will not work if the path contains the '=' symbol, though. DpFocus Keyword Type Description center bool Causes the currently focused row, if any, to be vertically centered in the pane. select bool If TRUE, the row that is current BEFORE any movement of the focus bar has its selection status toggled. (command) bare Use this bareword to control what the focus bar should do. There are several different words available: none Hide the focus bar. same Leave the bar alone. This is the default. prev Move bar up one row. next Move bar down one row. pageprev Move bar up roughly one pageful of rows. pagenext Move the bar down a rough page. first Move bar to first row in pane. last Move bar to last row in pane. activate Activate focused row; works like a double-click of it would. NOTE The "pageprev" and "pagenext" movements are not exactly well implemented. Consider them a rough hack, and use them only with that in mind. Thanks. DpFocusISrch This command has new semantics; use arrow up/down to move between hits. Keyword Type Description start string The string is interpreted as an integer, and the search will then require that the given string occurs for the *first* time at that offset in a filename for it to match. Defaults to "0", so if you say "DpFocusISrch start" it will only match to the start of filenames. text string Set the initial search string to the value, and also do a search for it immediately. DpGotoRow Keyword Type Description re string This lets you specify a pattern using the usual regular expression syntax. The first row whose file name matches the pattern will be scrolled into view. There is no requirement that the expression matches the entire filename, nor is there a requirement that it matches from the start. To get the latter, just prefix the RE with the circumflex (^) symbol, as usual. To get the former, postfix a dollar ($) sign as well. row integer This lets you specify the index of the row you wich to go to, rather than using a regular expression to select it. Only one of 're' and 'row' may be used at a time. If both are specified, 're' takes precendence. focus bool If TRUE, the target row will be focused in addition to being made visible. nocase bool If TRUE, the regular expression matching is done without regard for case differences. If FALSE, as is the default, case matters. DpFocusPath Keyword Type Description clear bool If TRUE, the contents of the path text entry box are removed before being focused. select bool If TRUE, the contents of the path text entry box will be selected in addition to focused. DpMaximize Keyword Type Description index int Maximizes the pane with the given index. If the index is negative, the current pane is maximized. FileAction Keyword Type Description action string The FileAction is used to operate upon files in a pane. It runs commands specified in the each file's style, as action properties. The argument is the name of the action to run. If no argument is given, the default action ("Default") is executed. Note that the property name is case sensitive: you must use the exact same casing as when you defined the property. This command replaces the older FileDefault, FileView, FileEdit etc. commands. DpReorient Keyword Type Description orient enum If value is "h", "horiz", or "horizontal", set pane split to horizontal (the "classic" mode). If it's "v", "vert" or "vertical", set it to vertical. If absent, the mode is toggled to whichever isn't the current one. quiet bare If present, the change of the orientation will not "dirty" the configuration. MenuPopup Keyword Type Description atfocus bare If included, the gentoo will attempt to position the menu over the currently focused row, rather than at the mouse pointer position. If no focused row exists, the menu is centered in the pane. menu string Name of menu to pop up. The only name currently supported is the default, "DirPaneMenu". SelectRE Keyword Type Description set enum Determine the set of rows to do the selection in, based on the rows' current selection status. Valid values are "all rows", "selected", and "unselected". type enum Further affect the set of affected rows, this time based on the row's file system type. Valid values are "all types", "directories only", and "non-directories only". action enum Controls what is done with rows that match the expression. Should be one of "select", "unselect" and "toggle". content enum Selects the content to match against. Must be a single mnemonic word that signifies the content type. The following types of content are currently recognized: name nlink devmin size uid atime smartsize uname mtime blocks gid ctime blocksize gname type modenum device (icon) modestr devmaj The use of "icon" as content is not supported. Hopefully, these shortened names should be understandable. glob bool If TRUE, the regular expression will be interpreted as a shell glob pattern. If not, it will be taken as a true RE. invert bool If TRUE, invert the sense of the matching. full bool If TRUE, require the expression to match full text of a row's name. If FALSE, a partial match (e.g. "a" matches "abc") will do. nocase bool When TRUE, the regular expression matcher will ignore differences in case between the expression and the filenames. (re) bare The actual regular expression to match. If this word is not present, the dialog will appear. NOTE Arguments to the SelectRE command will retain their values across invocations, and will also appear as defaults in the GUI the next time it is used. SelectRow Keyword Type Description row number Specify the number of the row you wish to have selected. Only a single row can be specified. You can use the "0x" prefix for hexadecimal row numbers, if you're so inclined. action enum Should be one of "select", "unselect", and "toggle". Hopefully self-explanatory. NOTE If the "row" keyword is _not_ specified, gentoo will use whatever row was last clicked (in any pane, not necessarily the current one). This is kind of tricky to use correctly, but works well when put in sequence with a "MenuPopup" and bound to the right mouse button in panes. This emulates Windows right-clicking, which is sometimes neat. SelectShell Keyword Type Description set enum Same as for SelectRE, see above. type enum Same as for SelectRE, see above. action enum Same as for SelectRE, see above. content enum Same as for SelectRE, see above. (command) bare The command to execute. The selected content will be appended for each row in the set, and when the command returns "success" (i.e. zero), the action will be performed. Example: SelectShell action=toggle "grep -q hello" NOTE Arguments to the SelectShell command will retain their values across invocations, and will also appear as defaults in the GUI the next time it is used. SelectSuffix Keyword Type Description action enum Controls what will be done to rows whose names end in the same suffix as either the row you clicked or the focused row. Can be "select", "unselect" or "toggle". Self-explanatory? ViewText Keyword Type Description encoding string Name of the encoding to expect text to be in. mode enum Controls how ViewText will view the contents of a given file. If absent or set to "auto", it will inspect the beginning of the file; if it looks like text in the given encoding, it's viewed as such. If not, or if mode is set to "hex", it will be viewed as hexadecimal data. You can also set the mode to "text" to force text viewing. Quit Argument Type Description dialog bool If TRUE, the Quit command will always show a dialog, regardless of whether the config has changed or not. If FALSE, the dialog will never be shown. To get the old-style behaviour, with automatic dialog only if the config has changed, omit the argument. gentoo-0.19.13/docs/scratch/renamere.txt 0000644 0001750 0001750 00000016345 11547706437 020237 0 ustar demarchi demarchi 1999-10-31 Emil Brink About gentoo's RenameRE command 1. INTRODUCTION This document contains a few notes, hints and tips on how to use the RenameRE command in gentoo. This command was introduced in the 0.11.10 release, which became available early November, 1999. 2. PURPOSE OF RenameRE The purpose of the RenameRE command is to support flexible renaming. For example, you can use RenameRE to change the extension on a bunch of files with a single command, or replace some other portion in a set of filenames. It's not a command that sees usage every day, but when you need it you tend to need it badly. :) Hopefully, the RenameRE command will "save" you from having to throw together a script or a fancy shell command line. If you really enjoy writing those scripts, feel free not to use the command. 3. OPERATING MODES For maximum ease of use, RenameRE provides not only a regular expression-based replacement algorithm, but also a simpler replacement algorithm. Before executing the RenameRE command, select one or more files. It often makes more sense to use the command when you have more than one file selected, but of course it will work on a single file as well. If you have no files selected when envoking the command, nothing happens (just as with most other file operation commands in gentoo). When there is a selection, the command pops up a simple dialog letting you chose one of the two operating modes, and then start the renaming operation by clicking the dialog's "OK" button. If you change your mind, just hit "Cancel" or the Escape key. You select operating mode by clicking the tabs in the top of the dialog; this also changes the dialog's contents to show that mode's controlling widgets. When you hit "OK", RenameRE will operate in the mode whose controls are visible. 3.1 Replacement The first mode is called "simple". It operates like the text replacement found in most editors, or like everybody's favorite Perl operator, s//. The simple replacement mode takes the following parameters: "Replace" The string you to search for. "With" The string you to replace any found occurances of the "Replace" string with. "Ignore Case?" If checked, the search will ignore any differences in case between the "Replace" string and the filenames. Perl people, think of this as the /i option character. "Replace All?" This causes the command to continue searching through the input filename even after having found and performed a replacement. In Perl, this looks like a trailing /g option. For example, if you had a filename of "abcabcabc" and specified the parameters as replace="abc", with="ABC", and leave the two options at their default values of false, the file would be renamed to "ABCabcabc". Check the "Replace All?" button, and the result is "ABCABCABC". The primary use for the Simple replacement mode is perhaps to change filename extensions. Doing this requires some care, however, since you cannot be sure that the string you find is indeed the extension, i.e. that it is last in the filename. For such control, you need to use the Regular Expression mode. 3.2 Regular Expressions The second mode is a lot more complicated, but also a lot more powerful and flexible. The basic idea is to match a regular expression against each of the filenames. The expression can con- tain subexpressions (enclosed in round parens). If the expression matches against an incoming filename, a second string is used to generate the new filename. In this second string, you can use $N to refer to the text in the incoming filename that matched the N:th subexpression in the regular expression. N should be a digit in the range 1..9. Any other text in the second string will be copied verbatim. To get a single dollar sign in the new filename, use $$. Any other character following a dollar sign will cause a parse error, and the rename will be aborted. The parameters you can provide in the dialog are as follows: "From" This is where you enter the regular expression. You can use parenthesis to indicate subexpression, and use the matching text in the new filename. "To" Here, you specify a string that forms the new filename. You can use $N to refer to the text that matched the N:th subexpression in the From string. "Ignore Case?" If checked, the regular expression matcher will disregard differences in case. Let's use a huge example to make the operation of the regular expression RenameRE a bit clearer. Let's assume you have a set of HTML documents whose names have the general form "gentoo-TOPIC(CATEGORY).htm", like this: "gentoo-commands(internals).htm", "gentoo-selecting(usage).htm", "gentoo-quitting(usage).htm", "gentoo-config(usage).htm", "gentoo-gui(internals).htm", "gentoo-re(misc).htm". We want to rename these so that the category (the word in parenthesis) is moved to the front, the word gentoo is removed, the actual content label is last before the dot, and that the extension is "html". To do this, we specify the following expression in the "From" box: "^gentoo-([^(]+)\(([^)]+)\)\.htm$" 1 2 3 4 5 6 7 8 This expression can be broken down: 1. The caret (^) anchors the expression to the beginning of the incoming string, thus making sure that we begin at the very start. Without this, there could be any prefix before the "gentoo", and we would produce an incorrect result. 2. The word "gentoo-" matches itself. 3. The construct ([^(]+) matches one more more characters that are not opening parenthesis. This should collect the letters of the topic part of the incoming names. 4. The backslash followed by opening paren "\(" matches exactly one opening parenthesis, which is the one between the topic and category parts of the filenames. 5. ([^)]+) matches the category, up to (but not including) the closing parenthesis. 6. Then follows a backslash-escaped closing parenthesis. 7. The sequence "\.htm" matches a dot followed by the three letters "htm". 8. The dollar sign anchors the expression to the end of the string, so that the ".htm" is really the final part of the filename. OK. That should take care of the incoming filenames, make sure they have the desired format, while at the same time storing away the information we want to conserve. Now, we specify a "To" string like this: "$2-$1.html" That's all there is! The $2 will insert the text that matched the second parenthesized subexpression, i.e. the one labeled 5 in the above breakdown. This will make the category appear first in the output. The dash goes straight through into the output name, followed by the topic as referenced by the $1 operator. The dot and the "html" suffix go straight through as well. Of course, we could have used a subexpression to match the "htm" extension as well, and entered "$3l" in the "To" string to add the final 'l', but that seemed like over- kill to me... :) The point of this example was to show how you can do fairly non-trivial permutations of the input filenames. A good understanding of regular expressions helps. 4. CLOSING WORDS Well, that should introduce the RenameRE command sufficiently and allow you to use it. The Simple mode is probably simple enough to just use once you know what its parameters mean, while the full-blown Regular Expression mode might warrant some practice. Anway, enjoy! gentoo-0.19.13/docs/scratch/focusing.txt 0000644 0001750 0001750 00000006513 11547706437 020252 0 ustar demarchi demarchi 1999-05-13 Emil Brink Keyboard focusing in gentoo 1. INTRODUCTION This little scratch document introduces the support for keyboard- controlled focusing introduced with gentoo 0.11.6. 2. WHAT? The #1 request I've received from users of gentoo during the time it has been publicly available (around 8 months or so, I think), has been to add support for keyboard navigation. I have always responded with that this is difficult under current versions of the GTK+ toolkit. It still is, but I hacked around that. Basically, gentoo now supports the notion of "focus", which works a bit like a cursor would in a text-editing program. At any one time, zero or one row is currently focused. There is a command which does the equivalent of a double-click on the currently focused row, thus allowing you to e.g. enter directories, view text files, and so on. It's pretty neat. The focused row is rendered in what is hopefully a clear manner, allowing you to distinguish between it and other, non- focused rows. The focusing is also visible regardless of whether the focused row is currently selected or not. It is at this point not possible to customize the colors used for focusing. I expect this to become possible in a later release. 3. HOW? The focusing is controlled by the addition of a single new built- in command, DpFocus. Various internal routines have also been extended and modified to be focus-aware. The DpFocus command works with command arguments, and is therefore documented in "docs/scratch/command_args.txt". Since the documentation there is perhaps a bit terse, I might as well repeat it here using 1,000 words (but no pictures). 3.1 The DpFocus Command Syntax The general syntax of the command is: DpFocus [center=
1zъ>S+FOiRy4ĩNSJQԢgiӢ;KҠqTJժZXͪVծz1gL].EZVd*cY+>x+^־J-c0Pӏ*M1"* º1V]c7eLYv!,gWVς6a
JƠ*xkX[κ%%]\8יu2-oZJmc$f;wܜJwuEEw)ΑBWkXˮ1 .||lt0k^Uİ%qe{YVp!֗6+a뒶R |E`[SI,d j,6@rAe8*/Tko'
