Today is <%= Time.now.strftime('%A') %>.
# creates ->Today is Thursday.
More information on ERB - http://www.ruby-doc.org/stdlib-1.9.3/libdoc/erb/rdoc/ERB.html ==== The master file book.html.erb 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... ==== 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: <%= import('a_whole_chapter.html.erb') %> This would import the file +book/a_whole_chapter.html.erb+ You can also create sub-folders and group your files there. For example, in your book.html.erb file you could import: <%= import('bodymatter/ch01/my_first_section.html.erb') %> This would import the file +book/bodymatter/ch01/my_first_section.html.erb+ Note that you can also nest import files into imported files. So in your +book/book.html.erb+ <%= import('bodymatter/ch01/ch01.html.erb') %> 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') %> ==== 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 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 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): <% if @output == :pdf %>This is a pdf-only section
<% end %> ==== 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. Here's an example +config/book.yml+ file with some Book Variables: # book.yml isbn: 1234567891011 html: title: An HTML Title pdf: title: A PDF Title pub_date: 12/13/2012 epub: title: A EPUB Title pub_date: 11/13/2012 You can then use these Book Variables in your book source file:The book isbn is <%= @book.isbn %>
The html title is <%= @book.html.title %>
The epub pub_date is <%= @book.epub.pub_date %>
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:My made up friend's name is <%= @book.my.madeup.friend.name %>
More info about YAML: http://en.wikipedia.org/wiki/YAML ==== Mixing it up So, do you want to see something cool? Now that we have the Output Variable and Book Variables, we can combine them to do nifty things, like:The ISBN is <%= @book.isbn %>
Title: <% if @output == :html %> <%= @book.html.title %> <% elsif @output == :pdf %> <%= @book.pdf.title %> <% elsif @output == :epub %> <%= @book.epub.title %> <% end %>
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: $ bookshop build pdf # -> find the output in builds/pdf/book.pdf To build an epub format of your book from the ERB source: $ bookshop build epub # -> find the output in builds/epub/book.pdf ==== Editing your pdf document options We recommend consulting PrinceXML's documentation concerning PDF options. http://www.princexml.com/doc/8.0/ ==== Editing you epub document and options We decided to keep away from a generator model for the epub, in favor of allowing the developer to have full control of the epub file in all its aspects. The build command for epub is merely to build the main html file from the .erb source files and then to zip them up into the epub format. 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). ===== 1. 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 ===== 2. The toc.ncx file is the file which contains the structural tree of your book's navigation. http://idpf.org/epub/20/spec/OPF_2.0.1_draft.htm#Section2.4.1.2 - Specs on the .ncx 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.ncx.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. == Example Book We've provided an example book for you already in the +book/+ folder. You can use this as an example of how to structure your book and to use ERB, Book Variables, and Output Variables. Simply create a new book: bookshop new name_of_book Then take a look at the example book in the +book/+ folder. You can then build the book into whatever format you like. == 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/ |--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/ |-- 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 Holds all the output files built from the html builds/epub When building the epub, the generated output will reside here in an .epub file. You can rename the .epub extension to .zip then unzip the file to view the contents. build/mobi When building the mobi asset, the generated output will reside here as "book.mobi" build/pdf When building the pdf book, the generated output will reside here as "book.pdf" config application-wide variables and configurations will go here == Get Involved 1. Fork the repository. 2. Pick an issue (or feature you want to add). 3. Make changes to your forked code. 4. Add tests so that we don't accidentally break your addition with our future commits. 5. Commit to your git (forked) repository. 6. Let us know about your code and we'll review/merge it into the master. 7. And pat yourself on the back for contributing to an open source project!! == License Copyright (C) 2011, 2012 by BlueHead Publishing, Inc (http://blueheadpublishing.com) Bookshop is available under either The "New" BSD License or The MIT License Please see the LICENSE file for further information == Thanks 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