--- xml/htdocs/proj/en/glep/glep-0029.txt	2004/08/22 02:02:32	1.2
+++ xml/htdocs/proj/en/glep/glep-0029.txt	2004/10/18 15:32:10	1.3
@@ -1,17 +1,13 @@
 GLEP: 29
 Title: USE flag groups
-Version: $Revision: 1.2 $
+Version: $Revision: 1.3 $
 Author: Ciaran McCreesh <ciaranm@gentoo.org>
-Last-Modified: $Date: 2004/08/22 02:02:32 $
+Last-Modified: $Date: 2004/10/18 15:32:10 $
 Status: Draft
 Type: Standards Track
 Content-Type: text/x-rst
 Created: 19-August-2004
-Post-Date: 21-August-2004
-
-BIG FAT DISCLAIMER: EARLY DRAFT, SEND COMMENTS TO ciaranm. EVERYTHING IN
-HERE IS OPEN TO DISCUSSION. THE WRITING STYLE SUCKS. MAY CAUSE CANCER IN
-PUPPIES.
+Post-Date: 21-August-2004, 18-October-2004
 
 Abstract
 ========
@@ -22,14 +18,17 @@
 Motivation
 ==========
 
-USE flags allow the user to have software built in a manner which is
-relevant for their system's role. For example, a desktop user will
-probably want to enable optional X support in packages, whereas a server
-user will not. However, with several hundred USE flags available, it can
-be time consuming to set up make.conf appropriately.
-
-This GLEP proposes a mechanism for grouping USE flags to simplify
-selection.
+Many packages have optional support for other packages (for example, the
+Vim text editor can optionally support perl, python and ruby
+interpreters). In Gentoo, these optional dependencies can be selected by
+the user using USE flags. This allows a system appropriate for a given
+environment to be built -- a server, for example, should not typically
+have an X11 server or sound support, whereas both would be desirable on
+most desktop systems.
+
+With several hundred USE flags available, deciding upon which USE flags to
+enable and which to disable can take a long time. This GLEP proposes a
+mechanism for grouping USE flags to simplify selection.
 
 Specification
 =============
@@ -40,7 +39,10 @@
 A group shall consist of one or more USE flags. These groups are defined
 in ``${PORTDIR}/profiles/use.groups``. It is proposed that uppercase names
 only are used for groups to keep them visually distinct from normal USE
-flags. The file format is similar to the existing use.* files:
+flags, although this should not be enforced programatically. The file
+should be similar in format to the existing use.* files. In the following,
+``SOME_GROUP`` and ``OTHER_GROUP`` are group names, and ``flag1`` through
+``flag5`` are USE flag names:
 
 ::
 
@@ -57,6 +59,22 @@
 	GROUP3 flag4
 	GROUP4 @GROUP2 @GROUP3 flag5
 
+The same flag may end up being in a particular group more than once:
+
+::
+
+	GROUP1 flag1 flag2
+	GROUP2 flag2 flag3
+	GROUP3 @GROUP1 @GROUP2 flag3 flag4
+
+As with similar files, comments may be included. Lines which begin with a
+hash symbol (#) are comments.
+
+::
+
+	# This is a comment
+	FOO bar baz fnord
+
 Users may create their own groups using ``/etc/portage/use.groups``. This
 file overrides the profile settings in the case of duplicates.
 
@@ -69,6 +87,7 @@
 
 ::
 
+	# This is a comment
 	DESKTOP Flags which are appropriate for most desktop systems
 	RECOMMENDED Flags which should be enabled on almost all systems
 
@@ -97,8 +116,8 @@
 
 It is proposed that ``-@GROUP`` syntax should *not* be supported. Instead,
 users wishing to turn most things off could use the ``-*`` USE syntax
-along with a group (for example, @RECOMMENDED) which turned on flags (for
-example, pam and readline) which should usually be used.
+along with a group (for example, @RECOMMENDED or @MINIMAL) which turned on
+flags (for example, pam and readline) which should usually be used.
 
 Adding New Groups
 -----------------