🔖 1.0.0

Author: hacker-DOM

.gitignore

@@ -12,5 +12,8 @@ package-lock.json
 # generated on `python3 setup.py build`
 build/
 
+# generated on `python3 -m build`
+dist/
+
 # generated on `pyenv local 3.8.12`
 .python-version

MANIFEST.in

@@ -0,0 +1 @@
+include ./README.adoc

README.adoc

@@ -1 +1,146 @@
-# adoc-math
+// Header
+# adoc-math
+:toc: macro
+
+// Links
+:example: https://github.com/hacker-dom/adoc-math/raw/main/example/adoc-math-example.pdf[Example]
+:adoc: https://docs.asciidoctor.org/asciidoc/latest[AsciiDoc]
+:markdown: https://daringfireball.net/projects/markdown/[Markdown]
+:latex: https://www.latex-project.org[LaTeX]
+:adoctor: https://github.com/asciidoctor/asciidoctor[Asciidoctor]
+:adoctor-pdf: https://github.com/asciidoctor/asciidoctor-pdf[Asciidoctor-Pdf]
+:adoctorjs: https://github.com/asciidoctor/asciidoctor.js[Asciidoctor.js]
+:adoc-stem: https://docs.asciidoctor.org/asciidoc/latest/stem/[AsciiDoc STEM]
+:adoctor-pdf-stem: https://docs.asciidoctor.org/pdf-converter/latest/stem[Asciidoctor-Pdf STEM]
+:mathjax: https://github.com/mathjax/MathJax-src[MathJax]
+:katex: https://github.com/KaTeX/KaTeX[KaTeX]
+:adoc-math: https://github.com/hacker-dom/adoc-math[adoc-math]
+:adoctor-math: https://github.com/asciidoctor/asciidoctor-mathematical[asciidoctor-mathematical]
+:amath: http://asciimath.org[AsciiMath]
+
+
+toc::[]
+
+## {example}
+
+## Installation
+
+adoc-math has zero depependencies! So it's fine to install it globallyfootnote:[Theoretically, the only time this could cause issues is if you have another package which has the name adoc-math (it obviously has to have a different PyPI name, because adoc-math is already taken 😛. But this is not very likely.. )] 😛
+
+[source,bash]
+----
+pip3 install --user --upgrade adoc-math
+adoc-math-setup # will call `npm i -g mathjax@3` and `npm link`
+----
+
+## Overview
+
+### Background
+
+I think of {adoc} as a markup syntax somewhere between {markdown} and {latex}. It originated with a https://github.com/asciidoc-py/asciidoc-py[Python implementation], but afaik that isn't actively developed, and the reference implementation is {adoctor} in Ruby.
+
+{adoc} allows you to write a document and then output it in:
+
+* html ({adoctor})
+* pdf ({adoctor-pdf})
+
+and many other formats! There is even an {adoctorjs} version (an automated translation of the Ruby code to JavaScript).
+
+### LaTeX
+Putting LaTeX equations in other places than a TeX document is not so easy. There are two main libraries for this:
+
+* :mathjax:
+** It uses native browser fonts and a lot of Css to replicate {latex} in the browser.
+* :katex:
+** Similar to {mathjax}, built by Khan Academy.
+
+### 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:
+
+* 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.
+* 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
+
+That's where `adoc-math` comes in! I decided for:
+
+* a Python package that searches for naturally-looking latex cells (e.g. `$a+b$`), calls {mathjax} to create an svg, and replaces the cells with an image of the svg
+
+I couldn't use {katex} because only {mathjax} has an Svg output (see https://github.com/KaTeX/KaTeX/issues/375).
+
+Unfortunately, {mathjax} 3 doesn't come with a Node CLI package like https://github.com/mathjax/mathjax-node-cli/[MathJax 2]. So I implemented xref:./adoc_math/d_mathjax_wrapper.js[a wrapper] over the library.
+
+### Usage
+
+[cols="2*"]
+|===
+| Inline cells:
+a|
+----
+$x + y$ [...options]
+----
+
+| Block cells:
+a|
+----
+$$ [...options]
+x + y
+$$
+----
+|===
+
+For more examples, see the {example}.
+
+
+## FAQ
+
+> Why isn't `adoc-math` written in Ruby?
+
+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!
+
+> 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.
+
+> Can I reference a cell, or add a caption to a block cell?
+
+Yes! Check out the {example}.
+
+> It's annoying having to uncomment the source math to edit it.
+
+You can use a `pre-post` pattern. `pre.adoc` will be your source code, and `post.adoc` will be the output of `adoc-math` / input to `asciidoctor(-pdf)?`. Run `cpy pre.adoc post.adoc` before every invocation to `adoc-math`.
+
+> How come inline cells become part of the sentence when they are on a separate line?
+
+In {adoc}, you need to separate two blocks with at least one _empty_ line. 🙂
+
+> Does `adoc-math` work with an Html output?
+
+This first version is geared towards Pdf output. Happy to add more powerful support for Html outputs in the future (e.g., just use the native `stem:[]` macro for Html, so we can use basic {mathjax} with browser fonts and Css (instead of svgs)).
+
+> Can I use a different font?
+
+{mathjax} currently http://docs.mathjax.org/en/v3.2-latest/output/fonts.html[doesn't provide support for multiple fonts].
+
+> Can I make my math thinner/thicker?
+
+The created svgs have a property called `stroke-width` that can adjust this. Unfortunately, it is currently set to 0, so it is not possible to make it thinner. In theory it should be possible to make it *thicker* by increasing that value. xref:./adoc_math/e_svg_transforming.py[svg_transforming.py] would be the place for that; or create an issue and I'll add it.
+
+## Debugging
+
+> I get a MODULE_NOT_FOUND error.
+
+MathJax probably cannot be found. Try running `adoc-math-setup`.
+
+> My AsciiMath fractions are too large!
+
+It seems that {amath} interprets fractions in `displaystyle` rather than `textstyle` (`\dfrac{}{}` rather than `\tfrac{}{} or even `\frac{}{}`, see https://tex.stackexchange.com/a/135395/31626[StackExchange]).
+
+I haven't found a good solution to this yet. If you have any ideas, please let me know! Note that if you have a singleton fraction (`$a/b$ amath`) you can scale it down with `$a/b$ amath, scale = 60%` (or just use `tex`).

adoc_math/__main__.py

@@ -20,7 +20,9 @@ def parse_args():
     )
 
     p.add_argument(
-        "target_files", help="List of files to run `adoc-math` on.", **list_of_files
+        "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. 🤟🚀",
+        **list_of_files,
     )
 
     p.add_argument(
@@ -35,17 +37,38 @@ def parse_args():
         **list_of_files,
     )
 
-    # p.add_argument("--default-alignment", help="Default alignment")
-
     p.add_argument(
         "--default-lang",
-        help="Default language. Can be TEX (LaTeX) or AMATH (AsciiMath).",
+        help="Default language. Can be TEX (LaTeX) or AMATH (AsciiMath). Default: amath.",
+        choices=("tex", "amath"),
+    )
+
+    p.add_argument(
+        "--default-scale",
+        help="Default scale. This option scales your svgs width and height (in `ex` units). Note that Asciidoctor does not provide a good API for scaling svgs - you can specify a fixed width, but cannot scale by a factor. By default, the math is a little bit too big (a little larger than surrounding text) - at least on the default Asciidoc theme. As such, the default is 90%%. Default: 90%%.",
+    )
+
+    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.',
+        choices=("position", "dont_position"),
+    )
+
+    p.add_argument(
+        "--default-vertical-align-offset",
+        help="This option allows to specify an offset to the `vertical-align` style explained above. For example, capital letter (`P`) seem to get positioned nicely, but lowercase letters (`p`) are not; I found that `vertical_align_offset = -0.4ex` works well for singleton lowercase characters. Note that this option won't have any effect if `positioning` is set to `dont_position`. Default: 0.0ex.",
+    )
+
+    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.",
     )
 
     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.",
     )
+
     p.add_argument(
         "--filename-snippet-length",
         type=int,
@@ -76,9 +99,9 @@ def main():
     args = parse_args()
 
     # The idea here is that the arguments specified in `parse_args` will have value
-    # None if they are not specified by the user. If we just use something like `i_impl.AdocMath(default_alignment=args.default_alignment`
+    # None if they are not specified by the user. If we just use something like `i_impl.AdocMath(default_positioning=args.default_positioning`
     # etc (for all other arguments), then we'll lose the default values
-    # as specified in AdocMath (e.g. default_alignment = Alignment.ALIGN)
+    # as specified in AdocMath (e.g. default_positioning = Positioning.POSITION)
     # So instead, let's just filter out those that are None
     # (more specifically those that are falsy), and pass in the rest
     kwargs = {key: val for key, val in vars(args).items() if val}

adoc_math/_common/b_types.py

@@ -13,6 +13,8 @@
   * this follows e.g. python ast's lineno
 * linenum is line number 1-indexed
   * this follows e.g. editors (e.g. vs code)"""
+Scale = NewType("Scale", int)
+VerticalAlignOffset = NewType("VerticalAlignOffset", float)
 MaxLines = NewType("MaxLines", int)
 LineInFile = NewType("LineIFile", str)
 Command = NewType("Command", str)
@@ -24,6 +26,9 @@
 SnippetPart = NewType("SnippetPart", str)
 DiffContent = NewType("DiffContent", str)
 LinesInserted = NewType("LinesInserted", int)
+SvgDocument = NewType("SvgDocument", xml.dom.minidom.Document)
+Svg = NewType("Svg", xml.dom.minidom.Element)
+Ex = NewType("Ex", float)
 
 
 class OutputMode(str, enum.Enum):
@@ -36,14 +41,23 @@ class Lang(str, enum.Enum):
     TEX = "TEX"
 
 
-# class Alignment(str, enum.Enum):
-#     ALIGN = "ALIGN"
-#     DONT_ALIGN = "DONT_ALIGN"
+class Positioning(str, enum.Enum):
+    POSITION = "POSITION"
+    DONT_POSITION = "DONT_POSITION"
+
+
+class Alignment(str, enum.Enum):
+    LEFT = "LEFT"
+    CENTER = "CENTER"
+    RIGHT = "RIGHT"
 
 
 class Opts(NamedTuple):
     lang: Lang
-    # alignment: Alignment
+    scale: Scale
+    positioning: Positioning
+    vertical_align_offset: VerticalAlignOffset
+    alignment: Alignment
     max_lines: MaxLines
 
 
@@ -63,3 +77,35 @@ class InlineCell(NamedTuple):
 
 
 Cell = Union[InlineCell, BlockCell]
+
+
+class SvgAttributesRaw(NamedTuple):
+    style: str
+    width: str
+    height: str
+    viewbox: str
+
+
+class ViewBox(NamedTuple):
+    # https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/viewBox
+    min_x: Ex
+    min_y: Ex
+    width: Ex
+    height: Ex
+
+    def __str__(s):
+        els = []
+        for el in s:
+            if el.is_integer():
+                els.append(int(el))
+            else:
+                els.append(el)
+        a, b, c, d = els
+        return f"{a} {b} {c} {d}"
+
+
+class SvgAttributesParsed(NamedTuple):
+    vertical_align: Ex
+    width: Ex
+    height: Ex
+    viewbox: ViewBox

adoc_math/_common/c_constants.py

@@ -3,14 +3,14 @@
 LOGGING_LEVEL = logging.DEBUG
 
 # Note: whitespace before $$ is not allowed
-REGEX_BLOCK_OPENING_TAG_SRC = r"^\$\$(?P<opts>\S*)\s*$"
+REGEX_BLOCK_OPENING_TAG_SRC = r"^\$\$(?P<opts>.*?)\s*$"
 REGEX_BLOCK_OPENING_TAG = re.compile(REGEX_BLOCK_OPENING_TAG_SRC)
 
 # Note: whitespace before $$ is not allowed
 REGEX_BLOCK_CLOSING_TAG_SRC = r"^\$\$\s*$"
 REGEX_BLOCK_CLOSING_TAG = re.compile(REGEX_BLOCK_CLOSING_TAG_SRC)
 
-REGEX_INLINE_SRC = r"^\$(?P<content>.*?)\$(?P<opts>\S*)\s*$"
+REGEX_INLINE_SRC = r"^\$(?P<content>.+?)\$(?P<opts>.*?)\s*$"
 REGEX_INLINE = re.compile(REGEX_INLINE_SRC)
 
 REPO = "https://github.com/hacker-dom/asciidoc-mathjax"

adoc_math/_common/e_utils.py

@@ -100,3 +100,19 @@ def change_cwd(path: Union[plib.Path, str]):
         yield
     finally:
         os.chdir(orig_cwd)
+
+
+def lshave(string: str, sub: str) -> str:
+    if string.startswith(sub):
+        return string[len(sub) :]
+    else:
+        return string
+
+
+def rshave(string, sub: str) -> str:
+    if not isinstance(string, str):
+        string = str(string)
+    if string.endswith(sub):
+        return string[: len(string) - len(sub)]
+    else:
+        return string

adoc_math/a_helpers.py

@@ -9,8 +9,11 @@ class Helpers:
     # endregion
 
     # region default cell options
-    # default_alignment: Alignment
     default_lang: Lang
+    default_scale: Scale
+    default_positioning: Positioning
+    default_vertical_align_offset: VerticalAlignOffset
+    default_alignment: Alignment
     default_max_lines: MaxLines
     # endregion