[gentoo-commits] proj/ufed:master commit in: /

["Sven Eden" <sven.eden@gmx.de>]

commit:     507076c625dd85d82a9dfb15fa095bc0c0cda86b
Author:     Sven Eden <sven.eden <AT> gmx <DOT> de>
AuthorDate: Thu Feb 21 10:03:35 2013 +0000
Commit:     Sven Eden <sven.eden <AT> gmx <DOT> de>
CommitDate: Thu Feb 21 10:03:35 2013 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/ufed.git;a=commit;h=507076c6

Updated man page to contain more (and easier to read) information. Thanks to Roman Zilka, who suggested most of these changes.

---
 ufed.8.in |  123 ++++++++++++++++++++++++++++++++++++------------------------
 1 files changed, 74 insertions(+), 49 deletions(-)

diff --git a/ufed.8.in b/ufed.8.in
index 523cbf4..5294b65 100644
--- a/ufed.8.in
+++ b/ufed.8.in
@@ -3,7 +3,7 @@
 ufed \- Gentoo Linux USE flags editor
 .SH "SYNOPSIS"
 .B ufed 
-.SH "DESCRIPTION"
+.SH "INTRODUCTION"
 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.
@@ -69,11 +69,11 @@ meaning of the flag differs, however, for each package.
 
 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.
+If a USE flag does not apply to your system, or is highly experimental, it is
+"masked" and can not be enabled.
 .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.
+If a USE flag is mandatory for your system or for a specific package, it is
+"forced" and can not be disabled.
 
 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
@@ -82,7 +82,11 @@ flags is set in your make.conf, you can remove it with ufed.
 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
+.SH "Navigation and control"
+
+ufed will present you with a list of descriptions for each USE flag. If a
+description is too long to fit on your screen, you can use the Left and Right
+arrow keys to scroll the descriptions.
 
 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.
@@ -91,72 +95,90 @@ 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.
+F5: Toggle display of local / global / 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.
+F6: Toggle display of flags supported by at least one installed
+package / supported by no installed package / all flags.
 .br
-F7: Switch between masked and forced flags, flags that are neither masked nor
-forced and all flag descriptions.
+F7: Toggle display of masked and forced flags / flags that are
+neither masked nor forced / all flags.
 
 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.
 
-After changing flags, press the Return or Enter key to make this permanent,
-or press Escape to revert your changes.
+After changing flags, press the Return or Enter key to save your USE flag setup
+to make.conf, or press Escape to revert your changes.
 
 Note: Depending on your system, you may need to wait a second before ufed
 detects the Escape key or mouse clicks; in some cases, you can use the
-ncurses environment variable ESCDELAY to change this. See the ncurses(3X)
-manpage for more info.
+ncurses environment variable ESCDELAY to change this. See \fBncurses\fR(3X)
+for more info.
 
-.B Display layout
-
-ufed will present you with a list of descriptions for each USE flag. If a
-description is too long to fit on your screen, you can use the Left and Right
-arrow keys to scroll the descriptions.
+.SH "Display layout"
 
 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:
+Each line consists of the following elements:
 
  (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 (-). 
+.TP
+\fB(s) : Your selection.\fR
 .br
-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).
+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 (-). 
+.TP
+\fBflag : The name of the flag.\fR
 .br
-D    : [D]efault settings from make.defaults or the ebuilds of installed
-packages. Masked flags are shown here as 'm', forced flags as 'f'.
+If the flag is globally masked, it will be shown as (-flag). If the flag is
+globally forced, it will be shown as (flag).
+.TP
+\fBD : System [D]efault settings.\fR
 .br
-P    : [P]rofile package settings from package.use.
+These are read from
+@GENTOO_PORTAGE_EPREFIX@/usr/portage/profiles/.../make.defaults and the
+\fBebuild\fR(5) IUSE defaults of installed packages. The settings in make.defaults,
+however, take precedence over the ebuild IUSE settings.
 .br
-C    : [C]onfiguration settings from @GENTOO_PORTAGE_EPREFIX@/etc/make.conf,
-@GENTOO_PORTAGE_EPREFIX@/etc/portage/make.conf and
-@GENTOO_PORTAGE_EPREFIX@/etc/portage/package.use.
+Masked flags are shown here as 'm', forced flags as 'f'.
+.TP
+\fBP : [P]rofile package settings.\fR
 .br
-S    : [S]cope of the description, package specific descriptions have an 'L'
-for "local".
+These are read from
+@GENTOO_PORTAGE_EPREFIX@/usr/portage/profiles/.../package.use. These package
+specific settings take precedence over the [D]efault settings.
+.TP
+\fBC : [C]onfiguration settings.\fR
 .br
-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.
+These are read from @GENTOO_PORTAGE_EPREFIX@/etc/make.conf,
+@GENTOO_PORTAGE_EPREFIX@/etc/portage/make.conf and
+@GENTOO_PORTAGE_EPREFIX@/etc/portage/package.use. These take precedence over
+the [D]efault and [P]rofile settings, with package.use overriding settings
+from make.conf.
+.TP
+\fBS : [S]cope of the description.\fR
 .br
-(packages): List of packages that support this flag with the following
-description.
+Local flag descriptions have an 'L' for "local" here.
+.TP
+\fBi : [i]nstalled.\fR
 .br
-description : The description of the flag from use.desc or use.local.desc.
-
+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.
+.TP
+\fB(packages): List of packages that support this flag.\fR
+.TP
+\fBdescription : The description of the flag from use.desc or use.local.desc.\fR
+.PP
 If the character in any of the D, P or C column is a + then that USE flag was
 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).
 
+Flags marked as [+] or [-] will be saved in your make.conf when you leave the
+program with an Enter.
+
 You can change the order of the (packages) and the description with the F9 key.
 
 .SH "REPORTING BUGS"
@@ -175,19 +197,22 @@ Contains user specified USE flags
 .br
 This is where ufed places a backup of your make.conf file.
 .TP
-\fB@GENTOO_PORTAGE_EPREFIX@/etc/make.profile/make.defaults\fR
-Contains system default USE flags
+\fB@GENTOO_PORTAGE_EPREFIX@/usr/portage/profiles/.../make.defaults\fR
+Contains system default USE flags. These are the default settings and take
+precedence over \fBebuild\fR(5) IUSE defaults.
 .TP
-\fB@GENTOO_PORTAGE_EPREFIX@/etc/make.profile/package.use\fR
-Contains per package default USE flags
+\fB@GENTOO_PORTAGE_EPREFIX@/usr/portage/profiles/.../package.use\fR
+Contains per package default USE flags. These are per package default settings
+and take precedence over system default USE flags.
 .TP
 \fB@GENTOO_PORTAGE_EPREFIX@/etc/portage/package.use\fR
-Contains user specified USE flags per package
+Contains user specified USE flags per package. These take precedence over all
+system defaults and the settings in your make.conf file.
 .TP
-\fB@GENTOO_PORTAGE_EPREFIX@/etc/make.profile/use.mask\fR
+\fB@GENTOO_PORTAGE_EPREFIX@/usr/portage/profiles/.../use.mask\fR
 Restricted USE flags
 .TP
-\fB@GENTOO_PORTAGE_EPREFIX@/etc/make.profile/use.force\fR
+\fB@GENTOO_PORTAGE_EPREFIX@/usr/portage/profiles/.../use.force\fR
 Enforced USE flags
 .TP
 \fB@GENTOO_PORTAGE_EPREFIX@/usr/portage/profiles/use.desc\fR