docs/140008: many papercut omissions on portupgrade man page

[Allan Stokes]

>Number:         140008
>Category:       docs
>Synopsis:       many papercut omissions on portupgrade man page
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Tue Oct 27 04:10:01 UTC 2009
>Closed-Date:
>Last-Modified:
>Originator:     Allan Stokes
>Release:        6.4 installed; 7.2 man page online
>Organization:
>Environment:
NA
>Description:
I seem to be upgrading everything this week: OpenBSD, FreeBSD, Ubuntu, Snow Leopard, Resident Evil.  The point here is that FreeBSD is not getting 100% of my focus, and I wish the portupgrade man page was being more considerate of my scattered attention.  

I really like the Ubuntu concept of a papercut bug: bugs that affect new users or casual users out of proportion to the effort of fixing them, which I think is the case here, if we consider the role of a seagull sysadmin.  

I'll take this in reading order, rather than by importance.  

>How-To-Repeat:
Leave network unattended for over a year.  Allocate a few days to upgrade everything all at once. 

>Fix:
Other suggestions

In the options that mention "make clean" or "make distclean" add "See ports(7)." 

Make it more clear in which phase "make config" is run and how to avoid dialog(1) from grinding things to a halt.  

In my 6.4 version of ports(7) I see documentation for BATCH and INTERACTIVE.  This doesn't appear to be the same "interactive" as portupgrade.  Is the INTERACTIVE mode of ports available from portupgrade?  

And why doesn't ports have an option to "just do it the same as if I loaded the binary package?"  I don't see one.  I don't get why the binary packages can perform default build steps where ports can not.  From a multitasking perspective, I'd rather have the default build complete in background and only pay if I decide to change it later.  

My original preference was binary packages, but they weren't available for my aging installation.  

Compiling these suggestions took about 20 times more focus than I had last night, when all I wanted to do was quickly get the wheels turning on a potentially long running job. 


>Release-Note:
>Audit-Trail:
>Unformatted:
 >> Do not be lazy about backing up your precious data and configuration
 >> files, including the package database in ``/var/db/pkg''.
 
 So give me the full list, and I'll whip up a script; no list == no time just now.
 
 >> --batch  
 >> Run an upgrading process in a batch mode (with BATCH=yes).
 
 I imagine that somewhere in the pkgtools BATCH=yes is documented.  (Later: no it's documented in ports(7)).  Does this allow me to run a large package upgrade without those screen prompts?  Throw me a bone here.  (Later: ports(7) says this restricts the  ports to those not requiring interaction [and recursive implications?], which is not what I would have guessed.)  
 
 >> --F 
 >> --fetchonly 
 
 Despite good efforts to document -R elsewhere, it's left out where the harried admin most needs to find it.  
 
 >> --interactive 
 
 There's a strange trailing Pp in the associated text.  Does not mention -y or -n.  Do these go together with --interactive?  If you read the fine print, cross referencing all three entries, the answer is clear.  
 
 >> --keep-going
 >> Force the upgrade of a package even if some of the
 >> requisite packages have failed to upgrade in advance.
 
 Does it have an effect in --fetchonly mode?  Nothing changes in -P mode or -PP mode?  Does it influence --noexecute?  
 
 From 6.4 installation: 
 >> --config
 >> Run ``make config-conditional'' before everything
 >> for all tasks.  -w option below.
 
 Apparently removed in 7.2.  Good.  I had no clue what it meant.  Was it some variant on BATCH mode?  
 
 >> -l FILE
 >> --results-file FILE    
 >> Specify a file name to save the results to.  
 >> By default, portupgrade does not save results as a file.
 
 And what will this file contain?  All I got under 6.4 was a single line per package error, of the following form.  
 
 ! security/sudo (sudo-1.6.9.12)	(clean error)
 
 I was looking for some way to track progress as it grinds through 120 packages so I could manage around other activities.  I was able to check timestamps on files in /var/db/pkg last night, but today after my portsnap upgrade, all the time stamps are ide ntical, even though I've had portupgrade running for hours now. 
 
 >> --log-file FORMAT	    
 >> Specify a printf(3) style format to determine the
 >> log file name for each port.
 
 Again a little light on the expected contents.  Same as what I see on the console?  My harried interpretation was that -l was going to give me a concatenated --log-file  I didn't properly interpret the undefined term "results".  
 
 >> --package
 >> Build a package when each specified port is
 >> installed or upgraded.  
 
 Build a package where?  Does this mean the install occurs from the built package instead of the default method?  Does that change anything?  What happens if a package file by the same name already exists?  
 
 Suggest adding "See PACKAGE in the ENVIRONMENT section." 
 
 >> -s
 >> --sudo
 >> Run commands under sudo(8) where needed.
 
 Does this interfere with starting portupgrade in background?  I realize ^Z doesn't work.  Does "commands" include all necessary access to /var/db tree?  
 
 If there are no drawbacks to this, why not add under DESCRIPTION: "If you have sudo configured (you should), it's recommended to run portupgrade as a regular user with the -s option".  Web documentation shows portupgrade running at the # prompt, so I ass umed that was best practice. 
 
 Under --batch, you might add "If you are running a large update, and your sudo credentials time out, you might want to run portupgrade under sudo or from the root prompt instead of using -s."  If batch has unattended semantics (which I haven't figured ou t yet).  
 
 >> --yes 
 >> Answer yes to all the questions.  This option 
 >> implies -v and negates -n.
   
 *The* questions?  You mean not the harassment configuration screens asking about LDAP and such like?  The go/no-go questions about final installation, which I infer after cross-referencing back to -n and its long form --no-execute?  
 
 Kudos for the TECHNICAL DETAILS section.  But it's not a good resource for the harried admin trying to get wheels turning while heavily multitasking.  
 
 The mode I was looking for is this: do everything possible as if I was downloading pre-built binary packages and don't stop until there's nothing left to be done that can't be done without my attention.  
 
 Then give me a nice summary of all the defaults I've accepted, in case I later wish to assert a preference, when I have the brain space to do so.