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

$ not rendering properly #890

Closed
morris25 opened this issue Nov 20, 2018 · 7 comments · Fixed by #1625
Closed

$ not rendering properly #890

morris25 opened this issue Nov 20, 2018 · 7 comments · Fixed by #1625
Milestone

Comments

@morris25
Copy link

morris25 commented Nov 20, 2018

The advised way to add dollar signs to a docstring is to double escape them, but the example docstring,

"""
\\\$ some text \\\$ some more text
"""
dolladollabills()="\$"

renders to :
screen shot 2018-11-20 at 2 12 47 pm

I have yet to find a nice way to get dollar signs to show up properly in both the repl and the rendered docs.

@mortenpi
Copy link
Member

mortenpi commented Nov 20, 2018

The escaping seems to be correct. My guess is that the problem is that we're outputting literal $ into the HTML, so MathJax does not distinguish it from normal math blocks. We should probably output $ for literal $s.

@odow
Copy link
Collaborator

odow commented Jul 3, 2021

This continues to bite me.

shell> cat src/index.md
The price is \$1.

The price is \$1 or \$2.

julia> using Documenter

julia> Documenter.makedocs(sitename = "Bug", pages = ["index.md"])
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages.

yields

image

My motivation to fix it is now high. Any pointers on where I should go looking?

@mortenpi
Copy link
Member

mortenpi commented Jul 3, 2021

If my original guess in #890 (comment) is correct, I think it might be enough to do the relevant escaping here

mdconvert(text::AbstractString, parent; kwargs...) = DOM.Node(text)

@odow
Copy link
Collaborator

odow commented Jul 4, 2021

So I tried the escaping thing. It was sufficient to go

function mdconvert(text::AbstractString, parent; kwargs...)
    if text == "\$"
        return DOM.Node("$")
    end
    return DOM.Node(text) 
end

and I had to modify

"""
Escape characters in the provided string. This converts the following characters:
- `<` to `&lt;`
- `>` to `&gt;`
- `&` to `&amp;`
- `'` to `&#39;`
- `\"` to `&quot;`
When no escaping is needed then the same object is returned, otherwise a new
string is constructed with the characters escaped. The returned object should
always be treated as an immutable copy and compared using `==` rather than `===`.
"""
function escapehtml(text::AbstractString)
if occursin(r"[<>&'\"]", text)
buffer = IOBuffer()
for char in text
char === '<' ? write(buffer, "&lt;") :
char === '>' ? write(buffer, "&gt;") :
char === '&' ? write(buffer, "&amp;") :

to prevent it being escaped.

But... it seems that the math engines treat &#x24; as $ when it comes to delimiters... so this had no effect.

The upstream issue for all of this is really: KaTeX/KaTeX#437

An easier solve is just to not use $ as the inline math delimiter.

diff --git a/src/Writers/HTMLWriter.jl b/src/Writers/HTMLWriter.jl
index 4f52d9b6..c9f0c250 100644
--- a/src/Writers/HTMLWriter.jl
+++ b/src/Writers/HTMLWriter.jl
@@ -164,8 +164,8 @@ struct KaTeX <: MathEngine
     function KaTeX(config::Union{Dict,Nothing} = nothing, override=false)
         default = Dict(
             :delimiters => [
-                Dict(:left => raw"$",   :right => raw"$",   display => false),
-                Dict(:left => raw"$$",  :right => raw"$$",  display => true),
+                Dict(:left => raw"\(", :right => raw"\)", display => false),
+                Dict(:left => raw"$$", :right => raw"$$", display => true),
                 Dict(:left => raw"\[", :right => raw"\]", display => true),
             ]
         )
@@ -1686,7 +1686,7 @@ function mdconvert(m::Markdown.LaTeX, ::MDBlockContext; kwargs...)
     @tags p
     p[".math-container"](string("\\[", m.formula, "\\]"))
 end
-mdconvert(m::Markdown.LaTeX, parent; kwargs...) = Tag(:span)(string('$', m.formula, '$'))
+mdconvert(m::Markdown.LaTeX, parent; kwargs...) = Tag(:span)(string("\\(", m.formula, "\\)"))
 
 mdconvert(::Markdown.LineBreak, parent; kwargs...) = Tag(:br)()
 

This seems to work okay:

julia> Documenter.makedocs(sitename = "Bug", pages = ["index.md"])
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages.

shell> cat src/index.md
The price is \$1.

The price is \$1 or \$2.

Here is some $x^2$ math.

And some more \\(\sqrt x\\).

And \$1 is more than $x^2$ but \\(\sqrt x\\) is less than \$2. 

image

Is changing the inline math escape breaking? It's a change on the HTML side, so user's shouldn't see any differences.

Edit: the span trick was easier: #1625

@sylvaticus
Copy link
Contributor

Hello, as of Documenter v0.27.15 this is still a problem.
If I have (a single) $a in a md page I got it rendered as a, but if I have (a single) $1 (i.e. the dollar sign followed by a digit, I have this error calling makedocs:

ERROR: MethodError: no method matching mdflatten(::IOBuffer, ::Int64, ::Int64)
Closest candidates are:
  mdflatten(::Any, ::Union{Expr, Symbol}, ::Any) at ~/.julia/packages/Documenter/7hBIS/src/Utilities/MDFlatten.jl:80
  mdflatten(::Any, ::Vector, ::Any) at ~/.julia/packages/Documenter/7hBIS/src/Utilities/MDFlatten.jl:34
  mdflatten(::Any, ::Markdown.Header{N}, ::Any) where N at ~/.julia/packages/Documenter/7hBIS/src/Utilities/MDFlatten.jl:44
  ...
Stacktrace:
  [1] mdflatten(io::IOBuffer, md::Int64)
    @ Documenter.Utilities.MDFlatten ~/.julia/packages/Documenter/7hBIS/src/Utilities/MDFlatten.jl:32
  [2] mdflatten(md::Int64)
    @ Documenter.Utilities.MDFlatten ~/.julia/packages/Documenter/7hBIS/src/Utilities/MDFlatten.jl:28
  [3] Documenter.Writers.HTMLWriter.SearchRecord(ctx::Documenter.Writers.HTMLWriter.HTMLContext, navnode::Documenter.Documents.NavNode, node::Int64)
    @ Documenter.Writers.HTMLWriter ~/.julia/packages/Documenter/7hBIS/src/Writers/HTMLWriter.jl:690
  [4] (::Documenter.Writers.HTMLWriter.var"#78#79"{Documenter.Writers.HTMLWriter.HTMLContext, Documenter.Documents.NavNode, Documenter.Documents.Page})(elem::Int64)
    @ Documenter.Writers.HTMLWriter ~/.julia/packages/Documenter/7hBIS/src/Writers/HTMLWriter.jl:1447
  [5] iterate
    @ ./generator.jl:47 [inlined]
  [6] collect_to!(dest::Vector{Documenter.Utilities.DOM.Node}, itr::Base.Generator{Vector{Any}, Documenter.Writers.HTMLWriter.var"#78#79"{Documenter.Writers.HTMLWriter.HTMLContext, Documenter.Documents.NavNode, Documenter.Documents.Page}}, offs::Int64, st::Int64)
    @ Base ./array.jl:782
  [7] collect_to_with_first!(dest::Vector{Documenter.Utilities.DOM.Node}, v1::Documenter.Utilities.DOM.Node, itr::Base.Generator{Vector{Any}, Documenter.Writers.HTMLWriter.var"#78#79"{Documenter.Writers.HTMLWriter.HTMLContext, Documenter.Documents.NavNode, Documenter.Documents.Page}}, st::Int64)
    @ Base ./array.jl:760
  [8] _collect(c::Vector{Any}, itr::Base.Generator{Vector{Any}, Documenter.Writers.HTMLWriter.var"#78#79"{Documenter.Writers.HTMLWriter.HTMLContext, Documenter.Documents.NavNode, Documenter.Documents.Page}}, #unused#::Base.EltypeUnknown, isz::Base.HasShape{1})
    @ Base ./array.jl:754
  [9] collect_similar(cont::Vector{Any}, itr::Base.Generator{Vector{Any}, Documenter.Writers.HTMLWriter.var"#78#79"{Documenter.Writers.HTMLWriter.HTMLContext, Documenter.Documents.NavNode, Documenter.Documents.Page}})
    @ Base ./array.jl:653
 [10] map(f::Function, A::Vector{Any})
    @ Base ./abstractarray.jl:2849
 [11] domify(ctx::Documenter.Writers.HTMLWriter.HTMLContext, navnode::Documenter.Documents.NavNode)
    @ Documenter.Writers.HTMLWriter ~/.julia/packages/Documenter/7hBIS/src/Writers/HTMLWriter.jl:1446
 [12] render_article(ctx::Documenter.Writers.HTMLWriter.HTMLContext, navnode::Documenter.Documents.NavNode)
    @ Documenter.Writers.HTMLWriter ~/.julia/packages/Documenter/7hBIS/src/Writers/HTMLWriter.jl:1280
 [13] render_page(ctx::Documenter.Writers.HTMLWriter.HTMLContext, navnode::Documenter.Documents.NavNode)
    @ Documenter.Writers.HTMLWriter ~/.julia/packages/Documenter/7hBIS/src/Writers/HTMLWriter.jl:822
 [14] render(doc::Documenter.Documents.Document, settings::Documenter.Writers.HTMLWriter.HTML)
    @ Documenter.Writers.HTMLWriter ~/.julia/packages/Documenter/7hBIS/src/Writers/HTMLWriter.jl:767
 [15] runner(#unused#::Type{Documenter.Writers.HTMLFormat}, fmt::Documenter.Writers.HTMLWriter.HTML, doc::Documenter.Documents.Document)
    @ Documenter.Writers ~/.julia/packages/Documenter/7hBIS/src/Writers/Writers.jl:42
 [16] dispatch(::Type{Documenter.Writers.FormatSelector}, ::Documenter.Writers.HTMLWriter.HTML, ::Vararg{Any})
    @ Documenter.Utilities.Selectors ~/.julia/packages/Documenter/7hBIS/src/Utilities/Selectors.jl:170
 [17] render(doc::Documenter.Documents.Document)
    @ Documenter.Writers ~/.julia/packages/Documenter/7hBIS/src/Writers/Writers.jl:86
 [18] runner(#unused#::Type{Documenter.Builder.RenderDocument}, doc::Documenter.Documents.Document)
    @ Documenter.Builder ~/.julia/packages/Documenter/7hBIS/src/Builder.jl:258
 [19] dispatch(#unused#::Type{Documenter.Builder.DocumentPipeline}, x::Documenter.Documents.Document)
    @ Documenter.Utilities.Selectors ~/.julia/packages/Documenter/7hBIS/src/Utilities/Selectors.jl:170
 [20] #2
    @ ~/.julia/packages/Documenter/7hBIS/src/Documenter.jl:266 [inlined]
 [21] cd(f::Documenter.var"#2#3"{Documenter.Documents.Document}, dir::String)
    @ Base.Filesystem ./file.jl:110
 [22] #makedocs#1
    @ ~/.julia/packages/Documenter/7hBIS/src/Documenter.jl:265 [inlined]
 [23] top-level scope
    @ ~/CloudFiles/lef-nancy-sync/Documents/Teaching/2021-2022/Introduction to Scientific Programming and Machine Learning with Julia/SPMLJ/makedoc.jl:190

@sylvaticus
Copy link
Contributor

ok, escaping with \$1 or \$a works, just that in the documentation it is referred under the LaTeX part, but dollar symbols are not used only for Latex, perhaps the escaping section should be moved outside of the LaTeX section in the Documenter.jl own documentation ???

@mortenpi
Copy link
Member

@sylvaticus I think you are running into #1020, which is slightly different from this issue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants