Section 19.4.10 of the Handbook (2nd Edition) skips over the use of mergemaster. It details steps to use instead of mergemaster, but mergemaster instructions are not included. Fix: Add a "Using mergemaster" title and mergemaster instructions before existing instructions in 19.4.10, and show a mergemaster command line and usage instructions. De-emphasize the manual merging method section, or at least break it from the mergemaster section with a title. How-To-Repeat: See section 19.4.10.
Responsible Changed From-To: freebsd-doc->trhodes I have already written 3 paragraphs for this pr, and will submit a patch for review in a day or so. Thanks for pointing this out.
On Thu, 28 Mar 2002 15:00:05 -0800 (PST) Tom Rhodes <darklogik@pittgoth.com> wrote: > The following reply was made to PR docs/36263; it has been noted by > GNATS. GRRR I didn't want it to MIME encode... -- Tom (Darklogik) Rhodes www.FreeBSD.org -The Power To Serve www.Pittgoth.com -Pittgoth Discussion Portal trhodes@ {Pittgoth.com, FreeBSD.org}
diff -ruN handbook/cutting-edge/chapter.sgml handbook.new/cutting-edge/chapter.sgml --- handbook/cutting-edge/chapter.sgml Tue Mar 26 20:16:48 2002 +++ handbook.new/cutting-edge/chapter.sgml Thu Mar 28 17:55:43 2002 @@ -1067,11 +1067,69 @@ 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. - You should read the manual page first, and make a backup of + section</link>, since &man.mergemaster.8; is described below. + 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 &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>
State Changed From-To: open->closed I have just committed a patch which adds a mergemaster section to the handbook, thanks for pointing this out!