Updated man page to current functionality.

1 files changed, 103 insertions, 45 deletions

diff --git a/ufed.8.in b/ufed.8.in
index 23886b7..8177feb 100644
--- a/ufed.8.in
+++ b/ufed.8.in
@@ -1,4 +1,4 @@
-.TH "UFED" "8" "05 Feb 2013" "UFED 0.42" "UFED"
+.TH "UFED" "8" "15 Feb 2013" "UFED 0.90" "UFED"
 .SH "NAME"
 ufed \- Gentoo Linux USE flags editor
 .SH "SYNOPSIS"
@@ -8,12 +8,93 @@ UFED is a simple program designed to help you configure the
 systems USE flags (see below) to your liking. To enable or
 disable a flag highlight it and hit space.
 
+.B What are USE flags?
+
+The USE settings system is a flexible way to enable or disable various features
+at package build-time on a global level and for individual packages. This
+allows an administrator to control how packages are built in regards to the
+optional features which can be compiled into those packages.
+
+For instance, packages with optional GNOME support can have this support
+disabled at compile time by disabling the "gnome" USE flag. Enabling the
+"gnome" USE flag would enable GNOME support in these packages.
+
+The effect of USE flags on packages is dependent on whether both the
+software itself and the package ebuild supports the USE flag as an optional
+feature. If the software does not have support for an optional feature then the
+corresponding USE flag will obviously have no effect.
+
+Also many package dependencies are not considered optional by the software and
+thus USE flags will have no effect on those mandatory dependencies.
+
+A list of USE keywords used by a particular package can be found by checking
+the IUSE line in any ebuild file or by using "equery" from gentoolkit.
+
+See http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=2&chap=2
+for more information on USE flags.
+
+Please also note that if UFED describes a flag (Unknown) it generally means
+that it is either a spelling error in one of the 3 configuration files or
+it is not an officially sanctioned USE flag. Sanctioned USE flags can be found 
+in @GENTOO_PORTAGE_EPREFIX@/usr/portage/profiles/use.desc and
+in @GENTOO_PORTAGE_EPREFIX@/usr/portage/profiles/use.local.desc.
+
+.B What are "global" and "local" USE flags?
+
+From the perspective of any package there is no distinction between "local" and
+"global" flags. A package either listens to a specific flag or it doesn't.
+
+The difference is the description, and maybe the impact of whether a flag is
+set or not. If a package supports a flag that has a global description in
+@GENTOO_PORTAGE_EPREFIX@/usr/portage/profiles/use.desc but does make use of
+the flag differently, then the package maintainer has to add a local
+description to the packages metadata.xml file.
+.br
+The same applies to flags that have no global description, a local one must be
+provided then.
+
+An example would be a package with the USE flag "tiff", that does not only add
+support for the TIFF image format, but changes the output format of the
+program installed. The USE flag then would have a different impact on the
+package than described in the global description; a local description must be
+provided then.
+
+.B What are "Masked" and "Forced" flags?
+
+ufed allows to view the descriptions of flags that are either masked or forced.
+
+If a USE flag does not apply to your system, or is highly experimental, it can
+be masked, making it impossible to select.
+.br
+If a USE flag is mandatory for your system or for a specific package, it can be
+forced, making it impossible to turn it off.
+
+Flags that are masked or forced globally have their names displayed in
+parentheses, and are prefixed with a '-' if they are masked. If one of these
+flags is set in your make.conf, you can remove it with ufed.
+.br
+If a flag is only masked or forced for specific packages, a lower case 'm'
+or 'f' in the defaults column (see "Display layout" below) indicates this.
+
 .B Navigation and control
 
 Use the Up and Down arrow keys, the Page Up and Page Down keys, the Home and
 End keys, or start typing the name of a flag to select it.
 Use the space bar to toggle the setting.
 
