PDF generation updates: working version mimicing webBook style

[mikewesthad]

This PR brings the PDF generation pipeline up to speed with the webBook styling.

The PDF generation works through a python script under scripts/. It generations ofBook.pdfand scripts/ofBook.tex. The latter is useful for debugging - pandoc isn't too helpful when building a PDF fails. Opening up ofBook.tex in TeXworks makes debugging easier. It also allows for testing of style/layout before changing the python script.

Following the organization from @ofZach's pending PR (#68), I moved all the chapters to chapters/ and removed the chapter numbering. Two of the chapters needed small edits to get them working with the latex package for styling code (re: #69).

[bilderbuchi]

OK, some issues I found in my chapter after a quick look:

• Some overfull hbox on p241, I can probably fix/work around this.
• The rendering of the file tree on p245 was pretty messed up, maybe some unicode/font problem? If need be I can also scrap/rework this, as those line symbols have been problematic before.
• The rendering of the code block on p246/247 is messed up (get black diamond symbols strewn within, maybe tabbing chars?). Same on p256 and elsewhere. Also, the alignment is destroyed by the line wrapping in the first part, apparently.
• p251, there are some note symbols in the diff code block, they shouldn't be there. Also, a bit later in the text.
• p262, section 11.3.5.4, line 2 - the quotation marks are wrong (these are the quotes you'd normally use in Latex to mark beginning/end of quote when using german quotes, btw)

[bilderbuchi]

So, I found out that the black diamonds are in place of the vertical bars, and the notes should be @ symbols. Apparently a problem with the fira font - we need to use at least version 3.110 (gah, now even fonts have version numbers! >:-( )

Quotation marks seem to be wrong everywhere. Not sure about the german quotes statement before. Not sure how to fix this.

Anything specific why you made the margins so wide/the textwidth so small? In my old setup, the textwidth is about 6 chars wider, and that was the standard setup I think. (also: 2in inner margin looks really excessive. would be interested in the reason for this)

[mikewesthad]

@bilderbuchi,

1. Overfull hbox with inline code. One fix would be to tell listings that we allow line breaking on underscores literate={\_}{}{0\discretionary{\_}{}{\_}}.
   2-4) I believe that this is a font issue. FiraMono doesn't appear to have symbols for |, └──,├── or @ defined. If I switch to loading a different font, those characters render. I am puzzled that these characters render in the web book.
2. I don't know why this is happening, but adding the --no-tex-ligatures flag to pandoc command fixes it. The double quote marks were being converted by pandoc into the german quote marks.

I can add the changes for 1 and 5 in a PR.

[bilderbuchi]

1. yes. where do I put that? I can also probably just rename that last one to something manageable.
   2-4) I'm not sure if you have already read my most recent comment, or what version of Fira you're looking at, but I just replaced the mono fonts with the newest version, which fixes most of the problems (@ and | are there, and the |, └──,├── are there. The remaining problem is that the latter symbols are in the wrong location (at the end of the line). (and that the textwidth is still too small)
2. I can confirm that, I also added --smart, if I read the manual section for no-tex-ligatures correctly, that's the smart thing to do.

[mikewesthad]

Actually, I figured I'd check if there's a more recent version of firaMono on mozilla's repo. Turns out there is, and that version has | and @ properly defined. So everything is fixed except for:

I'll PR the changes

[bilderbuchi]

also, add breakatwhitespace=true to the lstset call! fixes stuff like .gitignore getting linebroken after the dot!

[bilderbuchi]

any input w.r.t the margins?

[mikewesthad]

Oh. Seems we're on the same page. literate goes in \lstset. I'll add breakatwhitespace=true.

What specifically about the margins?

[bilderbuchi]

last part of my comment above, especially the inner margin and textwidth. huh, github commenting breaks down a bit if two people are on concurrently. :-D

[bilderbuchi]

hm, with the tree thing, there seems to be some linebreak weirdness (if you compare to the markdown or tex file content, something gets skipped). also, the listing frame is messed up.

[mikewesthad]

Ahh, oops. My apologies - yeah I missed that comment. I was playing with the margins to try and fit more text on each page. The prior version felt like there was too much whitespace and that the line width was too narrow for the code. Maybe I am missing a latex fundamental concept about margin/textwidth, though.

Hmm, which markdown file has the weirdness? chapter.md, chapter_modified_for_print.md, or both?

[bilderbuchi]

well, basically more margin = less textwidth. also, the inner margin is the one that makes space for the binding, note taking typically should happen in the outer margin (which is therefore typically larger). textwidth = pagewidth - inner - outer (I think, check the geometry package manual). margin sets all margins, so that at least seems redundant here.
I'll check it out later, a bit busy atm.

no, the weirdness is only in the pdf, markdown and tex look ok.

[mikewesthad]

Ohhhh, I think I'm on the same page as you now. The ofBook version that I was generating from your shell script had really huge margins. I must have been using an old version, or I must have made some tweaks a long time ago that I had forgot about. Now that I'm checking out the v0.1.0 release, I see that something was messed up on my end. The margins in v0.1.0 look fine. Here I was thinking that my margins were increasing the textwidth over the previous version (since changing margin, changes textwidth). They were only increasing the textwidth relative to my weird local version. That's why I was so confused by your initial comment that textwidth was smaller in my version.

We can revert back to your settings.

As for the redundancy. I was setting all the margins in one command, which destroys the 2-sided layout. Then, I overrode the inner+outer in the second commands to restore the 2-sided layout. Seemed like less work than specifying all the different margins individually, but I should've gone the verbose route for clarity purposes.

[bilderbuchi]

OK, an update re: the funny issue with the box drawing characters in a listing:
Apparently that's a problem of the listings package, google "latex utf8 listings" or so and you will see. I tried applying the really magical hacky solution approach but didn't get anywhere for some reason, so I fell over and printed the filetree with ascii characters as a workaround. 😫

[mikewesthad]

Hmm, this is frustrating. Your code block isn't the only one affected by this. I remember seeing the ␣ character all over the place in code blocks - specifically, anywhere the code block contains strings. E.g. "Hello World" becomes "Hello␣World". I don't have time right now to look into this, but maybe later in the week