Update for replacement of various Angstrom unit variants -> \AA

Author: willend

docs/manuals/mcstas/fix_unit_exponents.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""
+r"""
 fix_unit_exponents.py
 
 One-off maintenance script: normalizes implicit unit exponents in McStas
@@ -8,7 +8,7 @@
 
     cm2      -> cm^2
     AA-1     -> AA^-1
-    Angs-1   -> Angs^-1
+    Angs-1   -> AA^-1
     m3       -> m^3
     cm-2 s-1 -> cm^-2 s^-1
 
@@ -18,6 +18,15 @@
 only do so if the source .comp/.instr headers actually use the "^"
 notation in the first place.
 
+Along the way, it also canonicalizes Angstrom shorthand spelling to "AA"
+(the dominant convention in this codebase): "Angs", "Ang", "Angstrom" and
+"Angstroms" all become "AA". This is a source-level complement to
+_tex_with_angstrom()/_ANGSTROM_RE in mcdoc.py, which already recognize
+all of these spellings when rendering and turn them into the LaTeX \AA{}
+(ring-A, i.e. \AA{}) symbol regardless -- but keeping the source spelling
+consistent is worth doing too, rather than accumulating several synonyms
+for the same thing across the library.
+
 Scope: deliberately narrow, matching exactly what _format_unit() acts on:
   - Only lines inside a %P / %PARAMETERS McDoc section (tracked by
     scanning for %-tag lines; any %-tag whose first letter isn't P exits
@@ -31,6 +40,9 @@
     "^" (so "AA^3" and "cm^-2" are left alone), and only where the digit
     run ends at a word boundary (so e.g. "H2O" is correctly left alone --
     the "O" right after "2" means there's no exponent there to convert).
+  - The Angstrom-spelling canonicalization only matches whole "Angs"/
+    "Ang"/"Angstrom"/"Angstroms" tokens (word-bounded), so it cannot
+    touch part of a longer identifier or word.
 
 Usage:
     # Preview changes as a unified diff; changes nothing on disk:
@@ -48,8 +60,8 @@
 already-correct carets, chemical-formula-shaped false positives, prose
 outside %P), but a human pass over a mechanical, repo-wide edit is always
 worthwhile. Two files (contrib/NMO.comp, samples/PowderN.comp) have
-already been fixed by hand as a spot-check; running this script over them
-again should report zero further changes.
+already been fixed by hand as a spot-check, using "AA" throughout; running
+this script over them again should report zero further changes.
 """
 import argparse
 import difflib
@@ -65,15 +77,21 @@
 # ':' possibly being followed directly by '[' with no space).
 PARAM_LINE_RE = re.compile(r'^(\s*\*\s*[\w.]+\s*:)(.*)$')
 
+# Angstrom shorthand spellings other than the canonical "AA", matched as
+# whole words only.
+ANGSTROM_SYNONYM_RE = re.compile(r'\b(?:Angstroms?|Angs?)\b')
+
 # A "word immediately followed by an exponent" token, e.g. cm2, AA-1,
 # m-2.5 -- but not one already preceded by '^' (e.g. the "3" in "AA^3").
 EXPONENT_RE = re.compile(r'(?<!\^)\b([A-Za-z]+)(-?\d+(?:\.\d+)?)\b')
 
 
 def normalize_unit(unit):
-    ''' Converts cmN -> cm^N / AA-1 -> AA^-1 style tokens within one
-    [unit] bracket's content; anything else (units with no numeric
-    suffix, or already using '^') is left untouched. '''
+    ''' Canonicalizes Angstrom spelling to "AA", then converts cmN ->
+    cm^N / AA-1 -> AA^-1 style tokens within one [unit] bracket's
+    content; anything else (units with no numeric suffix, or already
+    using '^') is left untouched. '''
+    unit = ANGSTROM_SYNONYM_RE.sub('AA', unit)
     return EXPONENT_RE.sub(r'\1^\2', unit)
 
 

