help files done for now

Author: briantoby

.github/workflows/test_builddocsite.yml

@@ -9,6 +9,8 @@
 # this is a development version that creates draft help pages from the MDhelp directory
 # For now
 #  * HTML help files are copied over from the GSAS-II sources
+# Eventually, the help files generated here need to get into the GSASII/help
+# directory
 
 name: build GSAS-II web site w/test MD Help
 
@@ -61,6 +63,8 @@ jobs:
           cp -vr site ../help_test
           ENABLE_PDF_EXPORT=1 mkdocs build
           mv site/GSASII-help.pdf ../docs/
+          # create an anchor index
+          python findMDanchors.py
           cp -vr site ../help_test
           
       # - name: Upload help artifact  # creates zip file with website contents

MDhelp/docs/applicationwindow.md

@@ -13,6 +13,7 @@ The data tree shows contents of a GSAS-II project (which can be read or saved as
 The leftmost entries in the GSAS-II menu provide access to many features of GSAS-II. Other menu items will change depending on what type of entry is selected in the data tree. The menu commands that do not change and are described in the [main menu commands](./mainmenu.md) documentation.
 
 <a name="Data_frame"></a>
+<a name="Data_Frame"></a>
 ## GSAS-II Data Window
 
 Different information is displayed in the Data Editing Window, depending on which section of the [data tree](#Data_tree) is selected. For example, clicking on the "Notebook" entry of the data tree brings up the [Notebook editing window](./commontreeitems.md#Notebook), as documented elsewhere.

MDhelp/docs/commontreeitems.md

@@ -28,7 +28,7 @@ This window provides access to the controls that determine how GSAS-II performs
 [Configuration variables section of the Programmer's documentation.](https://gsas-ii.readthedocs.io/en/latest/GSASIIutil.html#config-example-py-configuration-options) for listing of these options.)
 
 1. **Refinement Controls**: 
-<a name="Refinement Controls"></a>
+<a name="RefinementControls"></a>
  These controls determine how refinements are performed. The first determines the computational engine used to minimize the structure.
 
     * **Refinement type** - 
@@ -136,6 +136,7 @@ In addition to menu commands, this window also offer the following actions by pr
 * **Show Generated Constraints** - After constraints have been processed, a series of relationships are developed to determine new variables from the current parameters and "inverse" equations that determine dependent parameters from the new variables and independent parameters. This shows the resulting relationships, as well as any "Hold" variables.
 * **Delete Selected** - This button will cause all the selected constraints on the current tab to be deleted.
 
+<a name=Constraints-SeqRef></a>
 ### Sequential Refinement Constraints
 
 While all the general information on constraints (above) applies to sequential refinements, the sequential refinement is performed by fitting each histogram individually and this affects how constraints are defined and processed for parameters keyed to a particular histogram number. When sequential refinement is selected (via the [Controls](#Controls) tree item), it becomes possible to define constraints of form `p:*:name` and `:*:name` (where "p" is a phase number and name is a parameter name). The "*" here is called a wildcard, and in a constraint or equivalence will cause that to be used for every histogram in turn.
@@ -171,6 +172,7 @@ This window shows the restraints to be used in a refinement for each phase (if m
     * **Delete restraints** - this deletes selected restraints from the list. A single click in the blank box in the upper left corner of the table will select/deselect all restraints.
 
 <a name="Rigidbodies"></a>
+<a name="Rigid_bodies"></a>
 ## Rigid bodies
 
 There are three different types of rigid bodies that can be used in GSAS-II, as selected by the tabs at the top of this window. 

MDhelp/docs/datatree.md

@@ -1,30 +1,36 @@
 <!--- Don't change the HTML version of this file; edit the .md version -->
+<a name="DataTreeOverview"></a>
 # GSAS-II data tree overview
 
 GSAS-II creates projects that are saved in `.gpx` files. The [GSAS-II Data Tree](./applicationwindow.md#Data_tree), which is shown on the left side of the main GSAS-II window shows a hierarchical index to the contents of a project. This index will usually have all of the entries listed below on the [Universal Data Tree Items](./commontreeitems.md) page, which are found in all types of GSAS-II projects and will also have at least one entry representing some sort of experimental data (or simulation) -- called a histogram -- and will likely have one or more phase entries. 
 
-When you click on an entry in the [data tree](./applicationwindow.md#Data_tree), the right side of the GUI, the [GSAS-II Data Window](./applicationwindow.md#Data_frame)  will show the associated information with that section of the .gpx file, you may have access to additional menu commands and visualization information related to the selected data tree item may be shown in the [GSAS-II Graphics Window](./applicationwindow.md#Plots). 
+When you click on an entry in the [data tree](./applicationwindow.md#Data_tree), the right side of the GUI, the [GSAS-II Data Window](./applicationwindow.md#Data_frame)  will show the associated information with that section of the `.gpx` file, you may have access to additional menu commands and visualization information related to the selected data tree item may be shown in the [GSAS-II Graphics Window](./applicationwindow.md#Plots). 
 
 Most of the subsequent sections of the GSAS-II help documentation describe: what the values shown in the GUI mean and what actions can be performed using the GUI, the menu commands and actions available for each type of data tree item, as well as any graphics that will be displayed and actions that can be performed graphically. 
 
 ## Data tree Histogram items
 
 These constitute the data sets ("Histograms") to be used by GSAS-II for analysis. 
-These are shown in the data tree as top-level entries with a prefix of:
+These are shown in the data tree as top-level entries where the prefix indicates the 
+data type. The name in the data tree is usually followed by a descriptive term or file name. 
+Most histogram types have information divided into sections, where each section is placed into a child (subdata) tree entry under the main histogram data entry. 
+Selection of the main data tree item for a histogram may not produce much information in the [data window](./applicationwindow.md#Data_frame) but usually does provide visualization of the data in the [graphics window](./applicationwindow.md#Plots). 
+The histogram data prefixes are listed below and are described in subsequent sections of this help information.
 
  * [**PWDR**](./powder.md): Powder Diffraction data
  * [**HKLF**](./singlecrystal.md): Single Crystal data
  * [**PDF**](./pairdistribution.md): Pair Distribution Functions (derived from data)
  * [**IMG**](./image.md): 2D Diffraction Images
  * [**SASD**](./smallanglescattering.md): Small Angle data
  * [**REFD**](./reflectometry.md): Reflectometry data
- 
-The prefix in the entry is followed by a descriptive term or file name. Selection of these items may not produce much information in the [data window](./applicationwindow.md#Data_frame) but does visualize the data in the [graphics window](./applicationwindow.md#Plots). The histogram data items are described in subsequent sections of this help file. 
+ * [**PKS**](./peaks.md) Powder Diffraction peak lists
+
 
 ## Data tree Phase information
 
-A [GSAS-II phase](./phaseoverview.md) is the description of a crystal structure, including unit cell parameters, symmetry and atom coordinates. Each phase is placed in the [data tree](./applicationwindow.md#Data_tree) as a child (subdata) tree entry in the phase. 
+A [GSAS-II phase](./phaseoverview.md) is the description of a crystal structure, including unit cell parameters, symmetry and atom coordinates. Each phase is placed in the [data tree](./applicationwindow.md#Data_tree) as a child (subdata) tree entry in the phase. Note that while phases do not have any special prefix and do not have child entries in the data tree, the phase information is separated into sections through the use of tabs on the upper part of the data window. The tabs are listed
+[here](./phaseoverview.md#PhaseTabList) and each tab is documented separately. 
 
 ## Phase/Histogram Linking
 
-Note that there is no limit to the number of phase and histogram entries that may be placed a project file, beyond that the computer being used must have enough memory to hold this information. Also, all the histogram and phase entries in project need not be utilized. Every phase can be linked to zero, one or more histograms. A single-crystal dataset can only be linked to one phase (or none), but a powder diffraction dataset can be linked to any number of phases, including zero. A phase that is not linked to a histogram is not used in refinements. Likewise, a histogram that is not linked to a phase is also not used. 
+Note that there is no limit to the number of phase and histogram entries that may be placed a project file, beyond that the computer being used must have enough memory to hold this information. Also, all the histogram and phase entries in project need not be utilized. Every phase can be linked to zero, one or more histograms. A single-crystal dataset can only be linked to one phase (or none), but a powder diffraction dataset can be linked to any number of phases, including zero. A phase that is not linked to a histogram is not used in refinements. Likewise, a histogram that is not linked to a phase is also not used. Deleting unlinked entries from a `.gpx` file is possible, but is not recommended as it may introduce problems; these are bugs that are hard to track down.

MDhelp/docs/image.md

@@ -128,6 +128,7 @@ There are menu commands to create masks as well as keyboard shortcuts. If a menu
     *   **Search to add to the pixel mask** using either the Operations->"Pixel mask search" or the Operations->"Multi-IMG pixel mask search" menu commands. This searches for pixels that have intensities that are significantly higher or lower than the median intensity for all pixels in a ring having the same two-theta value. The threshold for exclusion is determined by the standard deviation for the pixels in the ring multiplied by a user-supplied value.
 
 <a name="IMG_StressStrain"></a>
+<a name="IMG_Stress/Strain"></a>
 ## Stress/Strain
 
 This allows one to evaluate strain typically induced by a pure axial load (e.g. no shear) on a polycrystalline sample (e.g. a steel bar). This strain will distort the Bragg diffraction rings seen by the 2D detector. This follows the method of He & Smith (Baoping Bob He & Kingsley Smith, (1997). Adv. in X-Ray Anal. **41**, 501.) to determine the 3 unique terms of the axial strain tensor. One can examine the results as a series of diffraction line d-spacings vs azimuth angle; if no strain, these are straight, otherwise they will show a single sinusoidal variation with maxima at the maximum strain direction (90° & 270°) for a tension load. The signs are reversed for a compression load. One can also examine the local intensity variation as multiples of a random distribution (**MRD**) due to texture. Before embarking on this analysis be sure that your detector is *carefully calibrated* for orientation and position; you are looking for very slight variations in ring shape which may be biased by inadequate detector calibration. Commonly, the calibrant (typically \(\rm CeO_2\)) is painted on one sample surface (be sure to note if in front or back of sample!) and the sample ½ thickness is used in the Sample delta-z box (significant only for residual stress analysis).

MDhelp/docs/others.md

@@ -1,6 +1,7 @@
 <!--- Don't change the HTML version of this file; edit the .md version -->
 # Miscellaneous information
 
+<a name="Mac"></a>
 <a name="MacOS"></a>
 ## Macintosh notes:
 
@@ -10,6 +11,7 @@ At present, two versions of GSAS-II are provided. One is for older, Intel CPUs a
 GSAS-II defines actions for both the left and right and middle buttons assuming that a three-button mouse is available. If a two or three-button mouse is used with a Mac, the "extra"  mouse buttons will work as intended. If using a Mac touchpad or single-button mouse, clicking the touchpad or mouse button will generate a "left button" click. Hold down the control-key to generate a "right button" click or for a right-button drag, hold down control while pressing on the mouse button or touchpad. I do not know how to generate a middle-button click or drag with a single-button mouse, but with a MacBook touchpad, pressing with two fingers generates the equivalent of a right-mouse drag and moving two fingers without pressure is the equivalent of a middle-button drag action. 
 
 <a name="config"></a>
+<a name="Preferences"></a>
 ## Configuration Variables:
 
 GSAS-II provides a number of configuration settings that can be changed via variables that can be set and saved. These are controlled in the File/Preferences menu item (on Mac the Preferences menu is found in the usual place on Macs, in the main application menu as well as in the File menu). These settings are saved for subsequent runs in a file named `config.ini` in the user's `.GSASII` directory. More information, including a list of the available configuration variables and their use can be found in the `config_example.py` file or the [Configuration variables section of the Programmer's documentation.](https://gsas-ii.readthedocs.io/en/latest/GSASIIutil.html#config-example-py-configuration-options) 
@@ -20,6 +22,8 @@ GSAS-II provides a number of configuration settings that can be changed via vari
  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. 
 
 <a name="Origin_1"></a>
+<a name="_Origin_1"></a>
+<a name="Origin1"></a>
 ## Origin 1 -> Origin 2 Transformations
 
 An important transformation may be needed in certain cases for space groups that have two alternate origin settings [listed here](https://gsas-ii.readthedocs.io/en/latest/GSASIIutil.html#GSASII.GSASIIspc.spg2origins).
@@ -62,7 +66,7 @@ With coordinates that match the space group operations, the correct Ti-O distanc
 
 
 
-<a name="FPA"></a>
+<a name="FPA"></a><a name=FPAinput></a>
 ## Fundamental Parameters as used to derive instrumental parameters
 
 This describes the FPA terms used to determine instrumental parameters in the 

MDhelp/docs/phasedata.md

@@ -42,6 +42,7 @@ For single crystal data, the only parameters are scale, extinction and disordere
 * **Hydrostatic/elastic strain** – This shifts the lattice constants for the contribution of a phase into a histogram. The values are added to the [reciprocal lattice parameter tensor terms](http://gsas-ii.readthedocs.io/en/latest/GSASIIutil.html#gsasiilattice-unit-cell-computations). They must be refined in sequential refinements or where the lattice constants are slightly different in different histograms (as an example see the [Combined X-ray/CW-neutron refinement of \(\rm PbSO_4\) tutorial](https://advancedphotonsource.github.io/GSAS-II-tutorials/CWCombined/Combined%20refinement.htm). But these values and the phase's lattice parameters (on the General tab) should not be refined at the same time. When the values are non-zero, the lattice constants after application of these strain tensor terms is shown. 
 
 <a name="Phase-Preferred_orientation"></a>
+<a name="Preferred_orientation"></a>
 <a name="preferred_orientation"></a>
 * **Preferred Orientation** – Preferred orientation (texture) can be treated in one of two different sections of GSAS-II, either the Preferred Orientation correction here in the Data tab, or the "[Texture](phasetexture.md)" tab, depending on what is desired. 
 The Preferred Orientation correction here is typically used for crystallographic studies, where intensity corrections are desired to repair for undesired texture in the sample, while the Texture tab is used for studies where the goal is to characterize preferred orientation in a sample.

MDhelp/docs/phaseoverview.md

@@ -9,6 +9,7 @@ Phases are either created with the Data/"Add new phase" menu item (manual input)
 
 When a phase is selected from the data tree, parameters are shown for that selected phase in a tabbed window. Clicking on each tab raises the windows as documented in subsequent sections of the help documentation. The tabs are:
 
+<a name="PhaseTabList"></a>
  - [General](./phasegeneral.md)
  - [Data](./phasedata.md)
  - [Atoms](./phaseatoms.md)

MDhelp/docs/preface.md

@@ -1,6 +1,7 @@
 <!--- Don't change the HTML version of this file; edit the .md version -->
 # GSAS-II Tutorials
 <a name="Tutorial"></a>
+<a name="Tutorials"></a>
 
 The best way to learn about how different sections of GSAS-II is used
 is to work through some of the tutorials. 

MDhelp/docs/singlecrystal.md

@@ -19,10 +19,12 @@ You can change the weight factor. This is a multiplier on all of the reflection
 : * see K box for all the possible commands.
 * **Plot 3D HKLs** - shows a 3D representation of the unique part reciprocal space points for this phase. The save as/key item in the plot status bar shows the various commands for modifying this plot.
 
+<a name="HKLF_Instrument_Parameters"></a>
 ## Instrument Parameters
 
 This window shows the histogram type (SXC or SNC, for x-ray and neutron, respectively) and the wavelength. You may change the wavelength or radiation type but rarely will need to do so.
 
+<a name="HKLF_Reflection_List"></a>
 ## Reflection List
 
 This window shows the reflections for this single crystal data set.