# HG changeset patch
# User Nicholas R. Jankowski <jankowskin@asme.org>
# Date 1620753998 14400
#      Tue May 11 13:26:38 2021 -0400
# Node ID 7e02d8867b6aacb797d107ba0f4b430609a3bc36
# Parent  3e8bc8bee8e9a41d17bb9441aefcee92bc7e1ac4
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 3e8bc8bee8e9 -r 7e02d8867b6a doc/interpreter/package.txi
--- a/doc/interpreter/package.txi	Mon May 10 23:27:38 2021 +0200
+++ b/doc/interpreter/package.txi	Tue May 11 13:26:38 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 3e8bc8bee8e9 -r 7e02d8867b6a scripts/pkg/pkg.m
--- a/scripts/pkg/pkg.m	Mon May 10 23:27:38 2021 +0200
+++ b/scripts/pkg/pkg.m	Tue May 11 13:26:38 2021 -0400
@@ -35,13 +35,20 @@
 ## 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
+## administrator privileges, such as when run as root (or superuser) on
+## Unix-like systems, or run 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
+## privileges.
+##
+## Every time @code{pkg} is run Octave checks to see whether or not it has
+## administrator privileges and sets the default install location to the
+## global or local location accordingly.  Options when running @code{pkg} can
+## changed this location as described below.
 ##
 ## For global and local packages, there are separate databases holding the
 ## information about the installed packages.  If some package is installed
@@ -49,8 +56,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 +135,11 @@
 ##
 ## @item -local
 ## A local installation (package available only to current user) is forced,
-## even if the user has system privileges.
+## even if Octave is being run with administrative privileges.
 ##
 ## @item -global
 ## A global installation (package available to all users) is forced, even if
-## the user doesn't normally have system privileges.
+## Octave is not being run with administrative privileges.
 ##
 ## @item -forge
 ## Install a package directly from the Octave Forge repository.  This
@@ -151,8 +158,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 +168,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,
