PR: docs/36263

Reviewed by:	jim

en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml

@@ -1067,11 +1067,69 @@ Script done, &hellip;</screen>
         if you would prefer to do that.  We strongly recommend you
         use &man.mergemaster.8;, however, and if you do then you
         can skip forward to the <link linkend="update-dev">next
-        section</link>, since &man.mergemaster.8; is very simple to use.
+        section</link>, since &man.mergemaster.8; is described below.
-        You should read the manual page first, and make a backup of
+        Be sure to make a backup of
         <filename>/etc</filename> in case anything goes wrong.</para>
 
-      <para>If you wish to do the update manually,
+      <para>The &man.mergemaster.8; utility is a Bourne script that will
+        aid you in determining the differences between your configuration files
+        in <filename>/etc</filename>, and the configuration files in
+        the source tree <filename>/usr/src/etc</filename>. This is
+        the recommended solution for keeping the system configuration files up to date
+        with ones located in the source tree.</para>
+
+      <para><command>mergemaster</command> was integrated into the FreeBSD base
+        system between 3.3-RELEASE and 3.4-RELEASE, which means it is
+        present in all -STABLE and -CURRENT systems since 3.3.</para>
+
+      <para>To begin simply type <command>mergemaster</command> at your prompt, and
+        watch it start going.  <command>mergemaster</command> will then build a
+        temporary root environment, from <filename>/</filename> down, and then populate
+        it with various system configuration files.  Those files are then compared
+        to the ones currently installed in your system.  At this point, files that
+        differ will be shown in &man.diff.1; format, with the <option>+</option> sign
+        representing added or modified lines, and <option>-</option> representing
+        lines that will be removed either completely, or replaced with a new line.
+        See the &man.diff.1; manual page for more information about the &man.diff.1;
+        syntax and how file differences are shown.</para>
+
+      <para>&man.mergemaster.8; will then show you each file that displays variances,
+        and at this point you will have the option of either deleting the new file (referred
+        to as the temporary file), install the temporary file in its unmodified state,
+        merge the temporary file with the currently installed file, or view the
+        &man.diff.1; results again.</para>
+
+      <para>Choosing to delete the temporary will tell &man.mergemaster.8; that we
+        wish to keep our current file unchanged, and to delete the one that is
+        new.  This option is not the most recommended one, unless you see no
+        reason to change the current file.  You can get help at any time by
+        typing <option>?</option> at the mergemaster prompt.  If the user should
+        choose to skip a file, it will be presented again after all other files
+        have been worked with.</para>
+
+      <para>Choosing to install the unmodified temporary file will replace the
+        current file with the new one.  For most unmodified files, this is the best
+        option.</para>
+
+      <para>Choosing to merge the file will present you with a text editor,
+        and the contents of both files.  You can now merge them by
+        reviewing both files side by side on the screen, and choosing parts from
+        both to create a finished product.  When the files are compared side by side,
+        the <option>l</option> key will select the left contents and the
+        <option>r</option> key will select contents from your right.
+        The final output will be a file consisting of both parts, which can then be
+        installed.  This is usual option for files where settings have been
+        modified by the user.</para>
+
+      <para>Choosing to view the diff results again, will show you the file differences
+        just like &man.mergemaster.8; did before prompting you for an option.</para>
+
+      <para>After &man.mergemaster.8; is complete with the system files you will be
+        prompted for other options.  &man.mergemaster.8; will ask if you want to rebuild
+        the password file, run <filename>MAKEDEV</filename> and finishing up with a
+        removal of the left over temporary files.</para>
+
+      <para>If you wish to do the update manually, however,
         you cannot just copy over the files from
 	<filename>/usr/src/etc</filename> to <filename>/etc</filename> and
 	have it work.  Some of these files must be <quote>installed</quote>