kiwi0fruit / sugartex

SugarTeX is a more readable LaTeX language extension and transcompiler to LaTeX. Fast Unicode autocomplete in Atom editor via https://github.com/kiwi0fruit/atom-sugartex-completions

SugarTeX

SugarTeX is a more readable LaTeX language extension and transcompiler to LaTeX. Designed to be used instead of $formula$ insertions to markdown.

See SugarTeX documentation. Examples of input to output conversion see in this PDF.

I use Markdown with Python code blocks for document programming via Pandoctools (like R-Markdown).

Both Python and Markdown are very readable languages. Unfortunately LaTeX is not like this. So I wrote SugaTeX extension+transpiler that is highly readable. In order to achieve this it heavily uses Unicode so that SugarTeX install instructions even have recommended monospace font fallback chains. And more: SugarTeX Completions Atom package helps write all that Unicode in a moment.

I am trying to incorporate LaTeX into .md using the Markdown Philosophy of “you should write something that's readable as plain text, without compilation, also”.

Install

Install as part of Pandoctools - convenient interface and works out of the box.

Via conda:

conda install -c defaults -c conda-forge sugartex

Via pip:

pip install sugartex

Atom editor with full Unicode support

Highly recommended to install Atom editor as it's the best for markdown.

Atom is perfect for Unicode rich texts. But you need to install some fonts first. See this instruction how to install recommended font fallback chains for Unicode support.

SugarTeX Completions for Atom

