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

Replace ⇔ by ↔ in documentation #52078

Merged
merged 2 commits into from
Jan 24, 2024

Conversation

fingolfin
Copy link
Contributor

There is no HTML entity ⇔ and accordingly all the usual browsers (Chrome, Firefox, Safari) don't render it.

My guess is that there is confusion because GitHub supports ⇔ and shows it as ⇔ (and ↔ as ↔).

But here is for example what Firefox shows:
Screen Shot 2023-11-08 at 14 02 01

This patch could be backported to 1.9 and 1.10.

There is no HTML entity ⇔ and accordingly all the usual browsers
(Chrome, Firefox, Safari) don't render it special.
@brenhinkeller brenhinkeller added the docs This change adds or pertains to documentation label Dec 8, 2023
@fingolfin
Copy link
Contributor Author

Any particular reason this isn't merged? (And backported)?

@DilumAluthge
Copy link
Member

Hmmm. I just looked at the PDF docs for the Buildkite build of this PR, and it's still not rendering correctly. See page 505 (which is actually page 520 of the PDF).

To get the PDF, go to the Buildkite build for this PR, and then go to the pdf_docs_build job, and then click on the "Artifacts" tab, and then click on the TheJuliaLanguage.pdf artifact.

Maybe this is a bug in Documenter.jl?

@fingolfin
Copy link
Contributor Author

No idea, I never look/looked at the PDF version of the manual, my concern was fixing the HTML docs

@KristofferC KristofferC added the backport 1.10 Change should be backported to the 1.10 release label Jan 24, 2024
@KristofferC KristofferC mentioned this pull request Jan 24, 2024
33 tasks
@KristofferC KristofferC merged commit 81c4f8e into JuliaLang:master Jan 24, 2024
6 of 8 checks passed
@fingolfin fingolfin deleted the mh/harr branch January 24, 2024 14:15
KristofferC pushed a commit that referenced this pull request Jan 24, 2024
There is no HTML entity `⇔` and accordingly all the usual browsers
(Chrome, Firefox, Safari) don't render it.

My guess is that there is confusion because GitHub supports `⇔` and
shows it as ⇔ (and `↔` as ↔).

But here is for example what Firefox shows:
<img width="853" alt="Screen Shot 2023-11-08 at 14 02 01"
src="https://github.com/JuliaLang/julia/assets/241512/af7d9e27-a5c3-46c3-94d9-82ed52653cb4">

This patch could be backported to 1.9 and 1.10.

(cherry picked from commit 81c4f8e)
@DilumAluthge
Copy link
Member

DilumAluthge commented Jan 24, 2024

Hmmm. Even with this PR, the HTML docs still look broken.

Here are the commands that I ran:

git clone https://github.com/JuliaLang/julia.git
cd julia
git fetch origin 1588e3c965932281346b9fdbc411fa7e816729a7
git checkout 1588e3c965932281346b9fdbc411fa7e816729a7
make
make binary-dist
ls ./doc/_build/html/en/manual/noteworthy-differences.html

# Open the file in my default web browser:
open ./doc/_build/html/en/manual/noteworthy-differences.html

And here is a screenshot of the noteworthy-differences.html file when I opened it in Firefox on my machine:

screenshot

@DilumAluthge
Copy link
Member

@mortenpi Is this a Documenter bug?

@fingolfin
Copy link
Contributor Author

It is indeed wrong on https://docs.julialang.org/en/v1.11-dev/manual/noteworthy-differences/#Julia-and-harr;-C/C:-Namespaces

Which is weird - I thought I had actually built the docs and verified it worked? Alas I mad no record here, so now I am uncertain... of course if I dif then it was before Documenter 1.0 was released. When I am back at a computer I'll try this on the 1.9 / 1.10 release branches...

@fingolfin
Copy link
Contributor Author

Huh, this is so weird: I just noticed that both &harr; but also &hArr; are rendered right in the search panel, specifically I see this (tested in Safari and Firefox on macOS):

with the 1.10 docs:
Screen Shot 2024-01-25 at 19 53 24

And with the v1.11-dev manual
Screen Shot 2024-01-25 at 19 53 47

What happens in both cases is that the ampersand is escaped, i.e. &hArr; is turned into &amp;hArr;.

So it seems my "fix" here was wrong, so sorry :-/. The real issue is escaping of HTML entities in Documenter -- and that even differs by context / where it is done, it seems, given that they are rendered fine in the search results... I just tried pandoc and commonmarker and a few other tools, they all handle HTML entities in Markdown just fine.

@mortenpi
Copy link
Contributor

The Markdown parser doesn't support HTML entities though. So in my mind, the Documenter bug here is that sometimes it doesn't escape the & when printing out the HTML.

