fix instructions for ubuntu installation and for running on all platforms

[candeira]

A number of changes, hopefully self-explanatory, to aid newcomers interested in installing and running the program.

Offtopic but not completely, since this issue is about installing and running:

I've managed to use the Magic Book Project to obtain a pdf, and also to generate the book website for The Nature of Code. However, the paths for the book's js, img and css resources are different in the asciidoc sources from where the create_html_chapters process leaves everything.

Are you interested in creating a default file structure that other book authors can use for their work and which will leave a working website structure after the create_html_chapters command? Is there any way I can help?

[runemadsen]

This looks great. Thanks so much @candeira. Merging in right now.

We are very aware of the links not working in the chapters, and it's high on the list of things to fix. If you want to try and take a stab at it, I'm here to help, but otherwise I'm hoping to look at it in a couple of weeks when I'm not so backed up.

[candeira]

The path fix for links/images/js/css might require to also intervene in the Nature of Code repo, to reorganize where things go. I'll break a couple of things over Christmas to see if I can get any result you like.

Some thoughts about this reorganization, please let me know what you think:

• this is one of those "convention over configuration" cases where, as far as possible, we'd want to define a default file structure, get it right, and have everyone follow it, rather than forcing users to write their own config file or a makefile. Book authors should be able to clone an empty repo with a starter structure and some template .asc files, and start writing there.
• on the other hand, our default file structure should probably include a default config file to be followed by the asciidoc gem. That way we could have an easy start for beginners, and a way to complicate the project for those who need it.
• right now the example book repo (The Nature of Code) has a mix of javascript-by-book-author and javascript-by-original-shippers (jquery, processingjs). This could probably be organised by using git submodules.

Cheers,

Javier

[shiffman]

Hi Javier,

Thank you so much for your thoughts. Our goal for this project has always been to make "magic book" available and easy to use for all authors, including non-tech authors with no interest in git, etc. We're a far way off from this, but any help would be greatly appreciated!

I've noticed the issue you're referring to as I have to re-organize all my nature of code files before I push them to my site.

If you want to bang into this, feel free to fork the Nature of Code repo also!

I have a long list of things to get to with the Nature of Code book still, but eventually I hope to return to working on making Magic Book more accessible.

Dan

[candeira]

Hi Dan,

Thanks for The Nature of Code. I'm reading it through and enjoying it enormously.

I'll probably give the Magic Book and the Nature of Code repos a shake during the holiday, see if something comes out that works for you.