📝 Small changes in docs

Author: hacker-DOM

README.adoc

@@ -52,23 +52,25 @@ Putting LaTeX equations in other places than a TeX document is not so easy. Ther
 
 * {mathjax}
 ** It uses native browser fonts and a lot of Css to replicate {latex} in the browser.
+** It also has an svg output option!
 * {katex}
 ** Similar to {mathjax}, built by Khan Academy.
+** Does not have svg output.
 
 ### 🔍 STEM
 STEM stands for Science, Technology, Engineering, Mathematics, basicaly {latex}. There are two sections in the {adoc} documentation on STEM:
 
 * {adoc-stem}
 * {adoctor-pdf-stem}
 
-TLDR:
+The TLDR is:
 
-* In {adoctor} (i.e. Html output), you can include math with `stem:[x+y]`. In the browser, {mathjax} is used to render the math, and frankly, it looks beautiful.
+* In {adoctor} (i.e. Html output), you can include math with pass:n[``stem:[ x+y``]``]``. In the browser, {mathjax} is used to render the math, and frankly, it looks beautiful.
 * Since {mathjax} uses browser fonts and Css, it doesn't work in Pdfs. There is an official {adoctor-math} package that provides this support. However, it is extremely quirky, and the ouput doesn't look very good (see a comparison of {adoc-math} and {adoctor-math} in the {example})
 ** Some more references:
 *** https://github.com/asciidoctor/asciidoctor-mathematical/issues/45
 
-### 🔍 Architecture
+### 🔍 adoc-math
 
 That's where `adoc-math` comes in! I decided for:
 
@@ -106,6 +108,14 @@ For more examples, see the {example}.
 
 I don't speak Ruby 😞 If you would like to translate this library to Ruby, or at least an AsciiDoc macro that can get replaced by an image, so we cant get rid of the extra metacompilation step, I'd be more than happy to help!
 
+> Why aren't inline cells avaiable "in line", such as "Let $x$ be a integer."?
+
+This decision was chosen very early during development. It makes the parsing logic easier, and reduces the change that a paragraph containing two dollar signs will get replaced by LaTeX. In theory, it would be possible to add this; however, the output will still have at least one linebreak, since we want to comment out the source math. We would probably be better off just making an Asciidoc macro (`stem[]`, `m[]`, or something similar), but we need a Ruby speaker!
+
+> What are `ex` units?
+
+An ex unit is equal to the font size (height) of the lowercase `x` character. So it's roughly one half of a line? It's used in Mathjax's svgs (as the `width`, `height` and `vertical-align`) and in `adoc-math` to adjust the `vertical-align`.
+
 > What about Windows?
 
 I tried to be conscious of non-Posix platforms, but haven't tested in on Windows. Any behavioral discrepancies would be considered valid issues.

adoc_math/__main__.py

@@ -21,7 +21,7 @@ def parse_args():
 
     p.add_argument(
         "target_files",
-        help="List of files to run `adoc-math` on. Inline cells (lines such as `$x+y$ tex`) or block cells (lines such as [`$$ amath\n`, `x+y\n`, `$$\n`]) will be read for contents, parsed for options, passed into MathJax@3, and (optionally) the svg transformed. The svg will then be saved to the output directory, and the source file modified: the cell will be commented out and an image macro with a reference to the svg will be inserted. 🤟🚀",
+        help="List of files to run `adoc-math` on. Inline cells (lines such as `$x+y$ tex`) or block cells (line ranges such as [`$$ amath\n`, `x+y\n`, `$$\n`]) will be read for contents, parsed for options, passed into MathJax@3, and (optionally) the svg transformed. The svg will then be saved to the output directory, and the source file modified: the cell will be commented out and an image macro with a reference to the svg will be inserted. 🤟🚀",
         **list_of_files,
     )
 
@@ -39,7 +39,7 @@ def parse_args():
 
     p.add_argument(
         "--default-lang",
-        help="Default language. Can be TEX (LaTeX) or AMATH (AsciiMath). Default: amath.",
+        help="Default language. Can be `TEX` (LaTeX) or `AMATH` (AsciiMath). Default: amath.",
         choices=("tex", "amath"),
     )
 
