README.rdoc in bookshop-0.1.2

- old
+ new

@@ -1,44 +1,52 @@
-=== http://blueheadpublishing.github.com/bookshop/assets/logo.png
+=== http://3.bp.blogspot.com/-gYebAHHXpXs/T3aSYFIj6KI/AAAAAAAAACo/Rdo3WOqbihM/s320/bookshop_logo.png
 
     "a book publishing framework for today's publishing world"
-	
-bookshop is a book publishing framework for building pdf/(e)books based on HTML, CSS, and JavaScript. The framework is optimized to help publishers, editors, and authors quickly ramp-up, allowing them to jump in and develop their html-to-pdf/(e)book flows by favoring convention over configuration, setting them up with best-practices, standards and tools from the start.
 
+Bookshop is a an open-source book development and publishing framework for authors, editors, publishers and coders in today's publishing industry. Bookshop provides best-practices for developing your books in HTML/CSS/JS, allowing them to be transformed into potentially any book format (Print-PDF, PDF, mobi, ePub, etc.).
+
+A conceptual overview of bookshop: http://blueheadblog.blogspot.com/2012/03/announcing-bookshop-html-to-pdf-ebook.html
+
 bookshop hopes to simplify the process by:
 * using common tools like HTML/CSS to make the creation of your book comfortable and familiar, greatly reducing the learning curve for your developers, authors, agents, and other team members
 * providing a Ruby Gem to make building a book in HTML as easy as 'gem install bookshop'
 * pulling all the html-to-pdf/(e)book tools together into one place (princexml, kindlegen, epubcheck)
