Add template for MD tutorials & document; add mathjax to tutorial build

Author: briantoby

.github/workflows/builddocsite.yml

@@ -88,13 +88,18 @@ jobs:
             for fil in $dirname/*.md; do
               outfile="${dest}/$(basename "${fil%.md}.html")"
               echo "creating $outfile from $fil"
-              pandoc --standalone ${fil} --css tutorial.css -o ${outfile}
+              pandoc --standalone --mathjax --css tutorial.css -o ${outfile} ${fil}
               sed -i "s/<figure>/<BR clear=all><figure>/g" ${outfile}
             done
-            git add ${dest}
+            #git add ${dest}
           done
-          cd ..
-        
+          fil=template.md
+          outfile=template.html
+          echo "creating $outfile from $fil"
+          pandoc --standalone --mathjax --css tutorial.css -o ${outfile} ${fil}
+          sed -i "s/<figure>/<BR clear=all><figure>/g" ${outfile}
+          #cd ..
+
       - name: build tutorials index 
         run: |
           cd scripts

MDhelp/README.md

@@ -1,36 +1,19 @@
-This directory contains a draft version of the GSAS-II help pages
-that have been converted from their MS-Word/HTML format into 
-MarkDown. Web pages are generated with mkdocs
-
-
-Status of work 7/20/2025:
-
-The 41 .md files have all been looked at, though some more carefully
-than others. 
-
-The next step is to tabulate Anchors used in the .md files
-(duplicates, missing names used in original .html)
-
-Need python code that selects and opens new .html file based on anchor. 
-
-
-Needs more work: 
-
-menu commands not described or well described in
-atoms, draw atoms & draw options. Should also describe the settings on
-draw options. Also, how does one expand a drawing to multiple cells? I
-always forget that trick!
-
-Texture: are there places where capital greek letters should be used
-to differentiate symbols (\Phi vs \phi) orientation angles?
-
-image.md: Make gain map appears to be moved to Image
-Controls/Calibrate/Multiimage gain map. Remove former? Units are not
-correct I think, for GSAS-II to Fit2D and pyFAI conversions
-
-It would be nice to generate a PDF of all pages. Could not get
-https://mkdocs-to-pdf.readthedocs.io to work on MacOS, but perhaps on
-Linux? There are other choices:
-https://comwes.github.io/mkpdfs-mkdocs-plugin/index.html 
-https://pypi.org/project/mkdocs-with-pdf/
-Everything seems to depend on https://weasyprint.org/
+This directory contains the files used to generate the GSAS-II help
+files, which are on the web at
+https://advancedphotonsource.github.io/GSAS-II-tutorials/help/ and are
+placed into the GSAS-II source code (at
+https://github.com/AdvancedPhotonSource/GSAS-II/tree/main/GSASII/help) 
+
+To view the pages as they are being edited use this command inside
+this directory::
+
+    mkdocs serve
+    
+and then open the address that is shown in a web browser. Web pages
+are rebuilt after any file is saved. 
+
+Note that this requires the following packages: mkdocs,
+          mkdocs-material, python-markdown-math, mkdocs-static-i18n, 
+          mkdocs-to-pdf, & pymdown-extensions. All are available with
+          pip. At least some with conda. Producing a .pdf also requires
+          Google chrome or chromium. 

MDtutorials/README.md

@@ -1,22 +1,33 @@
+This directory contains files used to generate new GSAS-II tutorials. (The older tutorials were created using Microsoft Word to produce `.html` files directly.)
+The tutorials are placed on the web at
+https://advancedphotonsource.github.io/GSAS-II-tutorials/<subdir> using two commands:
+
+    pandoc --standalone --css tutorial.css --mathjax -o ${outfile}  ${infil}
+    sed -i "s/<figure>/<BR clear=all><figure>/g" ${outfile}
+
+Note that on MacOS the sed command must be `sed -i "" "s/...`. The tutorial.css file is found in the MDtutorials directory and is copied to the same location as `$outfile`.
+
 # Steps in creating a new tutorial
 
 > [!NOTE] 
 > Note: this is draft info and needs to be checked that I did not leave anything out
 
 1. Create a new directory in the current location. Make sure not to use a name already in use for an existing tutorial (in the main directory, (https://github.com/AdvancedPhotonSource/GSAS-II-tutorials/tree/main). 
 
-1. Create a &lt;filename&gt;.md file in the new directory. Name is arbitrary, but repeating the directory name is not a bad idea. Start the file with content like this:
+1. Create a &lt;filename&gt;.md file in the new directory. Name is arbitrary, but repeating the directory name is not a bad idea. Look at file `template.md` as an outline for formatting the tutorial. Start the file with content like this:
 
         ---
         title: "Tutorial: ...anything you want to put here"
         ---
         <!--- Don't change the HTML version of this file; edit the .md version -->
 
         [//1]: <> (Comment: optional comment(s) here.)
-
+        
+        * Exercise files are found [here](data/index.html)
+        
         ## Intro
 
-    look at the previously-created tutorials in this directory to see how formatting is done. 
+    omit the "Exercise files..." line if no exercise files are in use. Note that the `.../data/index.html` file is generated automatically.
 
 1. Create a directory named `imgs` inside the new directory. Any images used in the tutorial go here. 
 

MDtutorials/TutorialGuide.txt

@@ -93,7 +93,7 @@ Build commands
 
       The HTML file is constructed from the markdown file using commands:
 
-              pandoc --standalone ${infil} --css tutorial.css -o ${outfile}
+              pandoc --standalone --css tutorial.css --mathjax -o ${outfile}  ${infil}
               sed -i "s/<figure>/<BR clear=all><figure>/g" ${outfile}
 
       Note that on MacOS the sed command must be sed -i "" "s/...". The tutorial.css file

MDtutorials/template.md

@@ -0,0 +1,142 @@
+---
+title: "Tutorial: Example tutorial to be written in Markdown"
+---
+
+[//1]: <> (Comment: This comment is only in the .md file, as opposed to the next line which is raw HTML and creates that is placed into the .html file.)
+<!--- Don't change the HTML version of this file; edit the .md version -->
+
+* Exercise files are found [here](data/index.html)
+
+<a name=Intro></a>
+
+## Intro
+
+The ## indicates a top-level heading. Headings with a single # would be used for dividing a file into completely separate sections. Probably not what you would want. Start with an introduction and explain here what the tutorial is all about. 
+
+### Writing Equations
+
+Note that subheadings use more than three # characters and sub-sub-headings can use four. 
+
+
+Note that equations can generated with MathJax (TeX formatting). "In-line" equations, such as: Er${}_2$Ge${}_2$O${}_{7.5}$ or $Er_2Ge_2O_{7.5}$
+or $P 4_1 2_1 2$. Note that by default MathJax uses an *italic* font for letters and not numbers, but that can be overridden, like this $\textrm{Er}_2\textrm{Ge}_2\textrm{O}_{7.5}$ or 
+$\rm Er_2Ge_2O_{7.5}$. Here is another in-line equation: 
+$d(u,v) = 1 - \frac{ u \cdot v }{ \sqrt{ u^2 v^2 } }$. Note the difference to a display equation, as below. In-line equation delimiters are a single dollar sign ($). 
+
+#### Display Equations
+
+Or, write display equations, such as 
+$$ d(u,v) = 1 - \frac{ ( u - \bar{u} ) \cdot ( v - \bar{v} ) }{ \sqrt{ ( u - \bar{u} )^2 ( v - \bar{v} )^2}} $$
+which appear on a line by themselves, use with double-dollar sign delimiters ($$). 
+
+### Formatting text
+
+A blank line indicates the start of a paragraph. Multiple blank lines are ignored. Lists can start with a "*" for a bullet or a number and a period (such as "0.") to indicate numbering. Use 4 spaces of indentation to indicated a nested list.
+
+0. numbered list item 1
+0. numbered list item 2
+
+* outer bullet list
+    * inner bullet list
+    
+    
+
+Format text between a single pair of asterisks for *italic* (like this `*italic*`) and doubled stars **bold** (like this `**bold**`). 
+
+
+Text that should be displayed verbatim (without interpretation) can be 
+placed between two 
+"backtick" quotes (\`). So here `$A = a x^2 +b x + c$` is not interpreted as an equation.
+For a block of text that spans multiple lines, begin the block with three "back tick" quotes (\`\`\`) alone on the line and end the block with the same. 
+
+### Links
+
+To provide a link to a location within the tutorial, define an anchor in HTML. Place this just before the location to be referenced. Here is the HTML code to define an anchor "myanchor":
+
+```
+     	     <a name=myanchor></a>
+```
+
+To place a link to the anchor use a command to reference to that location, with a MarkDown command like this:
+```
+   	    here is some text [with a link](#myanchor) provided 
+```
+Likewise for an external reference, replace "#myanchor" with a URL (beginning with http:).
+
+Here is some text [with a link](#Intro) provided to the Intro section and here is an external link: [GitHub ticket](https://github.com/AdvancedPhotonSource/GSAS-II/issues). 
+
+### Tables
+
+Tables can be created using pipe characters (|) and dashes (-). 
+Note that a colon can be used for right or left alignment or use two, as below for centering.
+
+
+```
+  	 |  `FontSize_incr`  | Example |
+	 | :---: | ------------------------------------- | 
+     | 0 | [see file `font0.png`](imgs/font0.png) |
+     | 3 | [see file `font0.png`](imgs/font3.png) |
+```
+
+The code above creates the table below.
+
+|  `FontSize_incr`  | Example |
+| :---: | ------------------------------------- | 
+| 0 | [see file `font0.png`](imgs/font0.png) |
+| 3 | [see file `font0.png`](imgs/font3.png) |
+
+See the markdown docs for other mechanisms to create tables. 
+
+
+
+### Figures
+
+![Select the preference menu](imgs/menu1.png)
+
+There are multiple ways to place figures into a tutorial. The simplest way is to use the standard MarkDown command: 
+
+```
+![Select the preference menu](imgs/menu1.png)
+```
+
+Note the similarity of this with the command for creating links, except that an explanation mark (!) is placed at the beginning. The .css file used with tutorials places figures created with this command at the right margin. 
+Typically one should place the figure before the text that references it. Leave a blank line after this command or the figure is placed into a paragraph -- probably not what you want, except perhaps with a very small figure. 
+
+Alternately one can use HTML commands to place an image at a particular place with an HTML command like this:
+
+```
+<BR clear=all>
+<img src="./imgs/menu1.png" alt="extra peaks" width="200px;">
+```
+
+
+<BR clear=all>
+The `BR` command forces the image into a new area of the page and may not be wanted  with a complex image layout. 
+<img src="./imgs/menu1.png" alt="extra peaks" width=200px height=100px align="left" align="top"  border=2px title="distorted image"> 
+The main advantage of the HTML command is that it allows one to rescale an image by specifying options such as `width` and/or `height`. Other options that may be of use are `align`, (align options are top, bottom, center, left, right), `title` (creates a tool-tip) and `border=2px` (for a 2 pixel black border around the image). 
+Also, with an HTML command one can control how text is wrapped around an image.
+
+The figure above was generated with this command embedded into the paragraph:
+```
+<img src="./imgs/menu1.png" alt="extra peaks" width=200px height=100px align="left" align="top" border=2px title="distorted image"> 
+```
+
+<BR clear=all>
+
+### Recommended
+
+End the document with a table with the date and author(s). Here is the code to do that:
+
+```
+     ----
+     | | 
+     | ---: |
+     | Brian Toby |
+     | August 1, 2025 |
+```
+
+----
+| | 
+| ---: |
+| Brian Toby |
+| August 1, 2025 |

MDtutorials/tutorial.css

@@ -42,8 +42,14 @@
       font-kerning: normal;
     }
     header {
+      display: grid;
+      background-image: url('https://advancedphotonsource.github.io/GSAS-II-tutorials/_images/gsas2.png');
+      background-size: 60px;
+      background-position: right; /* Centers the image within the header */
+      background-repeat: no-repeat; /* Prevents the image from repeating */
+      height: 60px;
       margin-top: 0em;
-      margin-bottom: 1em;
+      margin-bottom: 70px;
       text-align: center;
       counter-reset: h2cnt;
     }