From f3adaa923ca94415590e1aacf0b1417deb876447 Mon Sep 17 00:00:00 2001
From: Sean Bowe <ewillbefull@gmail.com>
Date: Sun, 11 Aug 2019 02:50:24 -0600
Subject: [PATCH] Add math rendering with KaTeX.

---
 Cargo.toml        |  3 +++
 katex-header.html | 15 +++++++++++++++
 src/g1.rs         | 10 +++++-----
 src/g2.rs         | 10 +++++-----
 src/scalar.rs     |  5 +++--
 5 files changed, 31 insertions(+), 12 deletions(-)
 create mode 100644 katex-header.html

diff --git a/Cargo.toml b/Cargo.toml
index a0c2e3546..af6a7c61b 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -9,6 +9,9 @@ repository = "https://github.com/zkcrypto/bls12_381"
 version = "0.0.0"
 edition = "2018"
 
+[package.metadata.docs.rs]
+rustdoc-args = [ "--html-in-header", "katex-header.html" ]
+
 [dependencies.subtle]
 version = "2.1"
 default-features = false
diff --git a/katex-header.html b/katex-header.html
new file mode 100644
index 000000000..98e85904f
--- /dev/null
+++ b/katex-header.html
@@ -0,0 +1,15 @@
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/katex.min.css" integrity="sha384-9eLZqc9ds8eNjO3TmqPeYcDj8n+Qfa4nuSiGYa6DjLNcv9BtN69ZIulL9+8CqC9Y" crossorigin="anonymous">
+<script src="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/katex.min.js"                  integrity="sha384-K3vbOmF2BtaVai+Qk37uypf7VrgBubhQreNQe9aGsz9lB63dIFiQVlJbr92dw2Lx" crossorigin="anonymous"></script>
+<script src="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/contrib/auto-render.min.js"    integrity="sha384-kmZOZB5ObwgQnS/DuDg6TScgOiWWBiVt0plIRkZCmE6rDZGrEOQeHM5PcHi+nyqe" crossorigin="anonymous"></script>
+<script>
+    document.addEventListener("DOMContentLoaded", function() {
+        renderMathInElement(document.body, {
+            delimiters: [
+                {left: "$$", right: "$$", display: true},
+                {left: "\\(", right: "\\)", display: false},
+                {left: "$", right: "$", display: false},
+                {left: "\\[", right: "\\]", display: true}
+            ]
+        });
+    });
+</script>
\ No newline at end of file
diff --git a/src/g1.rs b/src/g1.rs
index 607cf2739..a7bd55878 100644
--- a/src/g1.rs
+++ b/src/g1.rs
@@ -1,13 +1,13 @@
-//! This module provides an implementation of the G1 group of BLS12-381.
+//! This module provides an implementation of the $\mathbb{G}_1$ group of BLS12-381.
 
 use crate::fp::Fp;
 use subtle::Choice;
 
-/// This is an element of G1 represented in the affine (x, y) coordinate space. It
-/// is ideal to keep elements in this representation to reduce memory usage and
+/// This is an element of $\mathbb{G}_1$ represented in the affine coordinate space.
+/// It is ideal to keep elements in this representation to reduce memory usage and
 /// improve performance through the use of mixed curve model arithmetic.
 ///
-/// Values of `G1Affine` are guaranteed to be in the q-order subgroup unless an
+/// Values of `G1Affine` are guaranteed to be in the $q$-order subgroup unless an
 /// "unchecked" API was misused.
 #[derive(Copy, Clone, Debug)]
 pub struct G1Affine {
@@ -16,7 +16,7 @@ pub struct G1Affine {
     infinity: Choice,
 }
 
-/// This is an element of G1 represented in the projective (X, Y, Z) coordinate space.
+/// This is an element of $\mathbb{G}_1$ represented in the projective coordinate space.
 #[derive(Copy, Clone, Debug)]
 pub struct G1Projective {
     x: Fp,
diff --git a/src/g2.rs b/src/g2.rs
index 018f54ea3..4cad32f14 100644
--- a/src/g2.rs
+++ b/src/g2.rs
@@ -1,13 +1,13 @@
-//! This module provides an implementation of the G2 group of BLS12-381.
+//! This module provides an implementation of the $\mathbb{G}_2$ group of BLS12-381.
 
 use crate::fp2::Fp2;
 use subtle::Choice;
 
-/// This is an element of G2 represented in the affine (x, y) coordinate space. It
-/// is ideal to keep elements in this representation to reduce memory usage and
+/// This is an element of $\mathbb{G}_2$ represented in the affine coordinate space.
+/// It is ideal to keep elements in this representation to reduce memory usage and
 /// improve performance through the use of mixed curve model arithmetic.
 ///
-/// Values of `G2Affine` are guaranteed to be in the q-order subgroup unless an
+/// Values of `G2Affine` are guaranteed to be in the $q$-order subgroup unless an
 /// "unchecked" API was misused.
 #[derive(Copy, Clone, Debug)]
 pub struct G2Affine {
@@ -16,7 +16,7 @@ pub struct G2Affine {
     infinity: Choice,
 }
 
-/// This is an element of G2 represented in the projective (X, Y, Z) coordinate space.
+/// This is an element of $\mathbb{G}_2$ represented in the projective coordinate space.
 #[derive(Copy, Clone, Debug)]
 pub struct G2Projective {
     x: Fp2,
diff --git a/src/scalar.rs b/src/scalar.rs
index f5c1cd34a..387b95ea1 100644
--- a/src/scalar.rs
+++ b/src/scalar.rs
@@ -1,4 +1,4 @@
-//! This module provides an implementation of the BLS12-381 scalar field `GF(q)`
+//! This module provides an implementation of the BLS12-381 scalar field $\mathbb{F}_q$
 //! where `q = 0x73eda753299d7d483339d80809a1d80553bda402fffe5bfeffffffff00000001`
 
 use core::fmt;
@@ -9,7 +9,8 @@ use subtle::{Choice, ConditionallySelectable, ConstantTimeEq, CtOption};
 
 use crate::util::{adc, mac, sbb};
 
-/// Represents a scalar of the BLS12-381 elliptic curve construction.
+/// Represents an element of the scalar field $\mathbb{F}_q$ of the BLS12-381 elliptic
+/// curve construction.
 // The internal representation of this type is four 64-bit unsigned
 // integers in little-endian order. `Scalar` values are always in
 // Montgomery form; i.e., Scalar(a) = aR mod q, with R = 2^256.