[doc] Add a Cover page to PDF doc #45034
Conversation
ViralBShah
added
backport 1.8
|
Two quick comments:
|
|
Sure, here's a quick mock-up of my thoughts.
|
|
Oh, and re:
You can run this yourself and just upload the |
|
@ViralBShah Should we only show "Chapter" title again?
|
|
@tecosaur Some quick attempts, fonts still need to be adjusted
Actually, I don't want to add any binaries to git.
|
|
Looking good. Two other things I'd advocate for
Lastly, regarding this comment:
|
|
How about pulling the PDF logo from JuliaLang/julia-logo-graphics in In any case, if a tikzpicture is needed, I used xyz2tex/svg2tikz and Inkscape to translate the SVG. See below. Julia logo as tikzpicture |
|
Seems like using the tikzpicture is perhaps a better option, since it can be directly embedded and updated in git. |
|
New changes:
Accepted some suggestions from tecosaur:
|
|
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
Lightened + saturated
(original)
Seen in greyscale
Both have a similar lightness, but the second looks less "washed out" compared to the original image thanks to the increase in saturation. |
|
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. |
I tried removing the gray background and adding a white translucent mask, and it looks good too.
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?
|
Get it.
Done. Now "Release Notes" is the last chapter in
|
|
I feel like this pr is ready to merge. |
Am I correct in guessing this would allow you to switch the colours for lightened + saturated variants, and avoid translucent masking?
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.
In that document (https://tecosaur.com/lfs/bmc/bmc.pdf) I used mini-tocs on chapter cover pages too:
I find this sort of structure particularly good for long documents. |
I guess so. I will try your suggestion this weekend.
This is a brilliant idea! I'll make a note of this first. The main purpose of this pr is to give julia a not bad cover. (Maybe 7/10 is enough) |
|
Glad my thought helped :)
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.
|
|
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. |
|
Should we merge this one for now, and keep making improvements in future PRs? This is already a strict improvement. |
Yes, just do it. If there is any improvement, I'll open a new pr. |
|
@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 |
|
The dev should have the development version listed (not just DEV). Would you prefer cover relatedissues to be filed in the new repo? |
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".
I can accept both.
|
|
Got it. "V3.1.4-DEV.999" is definitely preferable. |
|
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? |
Maybe just one line patch? copy 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 ref: julia/HISTORY.md at master · JuliaLang/julia md: tex: -(i.e. \(echo `$(nothing)`\)
+(i.e. \(echo `\$(nothing)`\)Output:
|
|
Escaping |
I'll try to submit a pr when the Documenter.jl issue is fixed. |
| \DeclareFixedFont{\MainHeading}{T1}{phv}{b}{n}{1.5cm} | ||
| \DeclareFixedFont{\SecondaryHeading}{T1}{phv}{b}{n}{0.8cm} |
There was a problem hiding this comment.
@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?
There was a problem hiding this comment.
@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
There was a problem hiding this comment.
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.
* Add cover page * use tikz logo * Add "Release Notes" to devdocs Co-authored-by: Viral B. Shah <[email protected]> (cherry picked from commit 8a3b4ab)
Close #35495.
Add some custom TeX styles include:
cover.tex: The main definition of the cover, used to replace the default\maketitlecommand.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.devdoc.Old design
- [PDF @ 5dc9ac4-tikz-bg](https://drive.google.com/file/d/1JzmnEKodYegfkY-eXm2lGkDkKbBJd688/view?usp=sharing)PDF @ 63816405e9-no-subtitle
PDF @ 8bb4a0d-remove slogan