Unclear Readme

[colemanfoley]

I found the Readme unclear in places.

1. What does it mean to apply pull requests against index.md? I see that edits to text in the book are usually made to the relevant markdown file, ie 03-internals.md. Is that what people are supposed to do, or are we supposed to make the changes in, say, chapter 3, then build the book, then make a pull request?

2. Resolving the pdflatex dependency is somewhat treacherous without more detailed instructions. I spent a lot of time trying to figure it out, first Googling 'pdflatex',with unclear results, then installing BasicTex, as Pandoc's installation guide seemed to recommend. On attempting to build, I got the following:

You need pdflatex
OS X: http://www.tug.org/mactex/
Then find its path: find /usr/ -name "pdflatex"
Then symlink it: ln -s /path/to/pdflatex /usr/local/bin
pandoc -s 'backbone-fundamentals'.md -o 'backbone-fundamentals'.pdf
--title-prefix 'Developing Backbone.js Applications'
--normalize
--smart
--toc
--latex-engine=xelatex
pandoc: xelatex not found. xelatex is needed for pdf output.

So I guess I need MacTex. I saw in another pull request that you want a cross-platform PDF solution, but I think a little more guidance for each major platform could make contributing less daunting.

[addyosmani]

Hey @colemanfoley. Thanks for the feedback. I've updated the readme to hopefully be a little more clear on the contribution process and overall structure of the repository. Is the updated version preferable?

Regarding PDFs - we've historically had issues with cross-platform PDF compilation. I unfortunately haven't been able to find the time to put together a succinct solution for this but I've added a note to the README to at least try setting expectations.

If you (or another contributor) have better luck drafting a solution here I would be happy to adopt it. When time is a little more available, I hope to expand the guide to better cover this area.

[colemanfoley]

Yes, I think that's a significant improvement. Thank you. As for the PDFs, yeah, I guess that's kind of a big thing, that probably shouldn't be thrown in with a PR for a small issue, so I'll go ahead and close this.