@@ -50,7 +50,7 @@ def parse_args():
 
     p.add_argument(
         "--default-positioning",
-        help='The raw svg, placed in the asciidoc document, usually gets rendered slightly above the line base (the baseline that characters which don\'t have lower parts (like "y" or "j" are above). Fortunately, Mathjax provides a "style" attribute in the svg (in the form of CSS), which is normally used by browsers to vertically align the math characters. I figured out a way to read this, process it, and achieve a similar effect in pdfs. The idea is that for simple symbols, like $x$, you usually want to position it. However, when you have a fraction ($\frac{a}{b}$), it usually looks better unpositioned. This option controls the default positioning for cells. Default: position.',
+        help=r'The raw svg, placed in the asciidoc document, usually gets rendered slightly above the line base (the baseline that characters which don\'t have lower parts (like "y" or "j" are above). Fortunately, Mathjax provides a "style" attribute in the svg (in the form of CSS), which is normally used by browsers to vertically align the math characters. I figured out a way to read this, process it, and achieve a similar effect in pdfs. The idea is that for simple symbols, like $x$, you usually want to position it. However, when you have a fraction ($\frac{a}{b}$), it usually looks better unpositioned. This option controls the default positioning for cells. Default: position.',
         choices=("position", "dont_position"),
     )
 
