LaTeX recommendations #15

necaisej · 2021-03-11T16:55:10Z

The HTML tag using the codecogs renderer allows for the most readable latex formula using symbols that do not need to be percent encoded in the url. In the IDE, the url may contain spaces and render just fine, but any spaces will need to be replaced by %20 for proper rendering in GitHub.

JoelPasvolsky · 2021-03-11T17:32:04Z

README.md

@@ -55,6 +55,26 @@ This is the place to:
 Note: there is no need to repeat everything that is already well-documented in
 the code.

+If you would like to include math equations to explain parts of your code or repo,
+it is recommended to use an external renderer and insert prepared svg files here.
+For example, it's possible to insert a link to the online CodeCogs equation editor;


The quoted links will show up on the rendered README looking like a broken links at first glance.
Why not something like this,

"You can include explanatory math equations in either of the following two ways:

Link to the online CodeCogs equation editor as shown below

Link to an image in the in the readme_imgs folder as shown below

Users will look at the raw REAME file to see the formats.

That's a fair suggestion - I have slight preference for being overly explicit with what we are recommending so that it's painfully obvious to users how to reproduce what's on the readme. It doesn't seem to me that the quoted links would look broken given the text around them, but I will defer on this.

JoelPasvolsky · 2021-03-11T17:35:44Z

README.md

@@ -55,6 +55,26 @@ This is the place to:
 Note: there is no need to repeat everything that is already well-documented in
 the code.

+If you would like to include math equations to explain parts of your code or repo,
+it is recommended to use an external renderer and insert prepared svg files here.


We've also used PNG images. Do you see a quality problem with those or another reason to require SVG? Perhaps we can say image files and note that SVG is preferred but not mandatory?

PNG files could be ok, but it seems easy enough to me that we pick a standard for uniformity. SVG will generally always be higher quality and more flexible - GIF and PNG etc. will have pixelation issues at different resolutions.

