# HG changeset patch
# User Nicholas R. Jankowski <jankowskin@asme.org>
# Date 1618422034 14400
#      Wed Apr 14 13:40:34 2021 -0400
# Node ID 152e67c3e53f8fc2d04d82c6cafb633f2da85a71
# Parent  41d53e20389ed5f80eee5578596b6b29f01c37de
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 41d53e20389e -r 152e67c3e53f doc/interpreter/package.txi
--- a/doc/interpreter/package.txi	Wed Apr 14 18:30:56 2021 +0200
+++ b/doc/interpreter/package.txi	Wed Apr 14 13:40:34 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://www.gnu.org/software/octave/index, 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 41d53e20389e -r 152e67c3e53f scripts/pkg/pkg.m
--- a/scripts/pkg/pkg.m	Wed Apr 14 18:30:56 2021 +0200
+++ b/scripts/pkg/pkg.m	Wed Apr 14 13:40:34 2021 -0400
@@ -35,13 +35,16 @@
 ## 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
+## packages, which is usually only available when Octave is run with elevated
+## privleges.  Because of this Octave checks if it has root access (or was
 ## "Run as administrator" on Windows) to be able to install packages globally.
 ##
 ## 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 (user profile on Windows) and are only available to that
+## specific user.  Usually, they can be installed without root access (or
+## administrative privileges).  If Octave does not detect that it is running with
+## elevated privleges, 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
@@ -151,8 +154,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 packgaes are installed either globally or locally
+## depending on whether elevated privliges are detected.  This requires an
+## internet connection and the cURL library.  Usage:
 ##
 ## @example
 ## pkg update
@@ -160,6 +164,12 @@
 ##
 ## @noindent
 ## To update a single package use @code{pkg install -forge}
+## 
+## @noindent
+## Updates for multiple packgaes 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
+## packgaes individually.
 ##
 ## @item uninstall
 ## Uninstall named packages.  For example,