tools/Python/mcdoc/mcdoc.py

@@ -103,6 +103,13 @@ def _tex(s):
     return s
 
 
+# Standalone tokens that are ASCII shorthand for Angstrom in McStas
+# comp/instr headers -- "AA" is the dominant convention, but "Angs",
+# "Ang", "Angstrom"/"Angstroms" also appear. All are converted to the
+# proper LaTeX \AA{} (ring-A) symbol; see _tex_with_angstrom() below.
+_ANGSTROM_RE = re.compile(r'\b(?:AA|Angstroms?|Angs?)\b')
+
+
 # ------------------------------------------------------------------
 #   %D "Description" field -> flowing LaTeX (instead of one big
 #   \verbatim block), with a small, whitelisted set of embedded HTML
@@ -201,14 +208,15 @@ def repl_img(m):
     # single space, exactly like ordinary paragraph reflow.
     s = re.sub(r'\s+', ' ', s).strip()
 
-    # Standalone "AA" (Angstrom) tokens -> \AA{}. Detected here, on the
-    # raw text (with only tag-derived placeholders interspersed, which
-    # can't create false word boundaries), and stashed via the *same*
-    # top-level tokens list as everything else above -- this is safe
-    # because it is a sibling top-level substitution into s, not nested
-    # inside another not-yet-resolved stashed value (contrast with
-    # _tex_with_angstrom(), which is for standalone/isolated use).
-    s = re.sub(r'\bAA\b', lambda m: stash(r'\AA{}'), s)
+    # Standalone "AA"/"Angs"/"Ang"/"Angstrom(s)" (Angstrom) tokens -> \AA{}.
+    # Detected here, on the raw text (with only tag-derived placeholders
+    # interspersed, which can't create false word boundaries), and
+    # stashed via the *same* top-level tokens list as everything else
+    # above -- this is safe because it is a sibling top-level
+    # substitution into s, not nested inside another not-yet-resolved
+    # stashed value (contrast with _tex_with_angstrom(), which is for
+    # standalone/isolated use).
+    s = _ANGSTROM_RE.sub(lambda m: stash(r'\AA{}'), s)
 
     # Escape everything else exactly like normal LaTeX text (this also
     # correctly turns any *unrecognized* '<tag>' into literal, visible
@@ -278,12 +286,13 @@ def _mccode_label():
 
 def _tex_with_angstrom(s):
     r'''
-    Like _tex(), but additionally converts standalone "AA" tokens -- the
-    common ASCII shorthand for Angstrom used throughout McStas comp/instr
-    headers, since the actual \AA{} (Angstrom, ring-A) character is rarely
-    typed directly -- into the proper LaTeX \AA{} symbol.
+    Like _tex(), but additionally converts standalone Angstrom shorthand
+    tokens -- "AA" is the dominant convention in McStas comp/instr
+    headers, but "Angs", "Ang", "Angstrom"/"Angstroms" also appear, since
+    the actual \AA{} (Angstrom, ring-A) character is rarely typed directly
+    -- into the proper LaTeX \AA{} symbol.
 
-    The "AA" detection deliberately happens on the *raw*, not-yet-escaped
+    The token detection deliberately happens on the *raw*, not-yet-escaped
     text (protected via a stash/placeholder, exactly like
     _convert_inline_markup does for HTML tags) rather than after _tex()
     has run. This matters: in raw text, '_' is a word character, so
@@ -304,7 +313,7 @@ def _tex_with_angstrom(s):
     def stash(repl):
         tokens.append(repl)
         return '\x01%d\x02' % (len(tokens) - 1)
-    s = re.sub(r'\bAA\b', lambda m: stash(r'\AA{}'), s)
+    s = _ANGSTROM_RE.sub(lambda m: stash(r'\AA{}'), s)
     s = _tex(s)
     def restore(m):
         return tokens[int(m.group(1))]