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.

Sign up for GitHub

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

Jump to bottom

Some improvements for the PDF of the manual #35495

Closed
3 tasks done
ViralBShah opened this issue Apr 15, 2020 · 19 comments · Fixed by #45034
Closed
3 tasks done

Some improvements for the PDF of the manual #35495

ViralBShah opened this issue Apr 15, 2020 · 19 comments · Fixed by #45034
Labels
docs This change adds or pertains to documentation docsystem The documentation building system

Comments

@ViralBShah
Copy link
Member

ViralBShah commented Apr 15, 2020 •
edited
Loading

Nice to have:

Edit: I updated the title of this issue to cover various issues in the PDF of the manual.

Basically have to go 50 pages to get to the "Getting started" part of the manual, which is chapter 14.
@ViralBShah ViralBShah added the docsystem The documentation building system label Apr 15, 2020
@ViralBShah
Copy link
Member Author

ViralBShah commented Apr 16, 2020 •
edited
Loading

The pdf of the Julia manual opens with a whole section on Release Notes, where each section of our release notes is a chapter in the documentation. This makes the documentation have many chapters in the beginning with just a couple of lines on each page. I suggest that we make all of release notes one chapter, if it is easy to do.

I suspect this happens because in the web version, the next page from the landing page is the release notes. However, in the online docs, one probably uses the toc on the left for navigation.

@mortenpi
Copy link
Contributor

The reason is that the NEWS.md page, while "hidden", is actually the same level as the Home/Manual/Base/etc. chapters, and so it becomes a separate \chapter. It might be possible to make it a lower-level page in the PDF or something along those lines.

@ViralBShah
Copy link
Member Author

I guess showing release notes to someone that early on in even in the web version doesn't seem like a good idea. Perhaps we can include it as a link rather than as a separate page? The level of information in the NEWS file as we currently ship it is significantly more technical than the rest of the manual.

@ViralBShah
Copy link
Member Author

Actually, is it possible to remove the NEWS altogether from the PDF? It is good the way it is in the web version, but doesn't add much value in the pdf.

@ViralBShah
Copy link
Member Author

The TOC has way too much detail. Would be nice to present fewer levels of information in the Table of Contents.

@ViralBShah ViralBShah changed the title Julia Release notes in the pdf of the Julia manual Some improvements for the PDF of the manual Apr 27, 2020
@ViralBShah
Copy link
Member Author

Spacing issues in TOC:

Screen Shot 2020-04-27 at 6 14 57 PM

@ViralBShah ViralBShah added the docs This change adds or pertains to documentation label Apr 27, 2020
@ViralBShah
Copy link
Member Author

ViralBShah commented May 26, 2020 •
edited
Loading

How does one go about fixing the latex generated that finally builds this PDF? Is it something in our Julia code, or some other tool that is harder for us to modify?

@ViralBShah
Copy link
Member Author

Self-answer: https://github.com/JuliaDocs/Documenter.jl/blob/master/src/Writers/LaTeXWriter.jl

ViralBShah added a commit that referenced this issue Jun 16, 2020
@ViralBShah
Partial fix for #35495
f2c6796 
This removes the NEWS.md link at the bottom of the first page of the
manual. Given that we link to it prominently on top of the page, I
feel this is ok.

This will remove Section II of the PDF manual, where the release notes
take 15 pages (because ofthe way markdown gets converted to PDF).
@ViralBShah ViralBShah mentioned this issue Jun 16, 2020
Merged
@ViralBShah ViralBShah changed the title Some improvements for the PDF of the manual [WIP] Some improvements for the PDF of the manual Jun 16, 2020
@ViralBShah ViralBShah mentioned this issue Jun 16, 2020
Closed
4 tasks
ViralBShah added a commit that referenced this issue Jun 17, 2020
@ViralBShah
Remove NEWS.md from the PDF of the manual (#36312)
43fd66c 
* Partial fix for #35495

This removes the NEWS.md link at the bottom of the first page of the
manual. Given that we link to it prominently on top of the page, I
feel this is ok.

This will remove Section II of the PDF manual, where the release notes
take 15 pages (because ofthe way markdown gets converted to PDF).

* Better layout for the generated PDF
KristofferC pushed a commit that referenced this issue Jun 25, 2020
@ViralBShah @KristofferC
Remove NEWS.md from the PDF of the manual (#36312)
ec9b512 
* Partial fix for #35495

This removes the NEWS.md link at the bottom of the first page of the
manual. Given that we link to it prominently on top of the page, I
feel this is ok.

This will remove Section II of the PDF manual, where the release notes
take 15 pages (because ofthe way markdown gets converted to PDF).

* Better layout for the generated PDF

(cherry picked from commit 43fd66c)
simeonschaub pushed a commit to simeonschaub/julia that referenced this issue Aug 11, 2020
@ViralBShah @simeonschaub
Remove NEWS.md from the PDF of the manual (JuliaLang#36312)
2702bfb 
* Partial fix for JuliaLang#35495

This removes the NEWS.md link at the bottom of the first page of the
manual. Given that we link to it prominently on top of the page, I
feel this is ok.

This will remove Section II of the PDF manual, where the release notes
take 15 pages (because ofthe way markdown gets converted to PDF).

* Better layout for the generated PDF
@inkydragon
Copy link
Member

inkydragon commented Jan 6, 2022 •
edited
Loading

  • Present lesser levels of subchapters in the TOC (It is almost 20 pages right now)
  • The spacing for chapter numbers in the TOC is not sufficient

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

TOC-baseline (14p) v.s. inc spacing for chapter numbers (3p)

patch3: en-toc-patch

only show "chapter" + use compact TOC spacing
image

inc spacing for chapter numbers
image

ref: The memoir class doc: memman.pdf

We only need to override writeheader function in our make.jl.

@ViralBShah
Copy link
Member Author

Yes let's do it.

@inkydragon inkydragon mentioned this issue Jan 7, 2022
Closed
@inkydragon
Copy link
Member

Have a cover page with some design and Julia logo

I've designed a cover page based on julia's homepage.
And there are many other choices: titlepages.pdf.

image

patch:

play with it

The tex code in my repo is self-contained, you don't need to clone julia's repo to compile PDF documents.
You just need to select the right branch (en-cover-page), clone the repo, go into the right folder (doc-en/), and build the PDF.

@ViralBShah
Copy link
Member Author

@inkydragon May I request you to submit a PR? This would all be great to have.

@inkydragon
Copy link
Member

Of course, I had the pleasure of designing the cover for julia's document.

My plan is: After #43698 is merged or I get some feedback, I'll open a new pr.

The main problem: finding a suitable way to customize the Documenter style.
It's fine to put everything into make.jl, but there must be a cleaner way to do it.

@ViralBShah
Copy link
Member Author

Also cc @fredrikekre

@inkydragon
Copy link
Member

inkydragon commented Jan 7, 2022 •
edited
Loading

Good News and Bad News
The good news is that we are about to fix all the problems mentioned in this issue.
The bad news is: I found more issues.

Take julia-1.8.0-DEV.pdf as an example.

New todo list:

Serious issues affecting reading

  • Internal Links Dead links in pdf documentation #43652 pdf manual 1.5.2 links #38054 .
    Almost all internal links are dead except for the link pointing to base/stdlib
  • p453 (Chap 39 Unicode Input): Pick the right font to display the Unicode Input table.
    You may need both math font and emoji font.
  • p456 (40.2 Command-line switches for Julia): Long table truncation
  • p190 (15.4 Strided Arrays): Long form item line break
  • p1416 (before "Build dependencies"): md link conversion failed
  • p1418 (104.2 Linux/Architecture Customization): HTML conversion failed.
    HTML and markdown are mixed in the table.

Optional improvements

  • Centering the tables
  • Do not show empty entries in "Release Notes"
  • ...

@ViralBShah
Copy link
Member Author

I think we can remove the release notes from the manual altogether, and instead just link to them.

@ViralBShah ViralBShah changed the title [WIP] Some improvements for the PDF of the manual Some improvements for the PDF of the manual Mar 14, 2022
@ViralBShah
Copy link
Member Author

With the improvements discussed in #43698 (comment), all the relevant items have been taken care of. I feel comfortable closing this.

A big shoutout to @inkydragon for making most of this happen.

@ViralBShah
Copy link
Member Author

ViralBShah commented Apr 5, 2022 •
edited
Loading

The only nice to have thing is to see if the Julia logo can be included on the cover page. The proposed design above would be great if we can check it into the doc directory.

@ViralBShah ViralBShah reopened this Apr 5, 2022
@inkydragon inkydragon mentioned this issue Apr 19, 2022
Merged
@ViralBShah
Copy link
Member Author

Thanks @inkydragon for seeing this through across multiple PRs!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
docs This change adds or pertains to documentation docsystem The documentation building system
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

[doc] Add a Cover page to PDF doc inkydragon/julia
3 participants
@mortenpi @ViralBShah @inkydragon