As for fixing this -- I think just using the Unicode character should be enough.

@fingolfin
Copy link
Contributor Author

@mortenpi thanks for the explanation.

I made PR #53066 as a follow up to resolve this.

@fingolfin
Copy link
Contributor Author

If this PR here is backported then the follow-up should of course also be.

DilumAluthge added a commit that referenced this pull request Jan 29, 2024
Documenter does not support HTML entities. See discussion in PR #52078
for further background.

Co-authored-by: Dilum Aluthge <dilum@aluthge.com>
KristofferC pushed a commit that referenced this pull request Jan 29, 2024
Documenter does not support HTML entities. See discussion in PR #52078
for further background.

Co-authored-by: Dilum Aluthge <dilum@aluthge.com>
(cherry picked from commit 746fad0)
KristofferC pushed a commit that referenced this pull request Jan 30, 2024
Documenter does not support HTML entities. See discussion in PR #52078
for further background.

Co-authored-by: Dilum Aluthge <dilum@aluthge.com>
(cherry picked from commit 746fad0)
KristofferC added a commit that referenced this pull request Feb 6, 2024
Backported PRs:
- [x] #51095 <!-- Fix edge cases where inexact conversions to UInt don't
throw -->
- [x] #52583 <!-- Don't access parent of triangular matrix in powm -->
- [x] #52645 <!-- update --gcthreads section in command line options -->
- [x] #52423 <!-- update nthreads info in versioninfo -->
- [x] #52721 <!-- inference: Guard TypeVar special case against vararg
-->
- [x] #52637 <!-- fix finding bundled stdlibs even if they are e.g.
devved in an environment higher in the load path -->
- [x] #52752 <!-- staticdata: handle cycles in datatypes -->
- [x] #52758 <!-- use a Dict instead of an IdDict for caching of the
`cwstring` for Windows env variables -->
- [x] #51375 <!-- Insert hardcoded backlinks to stdlib doc pages -->
- [x] #52994 <!-- place work-stealing queue indices on different cache
lines to avoid false-sharing -->
- [x] #53015 <!-- Add type assertion in iterate for logicalindex -->
- [x] #53032 <!-- Fix a list in GC devdocs -->
- [x] #52748 
- [x] #52856 
- [x] #52878
- [x] #52754 
- [x] #52228
- [x] #52924
- [x] #52569 <!-- Fix GC rooting during rehashing of iddict -->
- [x] #52605 <!-- Default uplo in symmetric/hermitian -->
- [x] #52618 <!-- heap snapshot: add gc roots and gc finalist roots to
fix unrooted nodes -->
- [x] #52781 <!-- fix type-stability bugs in Ryu code -->
- [x] #53055 <!-- Profile: use full terminal cols to show function name
-->
- [x] #53096 
- [x] #53076 
- [x] #52841 <!-- Extensions: make loading of extensions independent of
what packages are in the sysimage -->
- [x] #52078 <!-- Replace `&hArr;` by `&harr;` in documentation -->
- [x] #53035 <!-- use proper cache-line size variable in work-stealing
queue -->
- [x] #53066 <!-- doc: replace harr HTML entity by unicode -->
- [x] #52996 <!-- Apple silicon has 128 byte alignment so fix our
defines to match -->
- [x] #53121 

Non-merged PRs with backport label:
- [ ] #52694 <!-- Reinstate similar for AbstractQ for backward
compatibility -->
- [ ] #51479 <!-- prevent code loading from lookin in the versioned
environment when building Julia -->
@KristofferC KristofferC removed the backport 1.10 Change should be backported to the 1.10 release label Feb 6, 2024
Drvi pushed a commit to RelationalAI/julia that referenced this pull request Jun 7, 2024
There is no HTML entity `&hArr;` and accordingly all the usual browsers
(Chrome, Firefox, Safari) don't render it.

My guess is that there is confusion because GitHub supports `&hArr;` and
shows it as &hArr; (and `&harr;` as &harr;).

But here is for example what Firefox shows:
<img width="853" alt="Screen Shot 2023-11-08 at 14 02 01"
src="https://github.com/JuliaLang/julia/assets/241512/af7d9e27-a5c3-46c3-94d9-82ed52653cb4">

This patch could be backported to 1.9 and 1.10.

(cherry picked from commit 81c4f8e)
Drvi pushed a commit to RelationalAI/julia that referenced this pull request Jun 7, 2024
Documenter does not support HTML entities. See discussion in PR JuliaLang#52078
for further background.

Co-authored-by: Dilum Aluthge <dilum@aluthge.com>
(cherry picked from commit 746fad0)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs This change adds or pertains to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants