svn commit: r40809 - head/en_US.ISO8859-1/books/handbook/cutting-edge

[Warren Block]

Author: wblock
Date: Wed Jan 30 03:14:07 2013
New Revision: 40809
URL: http://svnweb.freebsd.org/changeset/doc/40809

Log:
  Rewrite the outdated section explaining make.conf and add a section to
  mention the existence of src.conf.  Warn users that these things,
  although shiny and strangely compelling, are also very sharp.
  
  PR:		172922

Modified:
  head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml

Modified: head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml	Wed Jan 30 00:07:33 2013	(r40808)
+++ head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml	Wed Jan 30 03:14:07 2013	(r40809)
@@ -2167,25 +2167,37 @@ Fetching 133 new ports or files... done.
 	<primary><filename>make.conf</filename></primary>
       </indexterm>
 
-      <para>Examine the files
-	<filename>/usr/share/examples/etc/make.conf</filename> and
-	<filename>/etc/make.conf</filename>.  The first contains some
-	default defines – most of which are commented out.  To
-	make use of them when you rebuild your system from source, add
-	them to <filename>/etc/make.conf</filename>.  Keep in mind
-	that anything you add to <filename>/etc/make.conf</filename>
-	is also used every time you run <command>make</command>, so it
-	is a good idea to set them to something sensible for your
-	system.</para>
-
-      <para>A typical user will probably want to copy and uncomment
-	the <makevar>NO_PROFILE</makevar> line found in
-	<filename>/usr/share/examples/etc/make.conf</filename>
-	to <filename>/etc/make.conf</filename>.</para>
-
-      <para>Examine the other definitions, like
-	<makevar>NOPORTDOCS</makevar>,
-	and decide if they are relevant to you.</para>
+      <para>&man.make.1; options are shown in &man.make.conf.5; and
+	<filename>/usr/share/examples/etc/make.conf</filename>.  These
+	settings can be added to <filename>/etc/make.conf</filename>
+	to control the way &man.make.1; runs and how it builds
+	programs.  Changes to some settings can have far-reaching and
+	potentially surprising effects.  Read the comments in both
+	locations and keep in mind that the defaults have been chosen
+	for a combination of performance and safety.</para>
+
+      <para>Options set in <filename>/etc/make.conf</filename> take
+	effect every time &man.make.1; is used, including compiling
+	applications from the Ports Collection or user-written C
+	programs, or building the &os; operating system itself.</para>
+    </sect2>
+
+    <sect2 id="src-conf">
+      <title>Check <filename>/etc/src.conf</filename></title>
+
+      <indexterm>
+	<primary><filename>src.conf</filename></primary>
+      </indexterm>
+
+      <para><filename>/etc/src.conf</filename> controls the building
+	of the operating system from source code.  Unlike
+	<filename>/etc/make.conf</filename>, the contents of
+	<filename>/etc/src.conf</filename> only take effect when the
+	&os; operating system itself is being built.  Descriptions of
+	the many options available for this file are shown in
+	&man.src.conf.5;.  Be cautious about disabling seemingly
+	unneeded kernel modules and build options.  Sometimes there
+	are unexpected or subtle interactions.</para>
     </sect2>
 
     <sect2 id="updating-etc">