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

Update documentation to use MathML #26812

Closed
jabagawee opened this issue Sep 20, 2023 · 4 comments · Fixed by #26887
Closed

Update documentation to use MathML #26812

jabagawee opened this issue Sep 20, 2023 · 4 comments · Fixed by #26887

Comments

@jabagawee
Copy link

Description

The current implementation of the documentation is somewhat inconsistent with math notation. A few examples:

  1. Matrices currently vary between having and not having commas to separate elements:
    a. (without commas) https://threejs.org/docs/#api/en/math/Matrix4.makeRotationFromQuaternion
    image
    b. (with commas) https://threejs.org/docs/#api/en/math/Matrix4.makeBasis
    image

  2. Some pages are inconsistent even within the same example:
    a. https://threejs.org/docs/#api/ar/math/Matrix4.makeBasis utilizes both Arabic commas and regular commas.
    image

  3. Alignment inconsistencies:
    a. (center aligned) https://threejs.org/docs/#api/en/math/Matrix4.makeBasis
    image
    b. (left-ish aligned): https://threejs.org/docs/#api/en/math/Matrix4.makeRotationZ
    image

  4. Some sections do not have the correct formatting:
    a. https://threejs.org/docs/#api/en/math/Matrix4.makeRotationY
    image

Solution

I propose that we replace the math markup throughout the documentation with MathML, which is accepted by all major browsers (according to mdn and caniuse).

Alternatives

The alternative would be to format the <code> sections in the documentation more carefully, but I'm not so sure that this is a superior alternative.

Additional context

No response

@Mugen87
Copy link
Collaborator

Mugen87 commented Sep 20, 2023

Do you mind updating one of the code examples on a new branch with MathML so we can easier make a comparison?

@jabagawee
Copy link
Author

Is it possible to re-open issues, or do I need to file a new one? We can perform some more substitutions for MathML in the page for Matrix3. I haven't checked the docs for other pages yet, but I imagine other pages in the math/ subdirectory might also benefit.

@Mugen87 Mugen87 reopened this Oct 3, 2023
@Mugen87
Copy link
Collaborator

Mugen87 commented Oct 3, 2023

It's okay to keep the issue open until other docs pages have been updated. It was automatically closed because #26887 got merged.

@Mugen87
Copy link
Collaborator

Mugen87 commented Oct 4, 2023

I've went through the math pages and could not find more obvious places where a migration to MathML is required. I think we can close this issue now.

For the future we can keep the policy in mind to always use MathML if we want to format math related syntax in the documentation or other places. If someone spots a place where MathML would make sense, it's best to directly file a PR. A separate issue isn't relevant in this case.

@Mugen87 Mugen87 closed this as completed Oct 4, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
2 participants