Trac sagemath#34593: Document and manage temporary directories

This is a followup to sagemath#33213. Some users prefer (or need) to control
where temporary files are created, and we should document this:

- as described at
https://docs.python.org/3/library/tempfile.html#tempfile.gettempdir,
users can set the environment variable `TMPDIR`

Possible follow-up:
- Also, according to
https://manpages.ubuntu.com/manpages/bionic/man8/tmpreaper.8.html, at
least on some systems it would be helpful to create a non-writable file
`.tmpreaper` in the directory to prevent the system from doing automatic
cleanup on it.

URL: https://trac.sagemath.org/34593
Reported by: jhpalmieri
Ticket author(s): John Palmieri
Reviewer(s): Matthias Koeppe

src/doc/en/installation/launching.rst

@@ -29,6 +29,36 @@ To start a Jupyter Notebook instead of a Sage console, run the command
 instead of just ``sage``. To quit the Jupyter Notebook press ``<Ctrl> + <c>``
 twice in the console where you launched the command.
 
+Environment variables
+---------------------
+
+Sage uses the following environment variables when it runs:
+
+- :envvar:`DOT_SAGE` - this is the directory, to which the user has read and
+  write access, where Sage stores a number of files.
+  The default location is :file:`$HOME/.sage/`.
+
+- :envvar:`SAGE_STARTUP_FILE` - a file including commands to be executed every
+  time Sage starts.
+  The default value is :file:`$DOT_SAGE/init.sage`.
+
+- :envvar:`BROWSER` - on most platforms, Sage will detect the command to
+  run a web browser, but if this doesn't seem to work on your machine, set this
+  variable to the appropriate command.
+
+- :envvar:`TMPDIR` - this variable is used by Python, and hence by
+  Sage; it gives the directory in which temporary files should be
+  stored. This includes files used by the notebook. Some browsers have
+  security settings which restrict the locations of files that they
+  will access, and users may need to set this variable to handle this
+  situation.
+
+- See
+  https://docs.python.org/3/using/cmdline.html#environment-variables
+  for more variables used by Python (not an exhaustive list). With
+  Python 3.11 or later, a brief summary can also be obtained by
+  running `python3 --help-env`.
+
 Using a Jupyter Notebook remotely
 ---------------------------------
 

src/doc/en/installation/source.rst

@@ -1086,20 +1086,6 @@ Some standard environment variables which are used by Sage:
 - :envvar:`OPENBLAS_CONFIGURE` - adds additional configuration flags for
   the OpenBLAS package that gets added to the make command. (see :trac:`23272`)
 
-Sage uses the following environment variables when it runs:
-
-- :envvar:`DOT_SAGE` - this is the directory, to which the user has read and
-  write access, where Sage stores a number of files.
-  The default location is :file:`$HOME/.sage/`.
-
-- :envvar:`SAGE_STARTUP_FILE` - a file including commands to be executed every
-  time Sage starts.
-  The default value is :file:`$DOT_SAGE/init.sage`.
-
-- :envvar:`BROWSER` - on most platforms, Sage will detect the command to
-  run a web browser, but if this doesn't seem to work on your machine, set this
-  variable to the appropriate command.
-
 Variables dealing with doctesting:
 
 - :envvar:`SAGE_TIMEOUT` - used for Sage's doctesting: the number of seconds