CLMU Technote: Make .rst file of .docx file and get in the docs

[slevis-lmwg]

Description of changes

See title.

Specific notes

Contributors other than yourself, if any:
@olyson

CTSM issues resolved or otherwise addressed, if any:
Resolves #4175

Requirements before merge:

• I have followed the CTSM contribution guidelines.

[slevis-lmwg]

• Try the python script on the .docx file with the MathType equations /glade/u/home/oleson/CLMU_Tech_Note/CLMU_Tech_Note.docx in case it does better
  UPDATE: It's worse, but I also see some valid missing-word corrections that I will bring in. BUT the latter raises concerns of difficult-to-spot missing words among larger diffs in the rest of the doc.
• Compare the .md and .rst files to see which one we prefer:
• .md does better at including tables and figures
• .rst does better at rendering the equations, but we would have to include figures and tables manually
• .rst from pandoc (according to Keith O.) does similarly but seems to include the tables
• Tried converting to .md from the MathType version, and the equations became images, which is not what we want
• I suggested and Keith agreed that I try linking the docx to Section 2.16, but I skipped in favor of the next checkbox
• I'm trying NSF NCAR's Claude account first
  • Claude had me convert the equations from MathType to Word-native equations in MSWord, save as a modern .docx, and upload to Claude for the conversion to .rst
  • Built successfully after minor updates by me
  • 3 equations that ended up as images 13-15 need manual entry and removal of figures 13, 14, 15
  • I saw nothing wrong with: Two equation fragments (search for unusually short/odd .. math:: blocks with tab-like structure, around what were originally lines ~1949 and ~2640) had ambiguous source XML Claude didn't want to guess-fix — worth comparing against the original PDF/docx rendering
  • Claude recommended spot-checking a handful of the 100 display and ~1,850 inline math blocks against the original for visual fidelity

Then return to this list...

• Generally look for formatting and other issues
• Move this chapter's references section to the technote's References section and link this section's references
• Number the Figures and Tables and link references to them
• Number the Equations and link references to them

[slevis-lmwg]

@olyson
Claude's .rst file looks much better (as I mentioned earlier).
I have cleaned up several minor things.

There are few bigger tasks that I listed in checkboxes above that I will let you prioritize as TODO high/med/low/would be nice to have. I'm open to continue helping.

You can pick up to view the built version at /glade/work/slevis/git/b4b-dev/doc/_build/html.

[slevis-lmwg]

A thought regarding the remaining busy-work:

• I will ask Claude to look at the current .rst file and do the linking of the tables and figures
• I uploaded the updated file to my branch: Review diffs (very quick), build, copy to laptop, review rendered copy
• Repeat with the equations; in this step Claude helped immensely, but Claude's output required many corrections
• Repeat with the references; this was easy for Claude
• Merge this chapter's References section with the Technote's References section

[slevis-lmwg]

My prompts to Claude (thread titled Converting docx to reStructuredText format) copied and pasted here.

The .docx to .rst conversion

• I want to convert a 220-page Microsoft .docx file containing tables, figures, and Mathtype equations to the .rst equivalent.
• Step by step, how do I convert the equations into OMML?
• I'm at step 6 asking to Save as .docx (default), and I get this message: "The following features in this doc are not supported by earlier versions of Word. Click Cancel and save in one of the new file formats: Equations will be converted to images. You will not be able to edit the equations until the document is converted to a new file format." What format should I save as instead?
• How do I upload the .docx for you to convert?
• Convert this 220-page document to .rst
• Continue
• The "Download" button is failing on the "media"

Dynamic Table and Figure numbering

• The .rst that you generated for me earlier in this thread mostly worked. I made a few edits and now I would like to upload it again for you to change the Table and Figure labeling so that the Table and Figure numbering can happen automatically based on section numbers. This specific .rst will likely be section 2.17 in a future version of the CLM Technical Note, but if it ends up as 2.18 or some other number, I want the Table and Figure numbering to update automatically in the rendered version that will appear online. Can you help?
• The updated rst file in which I would like Tables and Figures without hardcoded numbers so Sphinx can auto-generate the number and I can cross-reference using :numref:

Dynamic Equation numbering

• In the last .rst that you generated, I would like to add dynamic numbering to the equations, similar to what you did to the Figures and Tables.
• Yes, I would appreciate that, and you may find the correct cross-referencing in the docx file that I uploaded originally.
• For now, instead of fixing the unambiguous and flagging the rest, I am uploading a copy of the .docx where I clearly see the equation numbers (e.g. in the example that you quoted "Equations (2.4) and (2.5) for the walls and equation (2.6) for the road can now be expanded..." AND let me know if for some reason you still can't read the in-text references.
• Continue
• Continue
• Continue
• I would like to convert the (as you pointed out) "many single-line formulas that Pandoc folded into inline :math: roles" that "were individually numbered in the original Word doc," to .. math:: blocks and number them dynamically, as you did with the rest of the equations.
• Yes, continue with that approach for the remaining 96.

Linking in-text references to the References section

• I had to make some corrections to your otherwise immensely helpful work. Now, in the latest .rst that I'm uploading, I would like to see the in-text references linked to the reference list appearing in the last section of the file.
• I want to keep reading as "(Oleson et al. 2010a)" while the latter is a clickable link, because it's what we do in all the other chapters of the CLM Technote.