# HG changeset patch
# User Nicholas R. Jankowski <jankowskin@asme.org>
# Date 1619120305 14400
#      Thu Apr 22 15:38:25 2021 -0400
# Node ID 5c8a0a7fda9dab48631db65b22e0a798746600fd
# Parent  8dd0fca2a3d9ec0848910139ce77234a472e331a
Updated pkg documentation related to local/global install (bug #59821).

* scripts/pkg/pkg.m: clarifies global/local selection, limitations of pkg update.
* doc/interpreter/package.txi: added website URL, note on warnings.

diff -r 8dd0fca2a3d9 -r 5c8a0a7fda9d doc/interpreter/package.txi
--- a/doc/interpreter/package.txi	Thu Apr 22 12:52:14 2021 -0400
+++ b/doc/interpreter/package.txi	Thu Apr 22 15:38:25 2021 -0400
@@ -26,8 +26,9 @@
 installed in Octave.  At the time of writing the `Octave Forge' project
 can be found online at @url{https://octave.sourceforge.io}, but
 since the Internet is an ever-changing place this may not be true at
-the time of reading.  Therefore it is recommended to see the Octave
-website for an updated reference.
+the time of reading.  Therefore it is recommended to see
+@url{https://octave.org, the Octave website}for an
+updated reference.
 
 @menu
 * Installing and Removing Packages::
@@ -49,7 +50,7 @@
 
 @noindent
 If the package is installed successfully nothing will be printed on
-the prompt, but if an error occurred during installation it will be
+the prompt, but if a warning or error occurred during installation it will be
 reported.  It is possible to install several packages at once by
 writing several package files after the @code{pkg install} command.
 If a different version of the package is already installed it will
@@ -83,7 +84,7 @@
 
 @noindent
 If the package is removed successfully nothing will be printed in the
-prompt, but if an error occurred it will be reported.  It should be
+prompt, but if a warning or error occurred it will be reported.  It should be
 noted that the package file used for installation is not needed for
 removal, and that only the package name as reported by @code{pkg list}
 should be used when removing a package.  It is possible to remove
diff -r 8dd0fca2a3d9 -r 5c8a0a7fda9d scripts/pkg/pkg.m
--- a/scripts/pkg/pkg.m	Thu Apr 22 12:52:14 2021 -0400
+++ b/scripts/pkg/pkg.m	Thu Apr 22 15:38:25 2021 -0400
@@ -35,13 +35,17 @@
 ## Global packages are installed by default in a system-wide location.  This is
 ## usually a subdirectory of the folder where Octave itself is installed.
 ## Therefore, Octave needs write access to this folder to install global
-## packages.  That usually means that Octave has to run with root access (or
-## "Run as administrator" on Windows) to be able to install packages globally.
+## packages, which is usually only available when Octave is run with 
+## administrative rights.  That means to install packages globally Octave checks if 
+## it is executing as root (superuser) on Unix-like systems, or it is running
+## with elevated privileges ("Run as administrator") on Windows.
 ##
 ## In contrast, local packages are installed by default in the user's
-## home directory (profile on Windows) and are only available to that specific
-## user.  Usually, they can be installed without root access (or administrative
-## privileges).
+## home directory (or user profile on Windows) and are only available to that
+## specific user.  Usually, they can be installed without administrative rights.
+## If Octave does not detect that it is running with administrative rights, it
+## defaults to local package installation even if the local user has write
+## access to the global package location.
 ##
 ## For global and local packages, there are separate databases holding the
 ## information about the installed packages.  If some package is installed
@@ -49,8 +53,8 @@
 ## ("shadows") the global one.  Which package installation (global or local) is
 ## used can also be manipulated by using prefixes and/or using the
 ## @samp{local_list} input argument.  Using these mechanisms, several different
-## releases of one and the same package can be installed side by side as well
-## (but cannot be loaded simultaneously).
+## releases of the same package can be installed side by side as well (but
+## cannot be loaded simultaneously).
 ##
 ## Packages might depend on external software and/or other packages.  To be
 ## able to install such packages, these dependencies should be installed
@@ -128,11 +132,11 @@
 ##
 ## @item -local
 ## A local installation (package available only to current user) is forced,
-## even if the user has system privileges.
+## even if the user has administrative rights.
 ##
 ## @item -global
 ## A global installation (package available to all users) is forced, even if
-## the user doesn't normally have system privileges.
+## the user doesn't normally have administrative rights.
 ##
 ## @item -forge
 ## Install a package directly from the Octave Forge repository.  This
@@ -151,8 +155,9 @@
 ##
 ## @item update
 ## Check installed Octave Forge packages against repository and update any
-## outdated items.  This requires an internet connection and the cURL library.
-## Usage:
+## outdated items.  Updated packages are installed either globally or locally
+## depending on whether elevated privileges are detected.  This requires an
+## internet connection and the cURL library.  Usage:
 ##
 ## @example
 ## pkg update
@@ -160,6 +165,12 @@
 ##
 ## @noindent
 ## To update a single package use @code{pkg install -forge}
+## 
+## @noindent
+## Updates for multiple packages are sorted alphabetically and not checked for
+## dependencies affected by installation order.  If dependency order related
+## @code{pkg update} failures occur, use @code{pkg install -forge} to update
+## packages individually.
 ##
 ## @item uninstall
 ## Uninstall named packages.  For example,
