LaTeX Integration and Equation Numbering

[arnavs]

We're (cc: @jlperla, @Nosferican) looking into using Weave, and the system looks great except for a few snags with LaTeX:

• Equations natively display without numbers in HTML, either using \equation or \align. When we try to refer to them (by labeling and calling the label) we get a ???. We can get around this by manually numbering equations with \tag{}, but that feels hacky.

For example:

We can define an anonymous set of equations as such: 

```math
\begin{align}
a^2 + b^2 &= c^2 \label{pythagorean} \\
e^{i \pi} + 1 &= 0 \\ 
\mathbb{E}[mr] &= 1 \\ 
\end{align}
```

\begin{equation}
1 + 2 = 3 \label{truism}
\end{equation}

There aren't any numbers, and referring to \eqref{pythagorean} or \eqref{truism} breaks. 

• Sometimes we have redundant math-wrapping. For example, we need the math tags above for HTML output, but these tags render into LaTeX as something like $$\begin{align} ... \end{align}$$.

• If you just splat the code and forget about HTML, there seem to be some parsing errors, e.g. {\textbackslash}begin\{align\}...

We are calling Weave in Julia 0.7 as such:

weave("economics_examples.jmd", out_path = :pwd, doctype = "md2html", template = "custom_html.tpl") # HTML output
weave("economics_examples.jmd", out_path = :pwd, doctype = "md2tex") # TeX output

Let me know if there's anything different we should be doing, or if you have any thoughts.

[mpastell]

Markdown writers just pass the latex through to Mathjax and xelatex and they are slightly inconsistent in this case.

Markdown to html writer is Weave and if you have ideas how to change it you can open a pull request. (See:) https://github.com/mpastell/Weave.jl/blob/246f7eef62102d985332722034877511ccf8e16c/src/Markdown2HTML.jl#L158

For Latex Weave uses the writer in stdlib https://github.com/JuliaLang/julia/blob/master/stdlib/Markdown/src/render/latex.jl , if needed we could also add a custom Latex writer to Weave.

I think splatting the code works as expected, it is parsed as a paragraph and special characters are escaped from output.

You may also want to check whether pandoc markdown works better for you than the Julia variant.

[arnavs]

Thanks for investigating. Will experiment and get back to you. The equation numbers are a key feature for us, so hopefully we can get this to work.

[mpastell]

You can actually get the equation numbers by adding TeX: { equationNumbers: { autoNumber: "AMS" } } to Mathjax config in template. Additionally you need to escape any Latex in text, so use

There aren't any numbers, and referring to ``\eqref{pythagorean}``...

[arnavs]

Perfect, thank you.

[mpastell]

I think it actually would make sense to always output ```math blocks as align in both html and latex output. This is easy to change in the html writer, but for Latex we might need add a to a custom Latex writer to Weave (also not hard, but takes more work).

Going further it could also make sense to parse raw Latex so that you wouldn't need to escape equations.

[Nosferican]

Aye. I was using Pandoc to get the citations to work properly with the bib file and worked wonderfully with TeX and HTML (less so with IPYNB). Had some issues with Unicode for TeX or PDF (was using LuaLaTeX). We will play with those again and hopefully can clean some examples to help others using Weave. Thanks.

[mpastell]

There has been some discussion on citations in Discourse https://discourse.julialang.org/t/citations-in-docs/5066/35 , it would be great if there was Julia package for working with citations. Julia markdown parser is relatively straightforward to extend in order to parse citations from text.

[mpastell]

Does #143 fix this issue or is something more needed?

[arnavs]

Will test rn and get back to you.

[arnavs]

Getting an error when I run (and looks like the Travis build for the align branch broke, maybe for the same reason).

$ julia "c:\Users\Arnav Sood\Desktop\computing_and_datascience\julia_sandbox\Weave\Weave.jl"
ERROR: LoadError: UndefVarError: endof not defined
Stacktrace:
 [1] parse_inline(::String, ::Regex) at C:\Users\Arnav Sood\.julia\dev\Weave\src\readers.jl:306
 [2] Type at C:\Users\Arnav Sood\.julia\dev\Weave\src\chunks.jl:57 [inlined]
 [3] parse_doc(::String, ::Weave.MarkupInput) at C:\Users\Arnav Sood\.julia\dev\Weave\src\readers.jl:119
 [4] parse_doc(::String, ::String) at C:\Users\Arnav Sood\.julia\dev\Weave\src\readers.jl:79
 [5] read_doc(::String, ::Symbol) at C:\Users\Arnav Sood\.julia\dev\Weave\src\readers.jl:58
 [6] #weave#10(::String, ::Symbol, ::Symbol, ::Dict{Any,Any}, ::Symbol, ::String, ::Nothing, ::String, ::Symbol, ::Bool, ::Nothing, ::Nothing, ::Nothing, ::Array{String,1}, ::String, ::typeof(weave), ::String) at C:\Users\Arnav Sood\.julia\dev\Weave\src\Weave.jl:100
 [7] (::getfield(Weave, Symbol("#kw##weave")))(::NamedTuple{(:out_path, :doctype),Tuple{Symbol,String}}, ::typeof(weave), ::String) at .\none:0
 [8] top-level scope at none:0
 [9] include at .\boot.jl:317 [inlined]
 [10] include_relative(::Module, ::String) at .\loading.jl:1038
 [11] include(::Module, ::String) at .\sysimg.jl:29
 [12] exec_options(::Base.JLOptions) at .\client.jl:229
 [13] _start() at .\client.jl:421
in expression starting at c:\Users\Arnav Sood\Desktop\computing_and_datascience\julia_sandbox\Weave\Weave.jl:19

[mpastell]

The error you got is due to a deprecation in parsing inline code and also exists in master, I fixed it in align branch. Travis failure is expected as I haven't updated tests for new format.

[arnavs]

Perfect, thanks.

[arnavs]

@mpastell This works great/fixes our issues. Thanks for being so on top of this.

[mpastell]

Thanks, glad that it works and it was very minor fix. I'll tag a release with this patch.

[mpastell]

FYI: Weave no longer adds align to math blocks automatically so you need to do it yourself from now on. See: #182 .