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

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

commit:     f64909434026cc5dad9042d0b96355bc27e93712
Author:     Sven Eden <sven.eden <AT> gmx <DOT> de>
AuthorDate: Mon Feb 18 06:10:08 2013 +0000
Commit:     Sven Eden <sven.eden <AT> gmx <DOT> de>
CommitDate: Mon Feb 18 06:10:08 2013 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/ufed.git;a=commit;h=f6490943

Updated the program help page and added some more information to the man page. Both should be in sync now.

---
 ufed-curses-help.c |  162 +++++++++++++++++++++++++++++++++++++---------------
 ufed.8.in          |   10 +++-
 2 files changed, 124 insertions(+), 48 deletions(-)

diff --git a/ufed-curses-help.c b/ufed-curses-help.c
index 5788e1c..10855b6 100644
--- a/ufed-curses-help.c
+++ b/ufed-curses-help.c
@@ -26,57 +26,18 @@ static void init_lines(void);
 static void init_lines(void)
 {
 	static const char * const help[] = {
-"--- What is ufed ? ---",
+"--- What is ufed? ---",
 "",
 "ufed is a simple program designed to help you configure the systems USE "
-"flags (see below) to your liking.",
+"flags (see below) to your liking. To enable or disable a flag highlight it "
+"and hit space.",
 "",
-"--- 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.",
-"",
-"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.",
-"",
-"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.",
-"",
-"--- 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.",
-"",
-"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.",
-"flag : The name of the flag",
-"M    : Either 'M' for Masked (always disabled), 'F' for Forced (always "
-"enabled) or empty for regular flags.",
-"D    : Default settings from make.defaults.",
-"P    : Package settings from package.use and IUSE for installed packages.",
-"C    : Configration setting from make.conf.",
-"S    : Scope of the description, package specific descriptions have an 'L' "
-"for \"local\".",
-"i    : 'i' if any affected package is installed.",
-"(packages): List of affected packages",
-"description : The description of the flag from use.desc or use.local.desc.",
+"ufed edits the USE flag settings in your make.conf file only. It can not be "
+"used to edit your package.use file.",
 "",
-"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.",
+"If you have two make.conf files, /etc/make.conf and /etc/portage/make.conf, "
+"ufed reads the first, overrides its settings with the second, and writes "
+"changes to the second.",
 "",
 "--- What Are USE Flags? ---",
 "",
@@ -112,6 +73,113 @@ static void init_lines(void)
 "and in",
 " /usr/portage/profiles/use.local.desc",
 "",
+"--- 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 "
+"/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.",
+"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.",
+"",
+"--- 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.",
+"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.",
+"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.",
+"",
+"--- 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.",
+" F6: Switch between flags for which packages are installed that accept this "
+"flag, no packages are installed or all flag descriptions.",
+" 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.",
+"",
+"After changing flags, press the Return or Enter key to make this permanent, "
+"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.",
+"",
+"--- 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.",
+"",
+"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. If a flag is enabled or disabled by default, it will be "
+"shown as either (+) or (-).",
+"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).",
+"D    : [D]efault settings from make.defaults or the ebuilds of installed "
+"packages. Masked flags are shown here as 'm', forced flags as 'f'.",
+"P    : [P]rofile package settings from package.use.",
+"C    : [C]onfiguration settings from /etc/make.conf, /etc/portage/package.use "
+"and /etc/portage/package.use.",
+"S    : [S]cope of the description, package specific descriptions have an "
+"'L' for \"local\".",
+"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.",
+"(packages): List of packages that support this flag with the following "
+"description.",
+"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(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).",
+"",
+"You can change the order of the (packages) and the description with the F9 "
+"key.",
+"",
+"--- REPORTING BUGS ---",
+"",
+"Please report bugs via http://bugs.gentoo.org/",
+"",
 "--- Credits ---",
 "",
 "ufed was originally written by Maik Schreiber <blizzy@blizzy.de>.",

diff --git a/ufed.8.in b/ufed.8.in
index 8177feb..652f973 100644
--- a/ufed.8.in
+++ b/ufed.8.in
@@ -8,6 +8,13 @@ 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.
 
+ufed edits the USE flag settings in your make.conf file only. It can not be
+used to edit your package.use file.
+
+If you have two make.conf files, @GENTOO_PORTAGE_EPREFIX@/etc/make.conf and
+@GENTOO_PORTAGE_EPREFIX@/etc/portage/make.conf, ufed reads the first, overrides
+its settings with the second, and writes changes to the second.
+
 .B What are USE flags?
 
 The USE settings system is a flexible way to enable or disable various features
@@ -131,7 +138,8 @@ packages. Masked flags are shown here as 'm', forced flags as 'f'.
 .br
 P    : [P]rofile package settings from package.use.
 .br
-C    : [C]onfiguration settings from make.conf and
+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.
 .br
 S    : [S]cope of the description, package specific descriptions have an 'L'