Add more newlines (#297)

docs/contents/demo.md

@@ -7,13 +7,26 @@ For example,
 See @sec:getting-started.
 ```
 
-> See @sec:getting-started.
+See @sec:getting-started.
+
+```language-plain
+We can refer to citations such as @orwell1945animal and
+[@orwell1949nineteen] or to equations such as @eq:example.
+```
 
 We can refer to citations such as @orwell1945animal and [@orwell1949nineteen] or to equations such as @eq:example.
 
+```language-tex
+$$ y = \frac{\sin{x}}{\cos{x}} $$ {#eq:example}
+```
+
 $$ y = \frac{\sin{x}}{\cos{x}} $$ {#eq:example}
 
-To show your TeX equations, surround them by double dollar signs (`e.g., $$ x = 3 $$`) for display math and by single dolor sign (e.g., `$x = 3$`) for inline math.
+```language-plain
+Use single dollar symbols for inline math: $x = 3$.
+```
+
+Use single dollar symbols for inline math: $x = 3$.
 
 ## Embedding output {#sec:embedding-output}
 
@@ -351,11 +364,9 @@ Therefore, portable network graphics (PNG) images are also created and passed to
 ```
 
 Then, plotting works:
-
 ```jl
 @sco BooksDocs.example_plot()
 ```
-
 For multiple images, use `Options.(objects, paths)`:
 
 ```jl

src/build.jl

@@ -24,7 +24,7 @@ function inputs(project)
     H = config(project, "homepage_contents")::String
     C = config(project, "contents")::Vector{String}
     names = [H; C]
-    [joinpath("contents", "$name.md") for name in names]
+    return [joinpath("contents", "$name.md") for name in names]
 end
 
 """
@@ -160,7 +160,8 @@ function write_input_markdown(project; skip_index=false)::String
     end
     texts = read.(files, String)
     texts = embed_output.(texts)
-    text = join(texts, '\n')
+    # Double newline to make parsing easier for Pandoc (Books issue #295).
+    text = join(texts, "\n\n")
     dir = Books.GENERATED_DIR
     if !isdir(dir)
         @warn "$(dir) directory doesn't exist. Did you run `gen()`?"

src/generate.jl

@@ -151,15 +151,22 @@ function escape_expr(expr::AbstractString)
     joinpath(GENERATED_DIR, "$escaped.md")
 end
 
+"""
+    newlines(out::AbstractString) -> String
+
+Add some extra newlines around the output.
+This is required by Pandoc in some cases to parse the output correctly.
+"""
+newlines(out::AbstractString) = string('\n', out, '\n')::String
+
 function evaluate_and_write(M::Module, userexpr::UserExpr)
     expr = userexpr.expr
     path = escape_expr(expr)
     expr_info = replace(expr, '\n' => "\\n")
 
     ex = Meta.parse("begin $expr end")
     out = Core.eval(Main, ex)
-    converted = convert_output(expr, path, out)
-    markdown = string(converted)::String
+    markdown = newlines(convert_output(expr, path, out))
     indent = userexpr.indentation
     if 0 < indent
         lines = split(markdown, '\n')
@@ -177,11 +184,9 @@ function evaluate_and_write(f::Function)
     path = escape_expr(expr)
     expr_info = replace(expr, '\n' => "\\n")
     out = f()
-    out = convert_output(expr, path, out)
-    out = string(out)::String
-    write(path, out)
-
-    nothing
+    converted = newlines(convert_output(expr, path, out))
+    write(path, converted)
+    return nothing
 end
 
 function clean_stacktrace(stacktrace::String)
@@ -280,7 +285,6 @@ end
         [block_number::Union{Nothing,Int}=nothing];
         call_html::Bool=true,
         fail_on_error::Bool=false,
-        log_progress::Bool=true,
         project="default",
         kwargs...
     )
@@ -297,7 +301,6 @@ function gen(
         block_number::Union{Nothing,Int}=nothing;
         call_html::Bool=true,
         fail_on_error::Bool=false,
-        log_progress::Bool=true,
         project="default",
         kwargs...
     )
@@ -360,15 +363,13 @@ end
 function gen(;
         call_html::Bool=true,
         fail_on_error::Bool=false,
-        log_progress::Bool=false,
         project="default",
         kwargs...
     )
     if !isfile("config.toml")
         error("Couldn't find `config.toml`. Is there a valid project in $(pwd())?")
     end
     paths = inputs(project)
-    first_file = first(paths)
     gen(paths; fail_on_error, project, call_html)
 end
 

src/output.jl

@@ -36,7 +36,7 @@ end
 
 function convert_output(expr, path, outputs::AbstractVector{AbstractString})
     out = join(outputs, "\n")
-    out = output_block(out)
+    return output_block(out)
 end
 
 function convert_output(expr, path, outputs::AbstractVector)

src/showcode.jl

@@ -52,7 +52,7 @@ function apply_process_post(
     )
     out = pre(out)
     if isnothing(process)
-        out = convert_output(expr, path, out)
+        out = newlines(convert_output(expr, path, out))
     else
         out = process(out)
     end

test/generate.jl

@@ -62,8 +62,8 @@
     @test m[1] == "s = \"x = 1\"\n   sco(s)"
     @test m[2] == "   "
 
-    out = read_outcome(evaluated_block)
-    @test out == "   ```language-julia\n   x = 1\n   ```\n   \n   1\n   "
+    out = strip(read_outcome(evaluated_block))
+    @test out == "```language-julia\n   x = 1\n   ```\n   \n   \n   1"
 
     # Blocks with four indentations should not be evaluated.
     # This functionality is useful for the Books.jl documentation.

test/showcode.jl

@@ -12,12 +12,12 @@ end
     @test s == code_block(fdef)
 
     s = sco("x = 3")
-    @test s == "```language-julia\nx = 3\n```\n\n3\n"
+    @test s == "```language-julia\nx = 3\n```\n\n\n3\n\n"
     s = sco("""
         y = 2 # hide
         x = 3
         """)
-    @test s == "```language-julia\nx = 3\n```\n\n3\n"
+    @test s == "```language-julia\nx = 3\n```\n\n\n3\n\n"
 
     s = sco(raw"""
         x = 3
@@ -31,7 +31,9 @@ end
         sc_test_function()
         ```
 
+
         1
+
         """
 
     s = @sco sc_test_function_with_comment()
@@ -43,7 +45,9 @@ end
         sc_test_function_with_comment()
         ```
 
+
         2
+
         """
 end
 
@@ -69,18 +73,20 @@ end
 @testset "@sco" begin
     pre(out) = Options(out; caption="caption")
     s = @sco pre=pre sco_test_dataframe()
-    @test strip(s) == strip("""
+    expected = """
         ```language-julia
         sco_test_dataframe() = DataFrame(; x = [1])
         sco_test_dataframe()
         ```
 
+
         |   x |
         | ---:|
         |   1 |
 
         : caption
-        """)
+        """
+    @test strip(s) == strip(expected)
 end
 
 module ShowcodeTestModule