handbook/cutting-edge: Recommend etcupdate(8)

Since etcupdate(8) has lived in base since 10.0 and seen plenty of use
by both committers and contributors, it's time to recommend using it.

Reviewed by:	jhb (prior version)
Differential Revision:	https://reviews.freebsd.org/D27848

documentation/content/en/books/handbook/cutting-edge/_index.adoc

@@ -617,9 +617,10 @@ check /usr/src/UPDATING  <.>
 # make -j4 buildworld  <.>
 # make -j4 kernel      <.>
 # shutdown -r now      <.>
+# etcupdate -p         <.>
 # cd /usr/src          <.>
 # make installworld    <.>
-# mergemaster -Ui      <.>
+# etcupdate -B         <.>
 # shutdown -r now      <.>
 ....
 
@@ -635,6 +636,8 @@ check /usr/src/UPDATING  <.>
 
 <.> Reboot the system to the new kernel.
 
+<.> Update and merge configuraton files in [.filename]#/etc/# required before installworld.
+
 <.> Go to the source directory.
 
 <.> Install the world.
@@ -863,11 +866,54 @@ If a custom kernel was built, `KERNCONF` must also be set to use the new custom
 A few final tasks complete the update.
 Any modified configuration files are merged with the new versions, outdated libraries are located and removed, then the system is restarted.
 
+[[updating-src-completing-merge-etcupdate]]
+==== Merging Configuration Files with man:etcupdate[8]
+
+man:etcupdate[8] is a tool for managing updates to files that are not updated as part of an installworld such as files located in [.filename]#/etc/#.
+It manages updates by doing a three-way merge of changes made to these files against the local versions.
+It is also designed to minimize the amount of user intervention, in contrast to man:mergemaster[8]'s interactive prompts.
+
+[NOTE]
+====
+In general, man:etcupdate[8] does not need any specific arguments for its job.
+There is however a handy in between command for sanity checking what will be done the first time man:etcupdate[8] is used:
+
+[source,shell]
+....
+# etcupdate diff
+....
+
+This command allows the user to audit configuration changes.
+====
+
+If man:etcupdate[8] is not able to merge a file automatically, the merge conflicts can be resolved with manual interaction by issuing:
+
+[source,shell]
+....
+# etcupdate resolve
+....
+
+[WARNING]
+====
+When switching from man:mergemaster[8] to man:etcupdate[8], the first run might merge changes incorrectly generating spurious conflicts.
+To prevent this, perform the following steps *before* updating sources and building the new world:
+
+[source,shell]
+....
+# etcupdate bootstrap <.>
+# etcupdate diff <.>
+....
+
+<.> Bootstrap the database of stock [.filename]#/etc# files, for more information see man:etcupdate[8].
+
+<.> Check the diff after bootstrapping. Trim any local changes that are no longer needed to reduce the chance of conflicts in future updates.
+====
+
 [[updating-src-completing-merge-mergemaster]]
 ==== Merging Configuration Files with man:mergemaster[8]
 
-man:mergemaster[8] provides an easy way to merge changes that have been made to system configuration files with new versions of those files.
+man:mergemaster[8] provides a way to merge changes that have been made to system configuration files with new versions of those files.
-
+man:mergemaster[8] is an alternative to the preferred man:etcupdate[8]
 With `-Ui`, man:mergemaster[8] automatically updates files that have not been user-modified and installs new files that are not already present:
 
 [source,shell]