+You can apply various filters on the flags to display. A status line on the
+bottom right will show you which filters are in effect.
+
+F5: Switch between local, global or all flag descriptions.
+.br
+F6: Switch between flags for which packages are installed that accept this
+flag, no packages are installed or all flag descriptions.
+.br
+F7: Switch between masked and forced flags, flags that are neither masked nor
+forced and all flag descriptions.
+
+The default is to display all flags that are neither masked nor forced.
+
 If ncurses is installed with the "gpm" use flag enabled, you can use your
 mouse to navigate and to toggle the settings, too.
 
@@ -35,64 +116,41 @@ ufed attempts to show you where a particular use setting came from, and what
 its scope and state is.
 
 The display consists of the following information:
- (s) flag  M|DPC|Si| (packages) description
 
-(s)  : Your selection, either '+' to enable, '-' to disable, or empty to keep
-the default value.
-.br
-flag : The name of the flag
+ (s) flag  |DPC|Si| (packages) description
+
+(s)  : Your selection, either [+] to enable, [-] to disable, or empty to keep
+the default value. If a flag is enabled or disabled by default, it will be
+shown as either (+) or (-). 
 .br
-M    : Either 'M' for Masked (always disabled), 'F' for Forced (always
-enabled) or empty for regular flags.
+flag : The name of the flag. If the flag is globally masked, it will be shown
+as (-flag). If the flag is globally forced, it will be shown as (flag).
 .br
-D    : Default settings from make.defaults.
+D    : [D]efault settings from make.defaults or the ebuilds of installed
+packages. Masked flags are shown here as 'm', forced flags as 'f'.
 .br
-P    : Package settings from package.use and IUSE for installed packages.
+P    : [P]rofile package settings from package.use.
 .br
-C    : Configration setting from make.conf.
+C    : [C]onfiguration settings from make.conf and
+@GENTOO_PORTAGE_EPREFIX@/etc/portage/package.use.
 .br
-S    : Scope of the description, package specific descriptions have an 'L'
+S    : [S]cope of the description, package specific descriptions have an 'L'
 for "local".
 .br
-i    : 'i' if any affected package is installed.
+i    : [i]nstalled, indicates with an 'i' if either the listed packages are
+installed on your system, or if at least one package that supports this flag
+is installed. The latter applies to the global description of the flag.
 .br
-(packages): List of affected packages
+(packages): List of packages that support this flag with the following
+description.
 .br
 description : The description of the flag from use.desc or use.local.desc.
 
 If the character in any of the D, P or C column is a + then that USE flag was
-set in that file, if it is a space then the flag was not mentioned in that
-file and if it is a - then that flag was unset in that file.
+set in that file(s), if it is a space then the flag was not mentioned in that
+file(s) and if it is a - then that flag was unset in that file(s).
 
-.B What are USE flags?
-
-The USE settings system is a flexible way to enable or disable various features
-at package build-time on a global level and for individual packages. This
-allows an administrator to control how packages are built in regards to the
-optional features which can be compiled into those packages.
-
-For instance, packages with optional GNOME support can have this support
-disabled at compile time by disabling the "gnome" USE flag. Enabling the
-"gnome" USE flag would enable GNOME support in these packages.
-
-The effect of USE flags on packages is dependent on whether both the
-software itself and the package ebuild supports the USE flag as an optional
-feature. If the software does not have support for an optional feature then the
-corresponding USE flag will obviously have no effect.
-
-Also many package dependencies are not considered optional by the software and
-thus USE flags will have no effect on those mandatory dependencies.
-
-A list of USE keywords used by a particular package can be found by checking
-the IUSE line in any ebuild file or by using "equery" from gentoolkit.
-
-See http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=2&chap=2
-for more information on USE flags.
-
-Please also note that if UFED describes a flag (Unknown) it generally means
-that it is either a spelling error in one of the 3 configuration files or
-it is not an officially sanctioned USE flag. Sanctioned USE flags can be found 
-in /usr/portage/profiles/use.desc and in /usr/portage/profiles/use.local.desc.
+You can change the order of the (packages) and the description with the F9 key.
 
 .SH "REPORTING BUGS"
 Please report bugs via http://bugs.gentoo.org/