I was thinking of a use case where a contributor is using typical Windows tools to snapshot an equation from a PDF, for example. These usually have PNG, JPEG, etc but not SVG.
I agree that a high-res image is desirable but just worry that if creating an SVG is an obstacle to some users, they might forgo an equation, and I'd rather a lower quality image than no equation. So far I haven't seen low quality images with PNG. We would comment on those in a PR. (I typically view these in GitHub so maybe it's more problematic in the IDE.)

That's a good point. I think the main quality issues I've seen are with GIF rendered equations, but in general I think uniform SVG would be a good look. A middle ground is to say in the readme/contributing guide any image file, and to have someone on our side take responsibility for translating anything that gets uploaded which isn't SVG? Using the url renderer it's as simple as typing out the Latex.

JoelPasvolsky · 2021-03-11T17:37:42Z

README.md

@@ -55,6 +55,26 @@ This is the place to:
 Note: there is no need to repeat everything that is already well-documented in
 the code.

+If you would like to include math equations to explain parts of your code or repo,
+it is recommended to use an external renderer and insert prepared svg files here.
+For example, it's possible to insert a link to the online CodeCogs equation editor;


We've used MathJax previously, I'm not familiar with CodeCogs -- @silviacorbellaro

My understanding is that MathJax is less supported in GitHub rendering, but I am not really familiar with them. Any url renderer would be acceptable and the preference is just for any that can parse non-percent encoded symbols for readability. Potentially relevant exchange on SO:

https://stackoverflow.com/questions/11256433/how-to-show-math-equations-in-general-githubs-markdownnot-githubs-blog

Folks, does D-Wave already have a license for CodeCogs? I took a brief look and there are a few options to buy a license to the tool. I can't visualize the license text without signing up. What I can see is that there is a separate licence for commercial use, it's just more expensive.

hhtong · 2021-03-11T17:40:53Z

README.md

+renders the following expression.
+
+
+<img src="https://latex.codecogs.com/svg.latex?\large%20x_{ik}+x_{jk}-2x_{ik}x_{jk}">


This does not show up well in dark mode. In our conversation, you had talked about a flag that would allow for this to automatically show up in white/black depending on the mode. If we're going to suggest this method, it'd be good to mention.

Yes unfortunately I have not found a satisfying way to keep readable latex in the readme and render well in both light and dark mode. It looks like GitHub is actively working on automating this as of about two months ago. https://github.community/t/support-theme-context-for-images-in-light-vs-dark-mode/147981

Stopgaps for this we recommend could easily be made obsolete, so my current opinion has changed to that it's actually not worth supporting darkmode on repos until GitHub-side support has stabilized... Let me know if that makes sense.

Hmm, I think this could be a problem in the IDE, which defaults to dark mode. Have you taken a look at how this looks there?

What about just including a white background in the image instead of transparent? I think that's the way most of our current equation images are formatted. It may not be the ideal look in dark mode, but at least it is visible.

I have, and my conclusion was to set my IDE to light mode. I can't tell which markdown renderer is used behind the scenes in the IDE - I was wrong in my assumption that it was similar to Jupyter and it seems it has most but not all of the issues of GitHub rendering.

I don't think we can expect users to set their IDE to a different mode.

What about just including a white background in the image instead of transparent? I think that's the way most of our current equation images are formatted. It may not be the ideal look in dark mode, but at least it is visible.

This is the main stopgap that I was referring to - I think it is more beneficial to have editable latex so we can easily update equations than to require inserting images pre-rendered with white backgrounds to support GitHub darkmode while it is under development unfortunately. If there is a url renderer that allows white background that would be ideal.

Perhaps I’m missing something here, but what I’m gathering is that there is no current solution for displaying latex via a link to CodeCogs on dark mode (unless there is a url renderer w/ white background?). If that is the case, then I don’t think we should be recommending this as an option right now. This obviously could change later, but right now I’m inclined to just recommend SVG and remind users to use a white background.

One benefit of using the HTML tag might be the ability to add background colors ourselves. I'm currently testing including the tag style="background-color:white" etc.

Because github flavored markdown has such a strict sanitization filter, that was not possible; but the latex command \pagecolor{white} works just fine in the url renderer and keeps the whole insertion sufficiently unobtrusive and readable in my mind.

So now it looks alright in the IDE darkmode, though I wish there was a way to add a thin white border. In darkmode the last character in the equation is just barely frustrating to look at. I don't know a way to do this currently mainly because of the filter.

necaisej · 2021-03-16T20:43:19Z

Added color inversion which will be picked up in IDE; this renders white text transparent background SVG of equations in Leap, and black text transparent background SVG of equations on Github.

hhtong · 2021-03-16T21:00:03Z

README.md

+
+`![Expression](readme_imgs/expression.svg)`
+
+![Expression](readme_imgs/expression.svg)


Can we add a white background to this svg?

Yes - just one parameter in the svg file itself. Would you suggest doing so to make it readable on the IDE or in github darkmode? My proposal is to support darkmode only in the IDE by using the invert filter. I suppose we could axe the ![]() example and show that the html img insert method works with relative paths as well, keeping the same invert flag.

hhtong · 2021-03-16T21:09:19Z

README.md

+If you would like to include math equations to explain parts of your code or repo,
+it is recommended to use an external renderer and insert prepared svg files here.
+For example, it's possible to insert a link to the online CodeCogs equation editor;
+below includes syntax to be read on darkmode by default in D-Wave's [Leap IDE](https://ide.dwavesys.io).


Would putting these options in bullet points make this a bit more readable? (one option, one point)

JoelPasvolsky · 2021-03-16T21:14:03Z

README.md

@@ -55,6 +55,25 @@ This is the place to:
 Note: there is no need to repeat everything that is already well-documented in
 the code.

+If you would like to include math equations to explain parts of your code or repo,


I suggest this section have a subheader "Adding Equations"

JoelPasvolsky · 2021-03-16T21:17:26Z

README.md

+If you would like to include math equations to explain parts of your code or repo,
+it is recommended to use an external renderer and insert prepared svg files here.
+For example, it's possible to insert a link to the online CodeCogs equation editor;
+below includes syntax to be read on darkmode by default in D-Wave's [Leap IDE](https://ide.dwavesys.io).


I think it would more accessible to give two options:

using online renderer

Inserting an image file
And then explain in a footnote that the online renderer formulation has the filter:invert(1) part to look good in Leap's IDE, where darkmode is the default

In the second point, it would also be good to recommend using a white background.

Transparent background is actually preferable if the invert filter is used, since the IDE darkmode background is actually quite noticeably not jet black. It will not look absolutely disgusting though, so I think balancing what looks best with accessibility could be to not express a preference on user image background.

Perhaps it would be good to just note that the contributor should make sure that the equation is readable on both GitHub and the IDE.

I'd word that as taking into consideration that some users such as IDE users might have dark backgrounds rather than phrasing it as a requirement that contributors ensure readability in multiple environments, that seems a burdensome requirement on 3rd-party contributors

randomir · 2022-01-04T19:37:03Z

README.md

+it is recommended to use an external LaTeX renderer, or insert pre-rendered images in the repo.
+For example, it's possible to insert a link to the online CodeCogs equation editor which will


I'm not sure we want to recommend the use of external renderers (like CodeCogs). Have you confirmed this with IP/legal?

For example, CodeCogs has a fair use policy, but they require we provide a link back.

randomir · 2022-01-04T19:41:54Z

README.md

+
+The above text in markdown renders the following expression in your markdown readme.
+
+<img style="filter:invert(1)" src="https://latex.codecogs.com/svg.latex?\large\,x_{ik}+x_{jk}-2x_{ik}x_{jk}"> 


Looks like GitHub strips the filter:invert(1) style.

Maybe using mix-blend-mode would be better? The only downside is it's not supported for SVG on most mobile platforms/browsers.

necaisej added 19 commits March 10, 2021 16:12

Add equation recommendations

775a7f7

html insert syntax

4d0672e

space in link

0e31ab8

plus in link

8939c47

undo space in link

d500ebb

git renderer

3b74da0

codecogs link

5870e45

remove script

8debd84

indent in link

4c748ed

codecog

d54702f

png

ec3b2c2

https in link

7f85bbd

test img

907a6de

all options

ace4ba3

more tests

26b5c63

svg link tests

299da4a

no spaces link

484d0cd

no spaces

a125437

final link format

44422c7

arcondello requested review from hhtong and JoelPasvolsky March 11, 2021 16:57

JoelPasvolsky reviewed Mar 11, 2021

View reviewed changes

hhtong reviewed Mar 11, 2021

View reviewed changes

necaisej added 7 commits March 11, 2021 19:42

white background tags

beabf8d

white background syntax test

fbb685b

more background color tests

dd207c6

html img tag tests

dfb84ec

include alt tag

a3a2a9f

Put in code tag

466c1cc

one more test

e665bdb

necaisej added 2 commits March 13, 2021 00:16

White equation background

ad52c0d

Render inverted in IDE, transparent in GFM

ab7b730

hhtong reviewed Mar 16, 2021

View reviewed changes

JoelPasvolsky reviewed Mar 16, 2021

View reviewed changes

Adding Equations section

db3d9a6

JoelPasvolsky mentioned this pull request Mar 17, 2021

Readme LaTeX suggestion dwave-examples/distributed-computing#7

Open

hhtong mentioned this pull request Jun 2, 2021

Copy files from original repo. dwave-examples/crop-rotation#1

Merged

randomir reviewed Jan 4, 2022

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

LaTeX recommendations #15

LaTeX recommendations #15

necaisej commented Mar 11, 2021

JoelPasvolsky Mar 11, 2021

necaisej Mar 11, 2021

JoelPasvolsky Mar 11, 2021

necaisej Mar 11, 2021

JoelPasvolsky Mar 11, 2021

necaisej Mar 11, 2021 •

edited

Loading

JoelPasvolsky Mar 11, 2021

necaisej Mar 11, 2021

silviacorbellaro Mar 11, 2021

hhtong Mar 11, 2021 •

edited

Loading

necaisej Mar 11, 2021

hhtong Mar 11, 2021

mcfarljm Mar 11, 2021

necaisej Mar 11, 2021

hhtong Mar 11, 2021

necaisej Mar 11, 2021

hhtong Mar 11, 2021

necaisej Mar 11, 2021

necaisej Mar 13, 2021

necaisej commented Mar 16, 2021

hhtong Mar 16, 2021

necaisej Mar 16, 2021

hhtong Mar 16, 2021

JoelPasvolsky Mar 16, 2021

JoelPasvolsky Mar 16, 2021

hhtong Mar 16, 2021

necaisej Mar 16, 2021 •

edited

Loading

hhtong Mar 16, 2021 •

edited

Loading

JoelPasvolsky Mar 16, 2021

randomir Jan 4, 2022

randomir Jan 4, 2022 •

edited

Loading

		renders the following expression.


		<img src="https://latex.codecogs.com/svg.latex?\large%20x_{ik}+x_{jk}-2x_{ik}x_{jk}">


		`![Expression](readme_imgs/expression.svg)`

		![Expression](readme_imgs/expression.svg)

		it is recommended to use an external LaTeX renderer, or insert pre-rendered images in the repo.
		For example, it's possible to insert a link to the online CodeCogs equation editor which will


		The above text in markdown renders the following expression in your markdown readme.

		<img style="filter:invert(1)" src="https://latex.codecogs.com/svg.latex?\large\,x_{ik}+x_{jk}-2x_{ik}x_{jk}">

LaTeX recommendations #15

Are you sure you want to change the base?

LaTeX recommendations #15

Conversation

necaisej commented Mar 11, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

necaisej Mar 11, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hhtong Mar 11, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

necaisej commented Mar 16, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

necaisej Mar 16, 2021 • edited Loading

Choose a reason for hiding this comment

hhtong Mar 16, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

randomir Jan 4, 2022 • edited Loading

Choose a reason for hiding this comment

necaisej Mar 11, 2021 •

edited

Loading

hhtong Mar 11, 2021 •

edited

Loading

necaisej Mar 16, 2021 •

edited

Loading

hhtong Mar 16, 2021 •

edited

Loading

randomir Jan 4, 2022 •

edited

Loading