Install SugarTeX Completions package for easy typing SugarTeX and lots of other Unicode characters. (it's incompatible with latex-completions package).

In the SugarTeX documentation appropriate shortcuts for SugarTeX Completions for Atom are given.

Usage examples

Example of input to output conversion is at the end of [this PDF].

Windows:

@echo off
chcp 65001 > NUL
set PYTHONIOENCODING=utf-8
set PYTHONUTF8=1

type doc.md | ^
pre-sugartex | ^
pandoc -f markdown --filter sugartex -o doc.md.md

Unix (convert bash script to use like ./convert doc.md):

#!/bin/bash
export PYTHONIOENCODING=utf-8
export PYTHONUTF8=1

cat "$@" | \
pre-sugartex | \
pandoc -f markdown --filter sugartex -o "$@.md"

(or pandoc -f markdown --filter sugartex --to docx+styles -o "[email protected]")

Or splitting Pandoc reader-writer:

export PYTHONIOENCODING=utf-8

cat doc.md | \
pre-sugartex | \
pandoc -f markdown -t json | \
sugartex --kiwi | \
pandoc -f json -o doc.md.md

Panflute scripts are also installed so you can use it in default Panflute automation interface in metadata or in recommend panfl CLI:

• panfl sugartex --to markdown,
• panfl sugartex.kiwi -t markdown.

sugartex's Issues

Hacker News discussion

https://news.ycombinator.com/item?id=17172953

What to do with the need to change symbols across set of documents?

Came from this discussion:

It seems wrong idea to add special macros support to SugarTeX. If using Unicode macros is OK. Then better use them and be happy. UPD Seems like there are problems with Unicode macros names... So it needs investigation how easy is to tweak SugarTeX (add custom simple pre-replacements). It's definitely tweakable, but how easy to tweak?

DELETED

API questions

• Why do I export sugartex if it's private? unfinalized_sugartex? auto-finalize if use stex?
• Remove Consolas specific code as I now use other fonts.
• finalize better than ready (nope)

Add isFixedPitch flag to OpenMono

See discussion google/fonts#225

I would greatly appreciate patching Open Mono with this flag, it greatly enhances the usability of this font for coding.

How do you add a yaml header?

I'm trying to use sugartex to write an article but how do you add a yaml header? From the 'Usage' section I'm using this to render the pdf to which I added the last line:

#!/usr/bin/env bash
export PYTHONIOENCODING=utf-8

cat "$1".md | \
pre-sugartex | \
pandoc -f markdown -t json | \
sugartex --kiwi | \
pandoc -f json -o "$1".md.md | \
pandoc --pdf-engine=lualatex -F pandoc-eqnos -F sugartex -H "/path/head.tex" --number-sections -f markdown "$1".md.md -o "$1".pdf

However, I don't understand how to add a yaml header specifying parameters for LaTeX like title, author, date, margins, fonts, toc info.

1. Adding -H '/path/header.yml to the last line exits with 'file has no \begin{document}'
2. Writing the yaml header directly into the source file $1.md has no effect as it doesn't get output in the pdf
3. Adding it, still through -H '/path/header.yml, in pandoc -f json -o "$1".md.md | \ doesn't seem to have any effect as it doesn't get included in the pdf or a tex file if I output to tex instead of pdf.

Features to add

• Change main font-size in the Pandoctools examples as now it's too big.
• find out WTF is with escaped low tick in the Markdown documentation. Does it mean that Markdown is incorrect and PDF should always be read?
• Add new styles: bi, ib, tbi, tib, f (fr), bb (bbold), s (sans), si, sb, sbi, sib, sβ
• Update STIX Two Math for Roboto Mono and Consolas in Open Fonts (do not rename - be backward compatible)
• Write that DejaVu Sans Mono has only sans regular math letters - mind it. If DejaVu Sans Mono is before STIX Two Math in the fallback chain sans regular math letters would be of different style. Consider deleting them. Check DejaVu Serif and DejaVu Sans.
• Add to Atom: \_L\white=>𝅊𝅌; \_L\black=>𝅋𝅍. Rename: \_L\small into \_L\tone; \^r\small into \^r\tone.
• Write about turning ON sugartex.mjx_hack() when using stex function in python. Also add sugartex.default() that reverts all hacks and mathrm.
• Add right version of U+2215 ∕ Division slash to the "SugarTeX" font. This way I can create special font that is Roboto Mono (or may be Source Code Pro) ripped of all characters except whitespace and dash characters. And add ALL whitespace and dash characters to this font. Make distinction between short and long dashes like in Source Code Pro (but do not have 2-width characters!). Name it "SugarTeX". And with fallback chain 'SugarTeX', 'Source Code Pro' I won't need Sourcing Code Pro font. Fixing whitespace characters in Roboto Mono and Inconsolata also won't be needed.
• Move postfix unary operators changed from one-character to two character to another section.
• Remove combining symbols from the SugarTeX:
  • { ⃗x} / {⃗x}→\mathbf{x}, a x ⃗ → a \vec{x }, a x ⃑ → a \overrightarrow{x }. Replace them with x𝀁𝂗 (arrow), x𝂗 (\vec), x𝂏𝀀 (arrow). Atom: \^<-=>𝂏; \^->=>𝂗; \_<-=>𝃵; \_<-\alt=>˿; \^<-\alt=>𝂏𝀀; \^->\alt=>𝀁𝂗.
  • ⃗←\^->,; ⃑←\^->\har (Atom package)
  • map x¯ macron U+00AF into \bar{x} together with ˉ modifier letter macron U+02C9
  • Fix overline in the "SugarTeX" font! ‾ U+203E overline. Characters should join like in underline.
  • consider changing \^_\small, \^-\small, \^_, \^- in Atom. May be use \^-\min for real superscript minus (⁻) and \^-\overline for overline (‾) and remove \small.
  • combiantions from Atom with combining vector -- move to the ^^ section ONLY. Make sure that there is no combining characters in ^ section.
• Add prefix unary "escape train" operator that simply adds \ before each character (until it stops). It should work before other operators. Can be escaped: \⸌. Test: y⸌∕ x. Add superscript slash ⸍ to Atom. ⸌ ← \^\; ⸍ ← \^/; \_/=>⸝; \_\=>⸜.
• Create monospacified DejaVu Sans as it has more symbols than DejaVu Sans Mono.

Check big operators, test MathML. Other things to consider

• see http://asciimath.org/#syntax for big operators and cancel(x).
  I think the big operators support is already in SugarTeX but this still needs testing and investigating.
• find out about compilance with MathML. So that to mark what SugarTeX are convertable to MathML. May be even tailor output for LaTeX, MathML, MathJax, MS Word 2007+ separately (or find the most common denominator).
• Remove extra {} brackets? Consider cleaning up likes of {{x}} but not {{x}+1}