Going back to CodeCogs for math blocks

GitHub's LaTeX rendering is just not fit for purpose.

When it works it's extremely convenient, but:

1. It's riddled with all sorts of bugs that are frustrating to try to
   work around.

   See https://github.com/nschloe/markdown-math-acid-test for some
   examples. This is after more than a year from release.

   The current pain in my backside is when you have both inline math and
   block math in the same list item? There's no real workaround for this
   so you either have to give up on math blocks or give up on lists.
   Both of these options make the readability of the document worse.

   See https://github.com/orgs/community/discussions/17325 for this
   specific bug.

2. The LaTeX rendering on GitHub is surprisingly ugly?

   It's quite jarring going from other markdown renderers like StackEdit
   to GitHub.

   Some research suggests this might be machine-font related, but I've
   tested on multiple machines, Firefox and Chrome (Chrome is slightly
   better), but the results have always be unsatisfying.

So going back to CodeCogs.

The ghmath2codecogs.py scripts helps with this.

Note the original LaTeX is still accessible in the alt field of the img
links.

Author: geky

README.md

@@ -134,9 +134,12 @@ You can describe this mathematically in [GF(2)][gf2] (the extra
 $x^{\left|P\right|}$ represents shifting the message to make space for
 the CRC), but the above example is probably easier to understand:
 
-``` math
-C(x) = M(x) x^{\left|P\right|} - (M(x) x^{\left|P\right|} \bmod P(x))
-```
+<p align="center">
+<img
+    alt="C(x) = M(x) x^{\left|P\right|} - (M(x) x^{\left|P\right|} \bmod P(x))"
+    src="https://latex.codecogs.com/svg.image?C%28x%29%20%3d%20M%28x%29%20x%5e%7b%5cleft%7cP%5cright%7c%7d%20%2d%20%28M%28x%29%20x%5e%7b%5cleft%7cP%5cright%7c%7d%20%5cbmod%20P%28x%29%29"
+>
+</p>
 
 The neat thing is that this remainder operation does a real good job of
 mixing up all the bits. So if you choose a good CRC polynomial, it's very

ghmath2codecogs.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+
+import re
+
+URL = "https://latex.codecogs.com/svg.image?%s"
+
+def main(input, output):
+    lines = []
+    with open(input) as f:
+        for line in f:
+            lines.append(line)
+
+    with open(output, 'w') as f:
+        math = None
+        ws = None
+        for line in lines:
+            if math is None:
+                m = re.match('(\s*)```\s*math', line)
+                if m:
+                    # start collecting math lines
+                    math = []
+                    ws = m.group(1)
+
+                else:
+                    f.write(line)
+
+            else:
+                m = re.match('(\s*)```', line)
+                if m:
+                    # merge all math, removing newlines
+                    math = ''.join(m[:-1]+' ' for m in math)
+                    # deduplicate a whitespace, but whitespace is
+                    # important so keep one space
+                    math = re.sub('\s+', ' ', math)
+                    # and strip
+                    math = math.strip()
+
+                    # create the codecogs link
+                    f.write('%s<p align="center">\n' % ws)
+                    f.write('%s<img\n' % ws)
+                    f.write('%s    alt="%s"\n' % (ws, math))
+                    f.write('%s    src="%s"\n' % (ws, URL % ''.join(
+                        # for codecogs we need to url-encode our latex
+                        c if re.match('[a-zA-Z_]', c)
+                            else '%%%02x' % ord(c)
+                        for c in math)))
+                    f.write('%s>\n' % ws)
+                    f.write('%s</p>\n' % ws)
+
+                    # reset
+                    math = None
+                    ws = None
+        
+                else:
+                    math.append(line)
+
+
+if __name__ == "__main__":
+    import sys
+    import argparse
+    parser = argparse.ArgumentParser(
+        description="Rewrite a markdown file so GitHub math blocks "
+            "are replaced with embedded images generated by codecogs.",
+        allow_abbrev=False)
+    parser.add_argument(
+        'input',
+        help="Input markdown file.")
+    parser.add_argument(
+        '-o', '--output',
+        required=True,
+        help="Output markdown file.")
+    sys.exit(main(**{k: v
+        for k, v in vars(parser.parse_args()).items()
+        if v is not None}))