docs/74231: Conflicting information on mergemaster -p

[Brian Candler]

>Number:         74231
>Category:       docs
>Synopsis:       Conflicting information on mergemaster -p
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Mon Nov 22 10:20:22 GMT 2004
>Closed-Date:
>Last-Modified:
>Originator:     Brian Candler
>Release:        FreeBSD 5.3-STABLE i386
>Organization:
>Environment:
System: FreeBSD billdog.local.linnet.org 5.3-STABLE FreeBSD 5.3-STABLE #3: Thu Nov 18 15:49:59 GMT 2004 root at billdog.local.linnet.org:/usr/src/sys/i386/compile/BILLDOG i386


>Description:

The handbook gives inconsistent information about where 'mergemaster -p'
fits into the build/upgrade process.
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/makeworld.html

In section 19.4.1 its advice is the same as I find in /usr/src/Makefile:

# For individuals wanting to upgrade their sources (even if only a
# delta of a few days):
#
# 1.  `cd /usr/src'       (or to the directory containing your source tree).
# 2.  `make buildworld'
# 3.  `make buildkernel KERNCONF=YOUR_KERNEL_HERE'     (default is GENERIC).
# 4.  `make installkernel KERNCONF=YOUR_KERNEL_HERE'   (default is GENERIC).
# 5.  `reboot'        (in single user mode: boot -s from the loader prompt).
# 6.  `mergemaster -p'
# 7.  `make installworld'
# 8.  `mergemaster'
# 9.  `reboot'
#
# See src/UPDATING `COMMON ITEMS' for more complete information.

However in section 19.4.4 it says that mergemaster -p should be done earlier
in the process; and section 19.4.10 doesn't suggest doing mergemaster -p
there, which would be consistent with the initial advice.

19.4.4 describes the -p flag as "pre-buildworld". 'man mergemaster' says the
same, and also says it "compares only files known to be essential to the
success of {build|install}world". That implies it may need to be done before
make buildworld, as well or instead of before make installworld.

>How-To-Repeat:
	
>Fix:

Make it clear where mergemaster -p should be done in the entire process:
is it ever required before buildworld, or only before installworld?

>Release-Note:
>Audit-Trail:
>Unformatted: