Make language specification available as a PDF

[sake92]

The PDF is now published at https://scala-lang.org/files/archive/spec/2.13/spec.pdf

---

This is an attempt to help with scala/bug#10218
Wkhtmltopdf (v 0.12.6-dev) is used for generating PDF from HTML(s).

I tried first to render with existing setup, but had to make a few changes in print CSS and hide some divs from output.
Unfortunately, Mathjax doesn't behave well:

• takes long to load
• outputs small fonts when using wkhtmltopdf (I tried to set zoom etc, doesn't help)
• puts newline before every math expression in PDF... (no idea why does that)

This solution uses a more lightweight library called KaTeX.
A problem with KaTeX is that you can't escape a $ sign outside of math rendering scope.
Mathjax has this processEscapes: true property so you can do a \$ anywhere.
So I had to pick a different delimiter, ACUTE ACCENT (´) character (I also call it "forward-tick").

Here is PDF example: https://www.dropbox.com/s/yjcrs2ztk9myd0a/Spec.pdf?dl=0
NOTE: I used Batch script, didn't try Bash script, if someone could verify it works also that would be great. 🙂

[sake92]

I signed the CLA.

[adriaanm]

Wow, great work! 😍

I browsed the generated html locally and it looks really good.

[smarter]

Very cool. May I request that we store the generated output at http://www3.scala-lang.org/files/archive/nightly/pdfs/ScalaReference.pdf where version 2.9 currently lives ? This is what you get when you search for "scala specification" on Google Scholar currently.

It would also be useful to have the first page of the PDF explain that this document was generated from

[sake92]

Thanks guys! I have 2 quick questions:

1. In section function types the return type in code snippet is R but should be U?
2. In Return Expressions the NonLocalReturnException is mentioned but I couldn't find it in Scaladocs.. Should that be NonLocalReturnControl?

@smarter "that this document was generated from" ..? HTML version of Scala spec?
If that's what you meant, I added it now.

[smarter]

In section function types the return type in code snippet is R but should be U?

No because it's describing the definition of FunctionN which uses R, I think it's fine as is.

In Return Expressions the NonLocalReturnException is mentioned but I couldn't find it in Scaladocs.. Should that be NonLocalReturnControl?

Yes.

@smarter "that this document was generated from" ..? HTML version of Scala spec?
If that's what you meant, I added it now.

Yes, that's what I meant.

[SethTisue]

@sake92 interested in returning to this...?

[sake92]

@SethTisue I merged the latest changes and updated the linked PDF example.
If there's anything else to be done regarding this, please let me know.

[SethTisue]

@sake92 can you rebase and squash this into a smaller number of commits?

I put this on the 2.13.1 milestone since it isn't a release blocker, but it could still make 2.13.0-RC1

[sake92]

@SethTisue I did the rebase/squash thing. Never done squashing before, I hope everything's ok.. 😄

[SethTisue]

I took the liberty of force-pushing to your branch to fix a further merge conflict and to make some changes to the bash script.

note to anyone who wants to try this, on MacOS you can brew cask install wkhtmltopdf (note the cask)

the bash script needs some more work. I need to work on some other things right now, but I'll come back to this

[SethTisue]

I stabbed it with my steely knives for a while, but we won't be dining on roast beast tonight, it seems.

The bash script now generates a PDF on my Mac (Darwin doesn't do ls -I, and I had to make it ignore some weird http error I don't understand but hopefully doesn't matter, and my shell scripting fu is most definitely stoppable, and ...)

but Travis says:

The switch --print-media-type, is not support using unpatched qt, and will be ignored.
Unknown long argument --window-status

And then later it prints some dusty old Google Code URL, remember Google Code? So apparently brew install wkhtmltopdf on MacOS doesn't give us the same version that sudo apt-get install wkhtmltopdf gets us on Travis, what fun.

It's first and 10 again, at least.

[SethTisue]

in a dusty corner of the internet I found an old thing where someone used:

install:
    - mkdir wkhtmltopdf
    - wget http://wkhtmltopdf.googlecode.com/files/wkhtmltopdf-0.9.9-static-amd64.tar.bz2
    - tar xvjf wkhtmltopdf-0.9.9-static-amd64.tar.bz2 -C wkhtmltopdf
    - mv wkhtmltopdf/wkhtmltopdf-amd64 wkhtmltopdf/wkhtmltopdf
    - export PATH=$PATH:$PWD/wkhtmltopdf/

seems like I ought to be able to massage this into something that works

[SethTisue]

Leaving scala/bug#10218 open for now since I still need to do the publish-it-to-the-website part. So let's not pop too many champagne corks until I get around to that :-)

Thank you, @sake92, for taking this on and remaining committed to it despite the long wait.

[sake92]

Thank you @SethTisue for all the help! Glad that this is finally over. 😄

[SethTisue]

as for the publishing part: at e.g. https://travis-ci.org/github/scala/scala/jobs/749278429 we see scripts/travis-publish-spec.sh running and appearing to rsync files up to chara including a spec.pdf, but https://scala-lang.org/files/archive/spec/2.13/spec.pdf is 404

https://github.com/scala/scala-dev/blob/scala-dev/.github/ISSUE_TEMPLATE/release.md has instructions for ssh'ing to chara (I can never remember). if I ssh there and look in /home/linuxsoft/archives/scala/spec/2.13/, spec.pdf is there

so, okay, now this is familiar from doing releases actually, you have to wait for https://scala-webapps.epfl.ch/jenkins/view/All/job/production_scala-lang.org-scala-dist-archive-sync/ to sync the files into production

but this PR was merged two days ago and that job has run a number of times since then...

ah but then there's also https://scala-webapps.epfl.ch/jenkins/view/All/job/production_scala-lang.org-builder/ ... hmm no, that doesn't seem relevant

I triggered https://scala-webapps.epfl.ch/jenkins/view/All/job/production_scala-lang.org-scala-dist-archive-sync/154699/ manually just now on the off chance it might help

interesting, it's been running for 12 minutes now... recent past runs seem to be in the 3–10 minute range (why such variation?)

OMG THAT DID IT, we're live! https://scala-lang.org/files/archive/spec/2.13/spec.pdf

champagne consumption may commence 🥂

[smarter]

Awesome! By the way, if I type "scala language specification" on Google the first result is the venerable spec of Scala 2.6 (https://www.scala-lang.org/docu/files/doc/scala-documentation/ScalaReference.pdf), any chance that could redirect to the latest version?

[SethTisue]

@fsalvi could you add that redirect, please?

[fsalvi]

Ok, I added a redirect to the new spec page.