@@ -61,13 +61,13 @@ def parse_args():
 
     p.add_argument(
         "--default-alignment",
-        help="This option controls the default *horizontal* alignment of *block* cells. In particuar, it uses Asciidoc's image:...[align=(left|center|right)] API. Default: center.",
+        help="This option controls the default *horizontal* alignment of *block* cells. In particuar, it uses Asciidoc's `image:...[align=(left|center|right)]` API. Default: center.",
         choices=("left", "center", "right"),
     )
 
     p.add_argument(
         "--default-max-lines",
-        help="To ensure that you don't forget to close a cell, there is an option to set the maximum number of lines that a cell can have. This option sets the default value, but it can be overridden: as `$$max_lines=10\nx\n$$`. Max lines option (either through CLI or through a cell attribute) has no effect on inline cells, since they span just one line. Default: 6.",
+        help=r"If you forget to close a cell, it can be difficult to find the culprit. To prevent this, there is an option to set the maximum number of lines that a cell can have. This option sets the default value, but it can be overridden: as `$$max_lines=10\nx\n$$`. The `max_lines` option (set either through CLI or through a cell attribute) has no effect on inline cells, since they span just one line. Default: 6.",
     )
 
     p.add_argument(

adoc_math/_common/b_types.py

@@ -1,4 +1,4 @@
-from .c_constants import *
+from .a_imports import *
 
 OptionsRaw = NewType("OptionsRaw", str)
 OptionRaw = NewType("OptionRaw", str)

adoc_math/_common/c_constants.py

@@ -1,4 +1,4 @@
-from .a_imports import *
+from .b_types import *
 
 LOGGING_LEVEL = logging.DEBUG
 

adoc_math/_common/d_exceptions.py

@@ -1,4 +1,4 @@
-from .b_types import *
+from .c_constants import *
 
 
 class AdocMathException(Exception):

example/adoc-math-example.pdf

@@ -1,6 +1,6 @@
 // Header
 # Example
-:pdf-page-size: 9in x 17in
+:pdf-page-size: 9in x 17.5in
 :pdf-theme: pdf-theme.yml
 :stem:
 
@@ -20,19 +20,24 @@ The purpose of this example is to compare {adoc-math} and {adoctor-math}, and to
 We are about to discuss the famous <<cauchy-schwarz-ineq>>.
 
 *Theorem {counter:counter-thms} (Cauchy-Schwarz Inequality)* Let
-$n$ vertical_align_offset = -0.4ex
+// $n$ vertical_align_offset = -0.4ex
+image:imgs/adoc-math/a_inline_amath_n_f5d15920.svg[]
 be a non-negative integer, and let
-$a_0, a_1, ..., a_n,$ vertical_align_offset = -0.7ex
-$b_0, b_1, ..., b_n in bbb "R"$ 
+// $a_0, a_1, ..., a_n,$ vertical_align_offset = -0.7ex
+image:imgs/adoc-math/a_inline_amath_a_0a_7458f93c.svg[]
+// $b_0, b_1, ..., b_n in bbb "R"$ 
+image:imgs/adoc-math/a_inline_amath_b_0b_986ceb00.svg[]
 where
-$bbb "R"$
+// $bbb "R"$
+image:imgs/adoc-math/a_inline_amath_bbbR_34f68880.svg[]
 is the set of real numbers. It follows that:
 
 [#cauchy-schwarz-ineq]
 .Cauchy-Schwarz Inequality
-$$
-(a_0^2 + a_1^2 + ... + a_n^2)(b_0^2 + b_1^2 + ... + b_n^2) ≥ (a_0b_0 + a_1b_1 + ... + a_nb_n)^2
-$$
+// $$
+// (a_0^2 + a_1^2 + ... + a_n^2)(b_0^2 + b_1^2 + ... + b_n^2) ≥ (a_0b_0 + a_1b_1 + ... + a_nb_n)^2
+// $$
+image::imgs/adoc-math/b_block_amath_(a_0_6354bc50.svg[align=center]
 
 ### `asciidoctor-mathematical`
 
@@ -66,7 +71,8 @@ a|
 ----
 a|
 [.text-center]
-$a/b$
+// $a/b$
+image:imgs/adoc-math/a_inline_amath_ab_dd460eca.svg[]
 a| 
 * The default language is {amath}.
 * Inline cells start with a `$`, and end with a `$`.
@@ -79,7 +85,8 @@ a|
 ----
 a|
 [.text-center]
-$a/b$ amath
+// $a/b$ amath
+image:imgs/adoc-math/a_inline_amath_ab_bbcbf77a.svg[]
 .2+a|
 * Options come after the last `$` in inline cells.
 * You can override the default language with
@@ -99,7 +106,8 @@ a|
 ----
 a|
 [.text-center]
-$\dfrac{a}{b}$ tex
+// $\dfrac{a}{b}$ tex
+image:imgs/adoc-math/a_inline_tex_dfra_c0bb0f86.svg[]
 
 // Row
 a|
@@ -109,7 +117,8 @@ a|
 ----
 a|
 [.text-center]
-$a/b$ scale = 150%
+// $a/b$ scale = 150%
+image:imgs/adoc-math/a_inline_amath_ab_3888804f.svg[]
 a|
 * You can scale your math.
 
@@ -121,7 +130,8 @@ a|
 ----
 a|
 [.text-center]
-$a/b$ vertical_align_offset = 1ex
+// $a/b$ vertical_align_offset = 1ex
+image:imgs/adoc-math/a_inline_amath_ab_db32d819.svg[]
 a|
 * You can move your math up or down.
 
@@ -134,9 +144,10 @@ sum_(i=1)^n i^3=((n(n+1))/2)^2
 {empty}$$
 ----
 a|
-$$ amath
-sum_(i=1)^n i^3=((n(n+1))/2)^2
-$$
+// $$ amath
+// sum_(i=1)^n i^3=((n(n+1))/2)^2
+// $$
+image::imgs/adoc-math/b_block_amath_sum__57ebec07.svg[align=center]
 a|
 * Block cells are written between lines of `$$`; the options will be on the first line.
 
@@ -149,9 +160,10 @@ a^2 + b^2 = c^2
 {empty}$$
 ----
 a|
-$$ amath, right
-a^2 + b^2 = c^2
-$$
+// $$ amath, right
+// a^2 + b^2 = c^2
+// $$
+image::imgs/adoc-math/b_block_amath_a2+b_c62fc84c.svg[align=right]
 a|
 * You can horizontally align block cells.
 
@@ -170,21 +182,16 @@ a|
 {empty}$$
 ----
 a|
-$$ amath, max_lines = 8
-1 +
-2 +
-3 +
-4 +
-5 +
-6 =
-21
-$$
+// $$ amath, max_lines = 8
+// 1 +
+// 2 +
+// 3 +
+// 4 +
+// 5 +
+// 6 =
+// 21
+// $$
+image::imgs/adoc-math/b_block_amath_1+2+_9f90f2f1.svg[align=center]
 a|
 * If you forget to close a cell, it can be difficult to find the culprit. To prevent this, block cells have a `max_lines` parameter (by default 6). You can override this with `max_lines=X`.
-
-
-// Row
-| sum_(i=1)^n i^3=((n(n+1))/2)^2
-a|
-// $sum_(i=1)^n i^3=((n(n+1))/2)^2$
-|===
+|===

example/post.adoc

@@ -1,6 +1,6 @@
 // Header
 # Example
-:pdf-page-size: 9in x 17in
+:pdf-page-size: 9in x 17.5in
 :pdf-theme: pdf-theme.yml
 :stem:
 
@@ -181,10 +181,4 @@ $$ amath, max_lines = 8
 $$
 a|
 * If you forget to close a cell, it can be difficult to find the culprit. To prevent this, block cells have a `max_lines` parameter (by default 6). You can override this with `max_lines=X`.
-
-
-// Row
-| sum_(i=1)^n i^3=((n(n+1))/2)^2
-a|
-// $sum_(i=1)^n i^3=((n(n+1))/2)^2$
 |===