PORTSUPDATING -is it too terse for users to be useful?

[Vizion]

> -----Original Message-----
> From: owner-freebsd-ports at freebsd.org 
> [mailto:owner-freebsd-ports at freebsd.org] On Behalf Of Vizion
> Sent: Saturday, March 03, 2007 2:39 PM
> To: ports at freebsd.org
> Subject: PORTSUPDATING -is it too terse for users to be useful?
> 
> Hi
> 
> Sorry to say I find this extract in PORTSUPDATING a bit too 
> terse. I wonder if there could be some elaboration on the 
> advice given in PORTSUPDATING for those who do not understand 
> the implications. IMHO it is not very helpful to have an 
> absense of procedural detail in such a critical file.
> See illustrative questions below--
> 
> 20070301:
>   AFFECTS: users of ports-mgmt/portupgrade*
>   AUTHOR: sem at FreeBSD.org
> 
>   Because of a bug in previous version, it's recomended you 
> fill ALT_PKGDEP
> QUESTION: OK what is this.. what does it do?
>   section in pkgtools.conf file for portupgrade be aware of 
> alternative
>   dependencies you use,
>  
> QUESTION: OK what is an alternative dependency? What 
> procedure do we follow to find out which ones we use?
> 
> and run pkgdb -L to restore dependencies that was
>   lost.
> 
>   Example of ALT_PKGDEP section:
>   ALT_PKGDEP = {
>     'www/apache13' => 'www/apache13-modssl',
>     'print/ghostscript-afpl' => 'print/ghostscript-gnu',
>   }
> QUESTION: Example is fine.. but what is a suffix? How do we 
> identify the ones we need/use?
>   Note also, portupgrade knows nothing how to handle ports 
> with different
>   suffixes (E.g. -nox11). So you should define explicitly variables 
>   (E.g. WITHOUT_X11=yes) for the ports in /etc/make.conf or 
> pkgtools.conf
>   (MAKE_ARGS section) files.
>
I forgot to say:
1. I only took this one as an example of a general principle. In fact this entry is better than many others because it contains examples. I am wondering if, as a matter of course, references might be included to sources of more detailed information that would help those who might not be familiar with the terms used in a particular entry.