-* sticking with open-source tools to encourage community development
 * giving the developer a set of scripts to automate the redundant stuff
 * providing an architecture/structure that follows best-practices and simplification (DRY... Don't Repeat Yourself)
 
 == Getting Started
 
 === System Requirements
 
 * Ruby v1.8.7 or higher http://www.ruby-lang.org/en/downloads/
 
+(not required, but recommended for using other tools)
+* Java 1.5 or higher http://www.java.com/en/
+
 == Installation
 
+For detailed instructions for your particular platform, please see this link:
+
+https://github.com/blueheadpublishing/bookshop/wiki/Setting-Up-Your-bookshop-Environment
+
 === Install bookshop
 
     $ gem install bookshop
 
 === Install PrinceXML
 
-1. Go to PrinceXML website and follow the install instructions
+Go to PrinceXML website and follow the install instructions
 
-http://www.princexml.com/download/
+http://www.princexml.com/download
 
 == Using bookshop
 
 === Create a bookshop book
 
     $ bookshop new my_new_book
 
-	This will create a new bookshop book in /path/to/my_new_book with the following structure:
+	This will create a new bookshop book project in /path/to/my_new_book with the following structure:
 
   |-- book/                 # Source files for your book
       |--book.html.erb      # The master file
       |--frontmatter/       # Content at the front of the book (cover, title, preface, etc.)
       |--bodymatter/        # Main content of book (chapters, sections, etc.)
@@ -46,10 +54,16 @@
       |--assets/
           |--css/
               |--stylesheet.css
           |--images/
           |--js/
+      |--epub/              # epub specific files and contents
+          |--META-INF/
+          |--mimetype
+          |--OEBPS/
+              |--content.opf.erb
+              |--toc.ncx.erb
 
   |-- builds/               # All the builds are created here
       |--epub/
       |--html/
       |--mobi/
@@ -59,27 +73,31 @@
       |--book.yml           # Settings/Data for your book
 
 
 === Editing Your New Book
 
-==== Where does my Book really live?
+==== Editing your book source
 
+Currently, when you create a new bookshop project, it will generate the example book source for you. You can use this as a template, replacing the text with your own. But make sure to utilize the correct CSS microformat markup.
+
+For an explanation of the example, please see this article. - http://www.alistapart.com/articles/boom
+
 All of the source documents and assets for your book are stored in the +book/+ folder. So your stylesheets, images, text - everything used for building your book - lives here. Ideally, you should only every edit files in your +book/+ folder (with the exception of your config/book.yml file).
 
 ==== Why do the Source files end with +.erb+?
 
 The source files are all in ERB. ERB is a templating language for the Ruby programming language. Why is this cool? Because it means that you can use HTML _and_ you can embed Ruby code in your source files. In other words, you can do all kinds of cool programmy things. Like embed ruby functions and calls:
 
     <p>Today is <%= Time.now.strftime('%A') %>.</p>  # creates -> <p>Today is Thursday.</p>
 
 More information on ERB - http://www.ruby-doc.org/stdlib-1.9.3/libdoc/erb/rdoc/ERB.html
 
-==== One File to Rule Them All!
+==== The master file book.html.erb
 
-Your master file (which is used to build everything) is the +book.html.erb+ file (remember that we are in the +book/+ folder). You could of course just use this file and put all of your book contents here, making one enormous file, but we don't recommend it... 
+Your master file (from which everything is built) is the +book.html.erb+ file (remember that we are in the +book/+ folder). You could of course just use this file and put all of your book contents here, making one enormous file, but we don't recommend it... 
 
-==== The Magic of import()
+==== Import files into your master file
 
 Are you writing another "War and Peace"? We've created a nice way to make your epic book easier to manage. Rather than putting everything in the +book.html.erb+ file, you can +import+ files. This allows you to break your book up into smaller, more manageable pieces. This makes it soooooo much easier to manage your book. And others will thank you for it..
 
 You can import a file by using the import() function, for example:
 
@@ -102,31 +120,25 @@
 and in the +bodymatter/ch01/ch01.html.erb+ you could import more files
 
     <%= import('bodymatter/ch01/first_section.html.erb') %>
     <%= import('bodymatter/ch01/second_section.html.erb') %>
 
-==== Output-based Content
+==== Use the @output tag to create content based on output (pdf/html/epub/etc.)
 
-So what if you want to create content for certain builds only? Let's say you want to have a different title for the pdf then you do for the epub version of the book.
+So what if you want to create content for certain builds only? Let's say you want a certain section of your book to only be included in the pdf version of your book.
 
 No worries. We've created the handy Output Variable (@output) for you to use in this case... aren't we special?
 
 Currently we have three attributes you can call with @output - :html, :pdf, and :epub.
 
-Let's generate titles that change depending on the build, using a conditional statement (remember, everything is ERB, so we can use Ruby):
+Let's generate a section that will only be displayed in the pdf version of your book, using a conditional statement (remember, everything is ERB, so we can use Ruby):
     
-    <p>
-      <% if @output == :html %>
-        HTML Title
-      <% elsif @output == :pdf %>
-        PDF Title
-      <% elsif @output == :epub %>
-        EPUB Title
-      <% end %>
-    </p>
+    <% if @output == :pdf %>
+      <p>This is a pdf-only section</p>
+    <% end %>
 
-==== Book Variables -  The +config/book.yml+ file
+==== Use @book tags to reuse content throughout all book formats (the +config/book.yml+ file)
 
 Gosh, wouldn't it be cool to have a way to store bits of information that we use repeatedly throughout the book, like the ISBN, or the title? And then it would be great to be able to reference them from within the book source. That way we can change them once, in one place, rather than having to go looking for them throughout the entire book.
 
 We've provided a data structure for your book (in YAML) so you can store these pieces of data in variables that you can call within your source files.
 
@@ -151,22 +163,22 @@
     
     <p>The book isbn is <%= @book.isbn %></p>
     <p>The html title is <%= @book.html.title %></p>
     <p>The epub pub_date is <%= @book.epub.pub_date %></p>
 
-Note that you can construct and/or nest variables however you want to:
+Note that you can also construct and/or nest variables however you want to:
 
     # book.yml
     
     my:
       madeup:
         friend:
           name: dave
 
 Then call it in your source file with the variable:
 
-    <p>My made up friend's name is <%= @book.my.madeup.friend.name %>
+    <p>My made up friend's name is <%= @book.my.madeup.friend.name %></p>
 
 More info about YAML:
 
 http://en.wikipedia.org/wiki/YAML
 
@@ -187,10 +199,14 @@
 
 Please explore other creative ways to structure and enhance your book (we'd love to see how you are doing it).
 
 === Building Your First Book
 
+Each time you build a new book format, the source .erb files in your *book/* folder are built and copied to the build target folder. Then the final book format is generated from those newly generated files. For example, if you issue "bookshop build epub", the .erb source files are built and the resulting book.html and all the assets/ are saved to the *builds/epub/* folder. Then the target epub book format is generated from the *builds/epub* folder and saved back in the same folder.
+
+The great thing about this is that you can easily view the resulting book.html file in a browser to get a quick peak at the generated look and feel.
+
 To build an HTML format of your book from the ERB source:
 
     $ bookshop build html   # -> find the output in builds/html/book.html
 
 To build a pdf format of your book from the ERB source:
@@ -207,18 +223,19 @@
 
 http://www.princexml.com/doc/8.0/
 
 ==== Editing you epub document and options
 
+There are two main files (besides your actual book source) you will need to edit for the epub build are located in the +book/epub/OEBPS+ folder: content.opf (the Open Packaging Format) and the toc.ncx (the Navigation file).
+
+During the build process, the entire contents of the +book/epub/+ folder will be used, along with your book source files, to create your epub book format. You can add or edit any of the files in that folder if you like. Generally speaking, you will probably only ever edit the content.opf.erb and the toc.ncs.erb files.
+
 http://idpf.org/epub/30 - For an overview of EPUB
 http://idpf.org/epub/30/spec/epub30-ocf.html - For the specs on the epub file structures and contents
 
-
 We recommend consulting the EPUB documentation for specifics.
 
-There are two main files (besides your actual book source) you will need to edit for the epub build are located in the +book/epub/OEBPS+ folder: content.opf (the Open Packaging Format) and the toc.ncx (the Navigation file).
-
 ===== The *content.opf* file is the file which contains all of the primary information about your epub ebook (publisher, files included, date, etc.). 
 
 http://idpf.org/epub/20/spec/OPF_2.0.1_draft.htm - Specs on the .opf file
 
 ===== The toc.ncx file is the file which contains the structural tree of your book's navigation.
@@ -239,29 +256,35 @@
 
 == Description of bookshop app contents
 
 The default directory structure of a generated bookshop project:
 
-    |-- book/                 # Source files for your book
-        |--book.html.erb      # The master file
-        |--frontmatter/       # Content at the front of the book (cover, title, preface, etc.)
-        |--bodymatter/        # Main content of book (chapters, sections, etc.)
-        |--backmatter/        # Content at the back of the book (appendix, index, etc.)
-        |--assets/
-            |--css/
-                |--stylesheet.css
-            |--images/
-            |--js/
+  |-- book/                 # Source files for your book
+      |--book.html.erb      # The master file
+      |--frontmatter/       # Content at the front of the book (cover, title, preface, etc.)
+      |--bodymatter/        # Main content of book (chapters, sections, etc.)
+      |--backmatter/        # Content at the back of the book (appendix, index, etc.)
+      |--assets/
+          |--css/
+              |--stylesheet.css
+          |--images/
+          |--js/
+      |--epub/              # epub specific files and contents
+          |--META-INF/
+          |--mimetype
+          |--OEBPS/
+              |--content.opf.erb
+              |--toc.ncx.erb
 
-    |-- builds/               # All the builds are created here
-        |--epub/
-        |--html/
-        |--mobi/
-        |--pdf/
+  |-- builds/               # All the builds are created here
+      |--epub/
+      |--html/
+      |--mobi/
+      |--pdf/
 
-    |-- config/               # Your config and data settings
-        |--book.yml           # Settings/Data for your book
+  |-- config/               # Your config and data settings
+      |--book.yml           # Settings/Data for your book
 
 book
   Holds all the manuscript html code/files. This is where your master manuscript lives from which everything is built.
 
 builds
@@ -323,8 +346,9 @@
 We would like to thank:
 
 * The Ruby/Rubygems Team www.ruby-lang.org/
 * The Thor Team - https://github.com/wycats/thor
 * Hakon Wium Lie and Bert Bos for developing the book microformat http://www.alistapart.com/articles/boom
+* The PrinceXML Team - http://www.princexml.com/company/
 
 A List of Our Contributors:
 https://github.com/blueheadpublishing/bookshop/blob/master/CONTRIBUTORS.md
\ No newline at end of file