Document build_options: symbols

2 files changed, 12 insertions, 12 deletions

diff --git a/doc/configuration/use.html.part.in b/doc/configuration/use.html.part.in
index 0207feb42..e0a1a6309 100644
--- a/doc/configuration/use.html.part.in
+++ b/doc/configuration/use.html.part.in
@@ -31,7 +31,7 @@ specification may be any of:</p>
     <li><code>flag</code>, which enables that flag.</li>
     <li><code>flag=value</code>, which enables that flag and sets its parameter value. Most flags do not
     use parameters, and so any parameter value specified is ignored. See the <code>BUILD_OPTIONS: jobs</code>
-    flag below for an example of one that does.</li>
+    and <code>BUILD_OPTIONS: symbols</code> flags below for an example of ones that do.</li>
     <li><code>-flag</code>, which disables that flag.</li>
     <li><code>label:</code>, which marks any subsequent flags on that line as applying to a particular use expand
     (Gentoo) or suboption (Exherbo) label. Common examples of use expand labels are <code>VIDEO_CARDS</code>,
@@ -50,13 +50,6 @@ default <code>VIDEO_CARDS</code> from your profile, you will need to use <code>*
 <code>BUILD_OPTIONS</code> group. Packages may have any of the following special flags:</p>
 
 <dl>
-    <dt>split</dt>
-    <dd>If enabled, Paludis will split debugging information into <code>/usr/lib/debug</code> before merging
-    binaries and libraries.</dd>
-
-    <dt>strip</dt>
-    <dd>If enabled, Paludis will strip debugging information before merging binaries and libraries.</dd>
-
     <dt>recommended_tests</dt>
     <dd>If set, Paludis will run any 'recommended' tests provided by a package.</dd>
 
@@ -81,6 +74,13 @@ default <code>VIDEO_CARDS</code> from your profile, you will need to use <code>*
     <dt>jobs</dt>
     <dd>If set to an unsigned integer, specifies the number of jobs to run in parallel when build systems
     support this (e.g. <code>BUILD_OPTIONS: jobs=4</code> would imply <code>make -j4</code>).</dd>
+
+    <dt>symbols</dt>
+    <dd>Controls how debug symbols in executables and libraries are handled. If unset or set to <code>preserve</code>,
+    no stripping is done. If set to <code>strip</code>, debug symbols are split. If set to <code>split</code>, debug
+    symbols are split out into files in <code>/usr/lib/debug/</code>. If set to <code>compress</code>, symbols are also
+    split out, and debug sections are compressed. Note that <code>compress</code> will only work with <code>binutils
+        &gt;=2.21.51.0.4</code>, and may cause problems with older versions of <code>gdb</code>.</dd>
 </dl>
 
 <p>Note that these special flags are <em>not</em> use flags from an ebuild perspective. They are used only by Paludis
@@ -109,10 +109,10 @@ media-sound/lame       -gtk
 dev-cpp/*              doc
 
 # We like tests, and don't want debug symbols
-*/*                    BUILD_OPTIONS: optional_tests -split strip
+*/*                    BUILD_OPTIONS: optional_tests symbols=strip
 
 # But we do want split debug symbols for a few packages
-dev-cpp/*              BUILD_OPTIONS: split strip
+dev-cpp/*              BUILD_OPTIONS: symbols=split
 
 # We want to run four jobs in parallel if possible (Exheres format packages
 # only; Gentoo EAPIs use the MAKEOPTS environment variable instead)
diff --git a/doc/faq/different.html.part b/doc/faq/different.html.part
index ef674fd7e..a339fb20e 100644
--- a/doc/faq/different.html.part
+++ b/doc/faq/different.html.part
@@ -36,14 +36,14 @@ a rather ugly way of handling things. We do have equivalents to most values:</p>
     <code>$D</code>.</dd>
 
     <dt>nostrip</dt>
-    <dd>Set the flags <code>-split -strip</code> in the BUILD_OPTIONS group in use.conf, for the packages you want it
+    <dd>Set <code>symbols=preserve</code> in the BUILD_OPTIONS group in use.conf, for the packages you want it
     to apply to.</dd>
 
     <dt>sandbox</dt>
     <dd>Always on.</dd>
 
     <dt>splitdebug</dt>
-    <dd>Set the flags <code>split strip</code> in the BUILD_OPTIONS group in use.conf, for the packages you want it to
+    <dd>Set the flags <code>symbols=split</code> in the BUILD_OPTIONS group in use.conf, for the packages you want it to
     apply to.</dd>
 
     <dt>test</dt>