document new features; installing external packages; link to GH announcements page

Author: briantoby

MDhelp/docs/mainmenu.md

@@ -68,13 +68,16 @@ Finally, move to the atoms tab where atoms can be inserted or imported. Note tha
     !!! Note
         Note that for atom positions, the variables associated with coordinate values (named as `p::Aw:n`, where p is the phase number, n is the atom number and w is x, y or z) is not a refinable parameter, but the shift in the value is. The refined parameters are 'p::dAw:n'. The reason this is done is that by treating an atom position as (Ax+dAx,Ay+dAy,Az+dAz) where the “d” values indicate shifts from the starting position. Shifts are refined rather than the x, y, or z values as this this simplifies symmetry constraints. As an example, suppose we have an atom on a symmetry constrained site, `x,1/2-x,z`. The process needed to enforce this symmetry constraint, so that if x moves positively y has to move negatively by the same amount would be messy. With refinement of shifts, all we need to do is constrain the dAy to be equal to the negative of dAx (`0::dAy:n = -1 * 0::dAx:n` ).
 
+    <a name="ParmLogging"></a>
     Also, one can set here parameters that will be logged into the [Notebook](./commontreeitems.md#Notebook), so the values can be tracked and plotted across a refinement. Right-click to toggle the log setting. Note that individual log settings will override the the `LogAllVars` preference setting (see  [Configuration variables](./others.md#config)).
 
 * **Refine (Sequential refine)** - This performs the refinement (Pawley/Rietveld/LeBail or single crystal) fit according to the controls set in the Controls data tree item. This menu item name will be "Refine" unless the datasets to be used in a sequential refinement have been selected in the [Controls data tree](./commontreeitems.md#Controls) item, at which point the name will appear as "Sequential refine".
 
     When a PWDR histogram item is selected in the data tree, or a child tree item of a PDWR histogram is selected in the tree when Refine is used, the plot of that histogram will be updated after each cycle of refinement.
 
-    Once the refinement is completed, you will be offered the chance to load the results of the fit or to reject the fit,in which case no parameters will be changed, so it is possible to change settings or refinement flags and try different options. After the refinement results are reloaded, plots will be updated to reflect the new refinement values if the plot has a defined update process or will be closed as the plot contents are presumed to be obsolete and need to be manually recreated to be valid.
+    Once the refinement is completed, you will be offered the chance to load the results of the fit or to reject them, in which case no parameters will be changed. If the fit is rejected, it is possible to change settings or refinement flags and try a different set of options and try again. The dialog asking to load or Cancel the last refinement will show a table of parameters and how they changed in the refinement. Clicking on a parameter will show a plot of how the latest value follows the previous results, if that parameter is being [logged in the Notebook](#ParmLogging).
+    
+    After the refinement results are reloaded, each plot will be updated to reflect the new refinement values, if the plot has a defined update process or will be closed as the plot contents are presumed to be obsolete and need to be manually recreated to be valid.
 
 * **Compute partials** - 
 The term "phase partial intensities" is used to designate keeping separate track of the intensity contribution from each phase separately. When this is used, a zero-cycle refinement (meaning no parameters values are changed) where the contributions from each phase (phase partial intensities) are written for each histogram and each phase in that histogram into a single file named &lt;project&gt;`.partials` where &lt;project&gt; is the GSAS-II project (.gpx) name. This file is intended for internal use in GSAS-II and will be deleted if additional refinements are performed (as the information in them is then obsolete; use this menu command to recreate them if needed.) When the .partials file is created, the user can then choose to export the intensity information in a series of ASCII files named &lt;project&gt;_part_N.csv, which can be read by spreadsheets and most scientific software.

MDhelp/docs/others.md

@@ -19,7 +19,7 @@ GSAS-II provides a number of configuration settings that can be changed via vari
 <a name="RTFM"></a>
 ## Programmers' documentation
 
- The routines and classes used within GSAS-II are documented in a set of web pages and in a PDF document. This documentation is created from the Python source code files using Sphinx. 
+ The routines and classes used within GSAS-II are documented in a set of [web pages]((https://gsas-ii.readthedocs.io/en/latest) and in a [PDF document](https://gsas-ii.readthedocs.io/_/downloads/en/latest/pdf/) with >400 pages. This documentation is created from the Python source code files using Sphinx. There is also an [abbreviated form of the documentation](https://gsas-ii-scripting.readthedocs.io/en/latest/) intended for people developing scripting applications only, or [as a PDF](https://gsas-ii-scripting.readthedocs.io/_/downloads/en/latest/pdf/).
 
 <a name="Origin_1"></a>
 <a name="_Origin_1"></a>

webdocs/documentation.rst

@@ -72,6 +72,26 @@ an electronic book `(Scripting Manual as e-book
 <https://gsas-ii-scripting.readthedocs.io/_/downloads/en/latest/epub/>`_,  Epub
 format). 
 
+News
+----------------------------
+GSAS-II is not a "finished product" in that we are constantly 
+correcting bugs, adding new features and improving the science.
+(Alas, sometimes
+creating new bugs in that process.) At the same time, the computing
+environment that GSAS-II runs in also changes, so code that runs fine
+now may not run in a new version of an operating system or when Python
+or a Python package is updated, so even standing still sometimes requires code
+changes.
+
+News on changes to GSAS-II, new features, etc. is
+placed in the
+`Announcements section of the GitHub Discussion
+pages <https://github.com/AdvancedPhotonSource/GSAS-II/discussions/categories/announcements>`_.
+This will be useful reading for people who work with GSAS-II frequently. 
+One can also track the minutiae of changes made to GSAS-II from
+`GitHub's log of commits <https://github.com/AdvancedPhotonSource/GSAS-II/commits/main/>`_,
+but since many commits may be used for a single bug-fix or new
+feature, this can be hard to follow. 
 
 Crystallography/Powder Diffraction Intro
 -----------------------------------------------

webdocs/install-external.rst

@@ -19,11 +19,14 @@ There are several publicly-available programs where GSAS-II provides an interfac
       * the ``GSASII`` directory where GSAS-II has been installed
         (this will be where the GSAS-II Python files are found).
 
-    For Windows the home directory, ``~``, is usually
-    taken from the USERPROFILE setting or a combination of HOMEPATH
-    and HOMEDRIVE, so these directories will usually have form 
-    ``C:\Users\``*YourUsername* or
-    ``C:\Users\``*YourUsername*``\.GSASII``. 
+    .. tip::
+   
+      For Windows the user's home directory, ``~``, is usually
+      taken from the USERPROFILE setting or a combination of HOMEPATH
+      and HOMEDRIVE, so these directories will usually have form 
+      ``C:\Users\<YourUsername>`` or
+      ``C:\Users\<YourUsername>\.GSASII``.  (Replace ``<YourUsername>``
+      with the directory name on your computer.)
 
 **RMCProfile**
 ======================
@@ -35,19 +38,55 @@ There are several publicly-available programs where GSAS-II provides an interfac
     http://rmcprofile.org/Downloads or
     https://rmcprofile.pages.ornl.gov/nav_pages/download/
 
+    For Mac and Linux systems, one has some flexibility on where one
+    installs RMCProfile, on MacOS the only install location for
+    RMCprofile where the software is configured to run is the system
+    Applications directory. 
+    First, the `configuration
+    variable <https://advancedphotonsource.github.io/GSAS-II-tutorials/help/others.html#config>`_
+    ``rmcprofile_exec``,
+    if defined, is checked as a location for the RMCprofile
+    program. If that does not locate the program, On Windows and
+    Linux, the location of the GSAS-II Python files, the location of
+    the GSAS-II binaries, the current working directory (where the
+    GSAS-II .gpx file is located) and the location where Python is
+    installed, as well as the entire system path is searched for  ``rmcprofile`` or
+    ``rmcprofile.exe``. On MacOS, the only location where the 
+    ``rmcprofile`` executable can be found is
+    ``/Applications/RMCProfile.app/Contents/MacOS/exe``.
+
+    See routine ``GSASIIpwd.findrmcprofile()`` for details on finding the
+    RMCprofile program.
+
 **fullrmc**
 ======================
 
-    A modern software framework for large-box PDF & S(Q) fitting. Note
+    The fullrmc program is a modern software framework for large-box
+    PDF & S(Q) fitting. Note 
     that the GSAS-II implementation is not compatible with the last
     open-source version of fullrmc, but rather the version 5.0 must be
     used, which is distributed only as compiled versions and only for 64-bit
     Intel-compatible processors running Windows, Linux and
     MacOS. Download this as a single executable from website
     https://github.com/bachiraoun/fullrmc/tree/master/standalones. GSAS-II
-    will offer to install this software into the binary directory when the fullrmc
-    option is selected on the Phase/RMC tab.
+    will offer to download and install this software into the GSAS-II
+    binary directory when the fullrmc option is selected on the Phase/RMC tab. 
+
+    The `configuration
+    variable <https://advancedphotonsource.github.io/GSAS-II-tutorials/help/others.html#config>`_
+    ``fullrmc_exec``,
+    if defined, is checked as a location for the fullrmc
+    program. If that does not locate the program,
+    the location of the GSAS-II Python files, the location of
+    the GSAS-II binaries, the current working directory (where the
+    GSAS-II .gpx file is located) and the location where Python is
+    installed, as well as the entire system path is searched for  ``rmcprofile`` or
+    ``rmcprofile.exe``. On MacOS, the only location where the 
 
+    See routine ``GSASIIpwd.findfullrmc()`` for details on finding the
+    fullrmc program.
+
+    
 **PDFfit2**
 ======================
 
@@ -66,5 +105,21 @@ There are several publicly-available programs where GSAS-II provides an interfac
     conflict between package versions. When GSAS-II is run from a
     Python installation that includes the conda package manager (which
     is the case with the GSAS2MAIN installer), the GUI will offer an option to
-    install PDFfit2 via a separate environment when the
-    PDFfit2 option is selected on the Phase/RMC tab.
+    install PDFfit2 into a separate environment when the
+    PDFfit2 option is selected on the Phase/RMC tab. This will define the `configuration
+    variable <https://advancedphotonsource.github.io/GSAS-II-tutorials/help/others.html#config>`_
+    ``pdffit2_exec`` as the Python image where PdfFit
+    can be imported using
+    ``from diffpy.pdffit2 import PdfFit``.
+    Routine ``GSASIIphsGUI.checkPDFfit()`` is used to install
+    PDFfit2. Note that a completely separate Python installation can
+    be used for PDFfit2 and then ``pdffit2_exec`` should be defined
+    as the Python image to run PDFfit2 using that Python command. 
+
+    When PDFfit is used, routine ``GSASIIpwd.findPDFfit()`` is used to
+    locate PDFfit. This is done using `configuration
+    variable <https://advancedphotonsource.github.io/GSAS-II-tutorials/help/others.html#config>`_
+    ``pdffit2_exec`` and if that is not available, it is checked if
+    PDFfit can be run within the Python interpreter that is already
+    running GSAS-II.  Note that PDFfit is run from
+    ``GSASIIpwd.MakePDFfitRunFile()``.