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

[doc] Add a Cover page to PDF doc #45034

Merged
merged 15 commits into from
Apr 23, 2022
Merged

Conversation

inkydragon
Copy link
Member

@inkydragon inkydragon commented Apr 19, 2022

Close #35495.

Add some custom TeX styles include:

  • cover.tex: The main definition of the cover, used to replace the default \maketitle command.
  • custom.sty: Load the macro package required for the cover, define the background image style, etc.
  • preamble.tex: Replace the default preamble for inserting a custom cover.
  • logo.tex: logo of julia.
  • cover-splash.tex: Background image of the cover title, from julia's homepage.
  • Move the "Release Notes " to the last chapter of the devdoc.

Old design - [PDF @ 5dc9ac4-tikz-bg](https://drive.google.com/file/d/1JzmnEKodYegfkY-eXm2lGkDkKbBJd688/view?usp=sharing)

image

@ViralBShah ViralBShah added backport 1.8 Change should be backported to release-1.8 docsystem The documentation building system labels Apr 19, 2022
@tecosaur
Copy link
Contributor

Two quick comments:

  • LaTeX does support SVG, see https://ctan.org/pkg/svg. If an inkscape executable is not available when compiling, the SVG can be converted to a PDF as a pre-build step.
  • The large dark banner looks a little odd to me. Have you tried fading the background image and using black text?

@inkydragon
Copy link
Member Author

  1. LaTeX does support SVG, see https://ctan.org/pkg/svg. If an inkscape executable is not available when compiling, the SVG can be converted to a PDF as a pre-build step.
  2. The large dark banner looks a little odd to me. Have you tried fading the background image and using black text?
  1. TODO: Add a logo of julia in tikz to JuliaLang/julia-logo-graphics, then use it.
    Adding a new dependency is probably not a good idea.
  2. Yes, the design of the cover deserves further discussion.
    I will try your suggestion. It would be great if you could provide some references or example images.

@tecosaur
Copy link
Contributor

It would be great if you could provide some references or example images.

Sure, here's a quick mock-up of my thoughts.

image

@tecosaur
Copy link
Contributor

Oh, and re:

Adding a new dependency is probably not a good idea.

You can run this yourself and just upload the .pdf.

@inkydragon
Copy link
Member Author

@ViralBShah Should we only show "Chapter" title again?

How about only show "Chapter" title + compact spacing?

Originally posted by @inkydragon in #35495 (comment)

PDF-Chapter Only

image

@inkydragon
Copy link
Member Author

@tecosaur Some quick attempts, fonts still need to be adjusted

You can run this yourself and just upload the .pdf.

Actually, I don't want to add any binaries to git.
So I will try to remake the logo with Tikz

image

@tecosaur
Copy link
Contributor

tecosaur commented Apr 20, 2022

Looking good. Two other things I'd advocate for

  • Making "The Julia Project" one size larger than the date (I just think it looks nicer)
  • Changing "Julia 1.9.0 Documentation" to just "1.9.0"
    • I'd be more inclined to just change the subtitle to "Documentation on the language and stdlib", making "Documentation" here redundant.
    • Do we really need to have "Julia" appear four times on the cover page? I'd think three is enough.

Lastly, regarding this comment:

Actually, I don't want to add any binaries to git.

  1. Git is bad with changes within binaries, but has perfectly good support for binary objects.
  2. What about cover-background.png ?

@barucden
Copy link
Contributor

How about pulling the PDF logo from JuliaLang/julia-logo-graphics in make.jl before producing the PDF documentation?

In any case, if a tikzpicture is needed, I used xyz2tex/svg2tikz and Inkscape to translate the SVG. See below.

Julia logo as tikzpicture
\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage{tikz}

\begin{document}
\definecolor{cca3b33}{RGB}{202,59,51}
\definecolor{c4062d7}{RGB}{64,98,215}
\definecolor{c9457b1}{RGB}{148,87,177}
\definecolor{c389725}{RGB}{56,151,37}


\def \globalscale {1.000000}
\begin{tikzpicture}[y=0.80pt, x=0.80pt, yscale=-\globalscale, xscale=\globalscale, inner sep=0pt, outer sep=0pt]
  \path[fill=black,nonzero rule] (50.9033,123.2344) .. controls (50.9033,128.8857)
    and (50.2676,133.4502) .. (48.9961,136.9248) .. controls (47.7246,140.4023)
    and (45.9170,143.1006) .. (43.5703,145.0225) .. controls (41.2266,146.9443)
    and (38.4141,148.2305) .. (35.1357,148.8809) .. controls (31.8574,149.5283)
    and (28.2100,149.8535) .. (24.1992,149.8535) .. controls (18.7705,149.8535)
    and (14.6162,149.0068) .. (11.7363,147.3105) .. controls (8.8535,145.6143) and
    (7.4121,143.5811) .. (7.4121,141.2051) .. controls (7.4121,139.2275) and
    (8.2148,137.5605) .. (9.8262,136.2041) .. controls (11.4375,134.8477) and
    (13.5996,134.1709) .. (16.3125,134.1709) .. controls (18.3486,134.1709) and
    (19.9746,134.7217) .. (21.1875,135.8232) .. controls (22.4033,136.9248) and
    (23.4082,138.0146) .. (24.1992,139.0869) .. controls (25.1016,140.2734) and
    (25.8662,141.0645) .. (26.4873,141.4600) .. controls (27.1084,141.8555) and
    (27.6738,142.0547) .. (28.1836,142.0547) .. controls (29.2559,142.0547) and
    (30.0762,141.4189) .. (30.6416,140.1475) .. controls (31.2070,138.8760) and
    (31.4883,136.4033) .. (31.4883,132.7295) -- (31.4883,63.0381) --
    (50.9033,57.6973) -- (50.9033,123.2344)(78.5537,59.5605) -- (78.5537,104.4111)
    .. controls (78.5537,105.6562) and (78.7939,106.8281) .. (79.2744,107.9297) ..
    controls (79.7549,109.0312) and (80.4199,109.9805) .. (81.2666,110.7715) ..
    controls (82.1162,111.5625) and (83.1035,112.1982) .. (84.2344,112.6787) ..
    controls (85.3652,113.1592) and (86.5811,113.3994) .. (87.8818,113.3994) ..
    controls (89.3496,113.3994) and (91.0195,112.5762) .. (93.0527,111.1523) ..
    controls (96.2725,108.8965) and (98.2236,107.3467) .. (98.2236,105.5127) ..
    controls (98.2236,105.0732) and (98.2236,59.5605) .. (98.2236,59.5605) --
    (117.5537,59.5605) -- (117.5537,123.2344) -- (98.2236,123.2344) --
    (98.2236,117.2988) .. controls (95.6807,119.4463) and (92.9678,121.1689) ..
    (90.0850,122.4697) .. controls (87.2021,123.7705) and (84.4043,124.4209) ..
    (81.6914,124.4209) .. controls (78.5273,124.4209) and (75.5859,123.8965) ..
    (72.8730,122.8506) .. controls (70.1602,121.8047) and (67.7871,120.3779) ..
    (65.7539,118.5703) .. controls (63.7178,116.7627) and (62.1211,114.6416) ..
    (60.9609,112.2100) .. controls (59.8037,109.7812) and (59.2236,107.1797) ..
    (59.2236,104.4111) -- (59.2236,59.5605) --
    (78.5537,59.5605)(144.6621,123.2344) -- (125.4170,123.2344) --
    (125.4170,33.9580) -- (144.6621,28.6172) --
    (144.6621,123.2344)(152.7012,63.0381) -- (172.0312,57.6973) --
    (172.0312,123.2344) -- (152.7012,123.2344) --
    (152.7012,63.0381)(212.4199,90.3369) .. controls (210.5537,91.1309) and
    (208.6729,92.0479) .. (206.7803,93.0938) .. controls (204.8877,94.1396) and
    (203.1621,95.2852) .. (201.6094,96.5273) .. controls (200.0537,97.7695) and
    (198.7969,99.0996) .. (197.8359,100.5117) .. controls (196.8750,101.9238) and
    (196.3945,103.3945) .. (196.3945,104.9209) .. controls (196.3945,106.1074) and
    (196.5498,107.2529) .. (196.8604,108.3545) .. controls (197.1709,109.4561) and
    (197.6104,110.4023) .. (198.1758,111.1934) .. controls (198.7412,111.9844) and
    (199.3623,112.6201) .. (200.0420,113.1006) .. controls (200.7188,113.5811) and
    (201.4541,113.8213) .. (202.2451,113.8213) .. controls (203.8271,113.8213) and
    (205.4238,113.3408) .. (207.0352,112.3799) .. controls (208.6465,111.4189) and
    (210.4395,110.2061) .. (212.4199,108.7354) --
    (212.4199,90.3369)(231.8320,123.2344) -- (212.4199,123.2344) --
    (212.4199,118.1455) .. controls (211.3447,119.0508) and (210.2988,119.8857) ..
    (209.2822,120.6475) .. controls (208.2656,121.4092) and (207.1201,122.0742) ..
    (205.8486,122.6396) .. controls (204.5771,123.2051) and (203.1504,123.6416) ..
    (201.5654,123.9551) .. controls (199.9834,124.2656) and (198.1172,124.4209) ..
    (195.9727,124.4209) .. controls (193.0312,124.4209) and (190.3887,123.9961) ..
    (188.0449,123.1494) .. controls (185.6982,122.2998) and (183.7061,121.1426) ..
    (182.0684,119.6719) .. controls (180.4277,118.2041) and (179.1709,116.4639) ..
    (178.2949,114.4570) .. controls (177.4189,112.4531) and (176.9795,110.2617) ..
    (176.9795,107.8887) .. controls (176.9795,105.4570) and (177.4453,103.2539) ..
    (178.3799,101.2734) .. controls (179.3115,99.2959) and (180.5830,97.5176) ..
    (182.1943,95.9326) .. controls (183.8057,94.3506) and (185.6836,92.9385) ..
    (187.8311,91.6934) .. controls (189.9785,90.4512) and (192.2842,89.3057) ..
    (194.7422,88.2598) .. controls (197.2002,87.2139) and (199.7578,86.2559) ..
    (202.4150,85.3799) .. controls (205.0693,84.5039) and (207.7002,83.6689) ..
    (210.2988,82.8779) -- (212.4199,82.3682) -- (212.4199,76.0957) .. controls
    (212.4199,72.0264) and (211.6406,69.1436) .. (210.0879,67.4473) .. controls
    (208.5322,65.7510) and (206.4551,64.9043) .. (203.8564,64.9043) .. controls
    (200.8037,64.9043) and (198.6826,65.6396) .. (197.4961,67.1074) .. controls
    (196.3096,68.5781) and (195.7148,70.3564) .. (195.7148,72.4482) .. controls
    (195.7148,73.6348) and (195.5889,74.7949) .. (195.3340,75.9258) .. controls
    (195.0820,77.0566) and (194.6426,78.0439) .. (194.0215,78.8936) .. controls
    (193.4004,79.7402) and (192.5098,80.4199) .. (191.3496,80.9268) .. controls
    (190.1924,81.4365) and (188.7363,81.6914) .. (186.9844,81.6914) .. controls
    (184.2715,81.6914) and (182.0684,80.9121) .. (180.3721,79.3594) .. controls
    (178.6758,77.8037) and (177.8291,75.8408) .. (177.8291,73.4648) .. controls
    (177.8291,71.2617) and (178.5762,69.2139) .. (180.0732,67.3213) .. controls
    (181.5732,65.4258) and (183.5918,63.7998) .. (186.1377,62.4463) .. controls
    (188.6807,61.0869) and (191.6191,60.0146) .. (194.9531,59.2236) .. controls
    (198.2871,58.4326) and (201.8203,58.0371) .. (205.5498,58.0371) .. controls
    (210.1289,58.0371) and (214.0723,58.4473) .. (217.3799,59.2646) .. controls
    (220.6846,60.0850) and (223.4121,61.2568) .. (225.5596,62.7832) .. controls
    (227.7070,64.3096) and (229.2891,66.1465) .. (230.3057,68.2939) .. controls
    (231.3252,70.4414) and (231.8320,72.8467) .. (231.8320,75.5010) --
    (231.8320,123.2344);



  \path[fill=cca3b33,nonzero rule] (176.4551,41.3174) .. controls
    (176.4551,48.5684) and (170.5781,54.4424) .. (163.3301,54.4424) .. controls
    (156.0791,54.4424) and (150.2051,48.5684) .. (150.2051,41.3174) .. controls
    (150.2051,34.0693) and (156.0791,28.1924) .. (163.3301,28.1924) .. controls
    (170.5781,28.1924) and (176.4551,34.0693) .. (176.4551,41.3174);



  \path[fill=c4062d7,nonzero rule] (54.7148,41.3174) .. controls (54.7148,48.5684)
    and (48.8379,54.4424) .. (41.5898,54.4424) .. controls (34.3418,54.4424) and
    (28.4648,48.5684) .. (28.4648,41.3174) .. controls (28.4648,34.0693) and
    (34.3418,28.1924) .. (41.5898,28.1924) .. controls (48.8379,28.1924) and
    (54.7148,34.0693) .. (54.7148,41.3174);



  \path[fill=c9457b1,nonzero rule] (207.9902,41.3174) .. controls
    (207.9902,48.5684) and (202.1133,54.4424) .. (194.8652,54.4424) .. controls
    (187.6172,54.4424) and (181.7402,48.5684) .. (181.7402,41.3174) .. controls
    (181.7402,34.0693) and (187.6172,28.1924) .. (194.8652,28.1924) .. controls
    (202.1133,28.1924) and (207.9902,34.0693) .. (207.9902,41.3174);



  \path[fill=c389725,nonzero rule] (192.2256,14.0039) .. controls
    (192.2256,21.2520) and (186.3486,27.1289) .. (179.1006,27.1289) .. controls
    (171.8496,27.1289) and (165.9756,21.2520) .. (165.9756,14.0039) .. controls
    (165.9756,6.7559) and (171.8496,0.8789) .. (179.1006,0.8789) .. controls
    (186.3486,0.8789) and (192.2256,6.7559) .. (192.2256,14.0039);




\end{tikzpicture}
\end{document}

@ViralBShah
Copy link
Member

Seems like using the tikzpicture is perhaps a better option, since it can be directly embedded and updated in git.

@inkydragon
Copy link
Member Author

New changes:

  • Use translucent background
  • Centered main heading
  • use tikz logo; rm .png
  • Show only version number
  • make DocAuthors larger

Accepted some suggestions from tecosaur:

  • Making "The Julia Project" one size larger than the date (I just think it looks nicer)
  • Changing "Julia 1.9.0 Documentation" to just "1.9.0"
  • I'd be more inclined to just change the subtitle to "Documentation on the language and stdlib", making "Documentation" here redundant.
  • Do we really need to have "Julia" appear four times on the cover page? I'd think three is enough.

@tecosaur
Copy link
Contributor

Glad my suggestions were helpful! For what it's worth, I think this is shaping up nicely 🙂.

Something I didn't do in my mock-up that may be worth trying is increasing the saturation of the banner image along with the lightness.

As an example, compare:

Lightened

image

Lightened + saturated

image

(original)

image

Seen in greyscale

2022-04-21_15-24

Both have a similar lightness, but the second looks less "washed out" compared to the original image thanks to the increase in saturation.

@ViralBShah
Copy link
Member

We should avoid checking in the png into the repo. Maybe downloading both the Julia logo and background image during build is the better option? Or alternately, avoid the background altogether and get this merged for now.

@inkydragon
Copy link
Member Author

inkydragon commented Apr 21, 2022

increasing the saturation of the banner image along with the lightness.

I tried removing the gray background and adding a white translucent mask, and it looks good too.

avoid the background altogether

Don't worry I have redrawn the background image in tikz.

@ViralBShah I only have one last question, should the TOC shows only the chapters?

  • shows only the chapters: TOC=4 pages
  • show chapters+sections: TOC=14 pages

PDF-Chapter Only

image

Originally posted by @inkydragon in #45034 (comment)

@inkydragon
Copy link
Member Author

it's a good idea to keep it that way.

Get it.

Is it possible to make the Release Notes all be one chapter for the pdf?

Done. Now "Release Notes" is the last chapter in devdoc.

image

@inkydragon
Copy link
Member Author

I feel like this pr is ready to merge.

@tecosaur
Copy link
Contributor

I have redrawn the background image in tikz.

Am I correct in guessing this would allow you to switch the colours for lightened + saturated variants, and avoid translucent masking?

section level TOC allows readers to quickly find the right content

This may sound like an odd suggestion, but how about two TOCs?

The first can just be level-1 headings on one page, then immediately following that a second multi-page detailed TOC (i.e. what we currently have). I think this should allow for the best of both options, and would be distinctly better than one or the other.

I've used level-1 "summary TOCs" before and found the results quite good. e.g.

image

In that document (https://tecosaur.com/lfs/bmc/bmc.pdf) I used mini-tocs on chapter cover pages too:

image

I find this sort of structure particularly good for long documents.

@inkydragon
Copy link
Member Author

this would allow you to switch the colours for lightened + saturated variants

I guess so. I will try your suggestion this weekend.

how about two TOCs?

This is a brilliant idea! I'll make a note of this first.
Besides the TOC style, there is still much to improve.
The final goal should be to create a document class for julia's documents.

The main purpose of this pr is to give julia a not bad cover. (Maybe 7/10 is enough)
My next goal is to get the symbols in the julia document to display properly. ([TeX] Switch mono font to JuliaMono)
After that, I'll turn around and make the whole document look better.

@tecosaur
Copy link
Contributor

Glad my thought helped :)

After that, I'll turn around and make the whole document look better.

Great! I'd be up getting involved with that. I've spent far too long tweaking LaTeX styling, and I like the idea of improving the look of the Julia manual.

@mortenpi
Copy link
Contributor

mortenpi commented Apr 22, 2022

I just wanted to chime in and say that I also think that two TOCs is an excellent way to get the best of both worlds in this case.

For smaller package manuals (i.e. what should be the Documenter default) a single full TOC is probably sufficient though, as those are often only a few chapters? But I do think it would be awesome if the two TOC feature would be an option directly in Documenter.

@ViralBShah
Copy link
Member

Should we merge this one for now, and keep making improvements in future PRs? This is already a strict improvement.

@inkydragon
Copy link
Member Author

Should we merge this one for now

Yes, just do it.

If there is any improvement, I'll open a new pr.

@inkydragon
Copy link
Member Author

@tecosaur I created a new self-contained project for the cover of the julia manual.

We can do some experimentation there and open the new pr over here when we're ready.

And some experiments with document styles: https://github.com/inkydragon/Julia-LaTeX-doc

@ViralBShah ViralBShah added the merge me PR is reviewed. Merge when all tests are passing label Apr 23, 2022
@ViralBShah
Copy link
Member

The dev should have the development version listed (not just DEV). Would you prefer cover relatedissues to be filed in the new repo?

@inkydragon
Copy link
Member Author

The dev should have the development version listed (not just DEV).

Are you referring to the sample image in the inkydragon/julia-title-page?

The string "DEV" is currently a placeholder, and since the whole project is self-contained, the placeholder is not automatically replaced with julia's version number.

Maybe I could change it to "V3.1.4-DEV.999".

Would you prefer cover relate dissues to be filed in the new repo?

I can accept both.
My thoughts are:

  • Non-functional discussions are appropriate for a new repo.
    For example, modifying the saturation of the background image, the choice of font
  • If it is an issue that should be fixed, then the issue should be opened in julia's repo.
    For example: some characters are not displayed in julia's manual

@ViralBShah
Copy link
Member

Got it. "V3.1.4-DEV.999" is definitely preferable.

@ViralBShah
Copy link
Member

How hard would it be to get NEWS and HISTORY both included in the pdf (and the html too) with each release being a chapter in the pdf?

@ViralBShah ViralBShah merged commit 8a3b4ab into JuliaLang:master Apr 23, 2022
@inkydragon inkydragon deleted the doc-pdf-cover branch April 24, 2022 07:03
@inkydragon
Copy link
Member Author

How hard would it be to get NEWS and HISTORY both included in the pdf

Maybe just one line patch?

copy HISTORY.md to julia\doc\src, then apply this patch:

diff --git a/doc/make.jl b/doc/make.jl
index b331733984..5e3984de93 100644   
--- a/doc/make.jl
+++ b/doc/make.jl
@@ -177,6 +177,7 @@ const PAGES = [   
     "Standard Library" => StdlibDocs,
     # Add "Release Notes" to devdocs
     "Developer Documentation" => [DevDocs..., hide("NEWS.md")],
+    "Release History" => "HISTORY.md",
 ]
 else
 const PAGES = [

And we need to escape $.
@ViralBShah (Maybe this is a bug for Documenter.jl?)

ref: julia/HISTORY.md at master · JuliaLang/julia

md:

(i.e. echo `$(nothing)` will still error without running anything.)

tex:

-(i.e. \(echo `$(nothing)`\)
+(i.e. \(echo `\$(nothing)`\)

Output:

image

@ViralBShah
Copy link
Member

ViralBShah commented Apr 24, 2022

Escaping $ - can you file at Documenter.jl? These release notes look nice in the PDF! Can you submit a PR for that?

@inkydragon
Copy link
Member Author

Can you submit a PR for that?

I'll try to submit a pr when the Documenter.jl issue is fixed.
But I don't have much time at the end of this month.

@giordano giordano removed the merge me PR is reviewed. Merge when all tests are passing label Apr 28, 2022
Comment on lines +43 to +44
\DeclareFixedFont{\MainHeading}{T1}{phv}{b}{n}{1.5cm}
\DeclareFixedFont{\SecondaryHeading}{T1}{phv}{b}{n}{0.8cm}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@inkydragon I was able to extract the logs from the Docker build. It looks like these fonts are missing:

! Font \T1/phv/b/n/42.67912=phvb8t at 42.6791pt not loadable: metric data not f
ound or bad.
<to be read again> 
relax 
l.43 ...ixedFont{\MainHeading}{T1}{phv}{b}{n}{1.5cm}
                                                  

luaotfload | resolve : sequence of 3 lookups yielded nothing appropriate.
! Font \T1/phv/b/n/22.76228=phvb8t at 22.7623pt not loadable: metric data not f
ound or bad.
<to be read again> 
relax 
l.44 ...ont{\SecondaryHeading}{T1}{phv}{b}{n}{0.8cm}

Would this be a fatal error?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mortenpi I'm not sure, but I had no issues compiling locally with lualatex

Can you reproduce the build failure?
Or does the problem only happen with CI

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yea, it's consistent if you build with the Docker image. To reproduce, if you have Docker installed, you can just run

DOCUMENTER_LATEX_DEBUG=$PWD/pdf-logs make -C doc pdf texplatform=docker

This will also copy the logs to pdf-logs/, although you need to update Documenter to the latest master to get useful LaTeX logs out.

KristofferC pushed a commit that referenced this pull request May 16, 2022
* Add cover page
* use tikz logo
* Add "Release Notes" to devdocs

Co-authored-by: Viral B. Shah <ViralBShah@users.noreply.github.com>
(cherry picked from commit 8a3b4ab)
@KristofferC KristofferC mentioned this pull request May 16, 2022
67 tasks
@KristofferC KristofferC removed the backport 1.8 Change should be backported to release-1.8 label May 26, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docsystem The documentation building system
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Some improvements for the PDF of the manual
8 participants