Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make equations more REPL-friendly #101

Closed
sethaxen opened this issue Jan 23, 2020 · 4 comments
Closed

Make equations more REPL-friendly #101

sethaxen opened this issue Jan 23, 2020 · 4 comments
Assignees
Labels
documentation Improvements or additions to documentation

Comments

@sethaxen
Copy link
Member

The primary goal with the equations is to render correctly in the HTML documentation. However, when the equations are pure LaTeX, they are tough to read in the unicode, and those who are reading the code offline or using the help feature in the REPL will have a hard time reading the equations without TeX rendering software.

In my PRs, I started using unicode characters when possible. i.e., when the unicode character renders identically to the TeX character in the HTML (tested on Google Chrome). For example,

https://github.com/JuliaNLSolvers/Manifolds.jl/blob/115b3532b21892a1a4e273d98c35f99a883666b2/src/groups/group.jl#L445-L457

which renders as though it were completely written in LaTeX.

There are a few downsides to this approach I can think of. First, the resulting equations can't just be pasted into a TeX renderer. Also, it is always possible that the user is using an OS or a browser with a font that does not contain those unicode characters. I think the positives outweigh the negatives though and propose adopting this convention across the package.

@mateuszbaran
Copy link
Member

For me such mixed Unicode/LaTeX isn't much easier to read than pure LaTeX but I can see that it can help sometimes. I think we can adopt this convention.

@kellertuer
Copy link
Member

I can read LaTeX nearly as if were rendered (or to cite a movie “after some time you just see the red dress”) – but I am fine with the UTF8 idea, we can do a browser check later and let'S hope enough browsers play that game.

@kellertuer
Copy link
Member

Since we are discussion notations anyways: Maybe it's a good idea to have an overview of notation? There are quite a lot of different ways, notation is used on manifolds, for example I (otherwise, usually) use p,q,x,y,z for points, X,Y,Z,W for tangents, small greeks for cotangents, capital caligraphic for manifolds and so on. We are different here on tangents (being small letters), that's fine. But with a notation table we can also stay consistent in the docs.

@mateuszbaran
Copy link
Member

Right, we're a bit inconsistent about notation. I think we should have a documentation page that explains it.

@sethaxen sethaxen added the documentation Improvements or additions to documentation label Jan 24, 2020
@kellertuer kellertuer self-assigned this Jan 30, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

3 participants