README.md in rpub-0.3.0 vs README.md in rpub-0.4.0

- old
+ new

@@ -1,6 +1,6 @@ -# Rpub -- an ePub generator in Ruby [![Build Status](https://secure.travis-ci.org/avdgaag/rpub.png?branch=master)](http://travis-ci.org/avdgaag/rpub) +# Rpub -- an ePub generator in Ruby [![Build Status](https://secure.travis-ci.org/avdgaag/rpub.png?branch=master)](http://travis-ci.org/avdgaag/rpub) [![Gemnasium dependency status](https://gemnasium.com/avdgaag/rpub.png)](https://gemnasium.com/avdgaag/rpub) ## Introduction Rpub is a command-line tool that generates a collection of plain text input files into an eBook in ePub format. It provides several related functions to @@ -8,10 +8,11 @@ * Generation of table of contents * Packaging your eBook in an archive with additional README file * Embedding fonts * Easy previewing as you write +* .mobi compatibility ## Installation Rpub is distributed as a Ruby gem, which should be installed on most Macs and Linux systems. Once you have ensured you have a working installation of Ruby @@ -51,11 +52,12 @@ --- author: Your Name title: My new book version: 0.1.0 -This file is written in [YAML](http://yaml.org) and sets basic properties of your book project. +This file is written in [YAML](http://yaml.org) and sets basic properties of +your book project. Since regenerating your ePub file and opening it in a suitable reader application is cumbersome, Rpub can generate a simple preview document for you: $ rpub preview @@ -65,10 +67,28 @@ easy viewing in any browser. [Markdown]: http://daringfireball.net/projects/markdown [John gruber]: http://daringfireball.net +### Generating a .mobi file + +Since the ePub and Mobipocket file formats are very (_very_) similar it is +quite easy to create a `.mobi` version of your book, suitable for reading on +Amazon's Kindle. To do so, you will need to install the [kindlegen program +Amazon provides][kindlegen]. + +Here's how it works: + +1. Install `kindlegen` ([download it here][kindlegen]) +2. Compile your book as usual using `rpub compile` +3. Compile `my-book.epub` to `my-book.mobi`: `kindlegen my-book.epub`. + +Optionally, include your `my-book.mobi` in your package by adding it to your +list of packaged files (see "Packaging for distribution"). + +[kindlegen]: http://www.amazon.com/gp/feature.html?ie=UTF8&docId=1000765211 + ### Advanced features #### Packaging for distribution Often you want to distribute your ebook over the internet, along with some @@ -102,28 +122,44 @@ To enable the automatic generation of a table of contents, add the following configuration to your `config.yml` file: toc: true +Note that this only affects the human-readable table of contents, represented +as a page in your book. Rpub will alway generate the .epub table of contents +for you, which contains the machine-readable references to your chapters. It +will, by default, reference all chapter titles and subheadings for you, but +you can customize the number of levels that will be included using the +following in your `config.yml` file: + + max_level: 3 + #### Custom layout and styles When you compile a set of Markdown files to an ePub file, rpub uses a default HTML layout and set of styles to determine the look and feel of the book. These will do fine for most cases, but you can provide your own, if you are so inclined. Simply define a `layout.html` and/or `styles.css` in your project directory. Your HTML file will be parsed with Erb, an so you can include your writing -using the `yield` method: +using the `@body` instance variable: <html> <body> - <%= yield %> + <%= @body %> </body> </html> -**Note**: despite the name 'html' and `.html` extension, your file actually has +**Note 1**: this feature is actually provided by the [Kramdown gem][kramdown], +so have a look at [the standard Kramdown document template][doc] to see some +nifty tricks. + +[kramdown]: http://kramdown.rubyforge.org +[doc]: https://github.com/gettalong/kramdown/blob/master/data/kramdown/document.html + +**Note 2**: despite the name 'html' and `.html` extension, your file actually has to be XHTML-compliant. You can also provide custom layouts or styles to use when invoking the `compile` or `preview` commands, using the `-l` or `-s` options: @@ -134,20 +170,70 @@ $ rpub generate ### Command reference -* `rpub compile` -- generate .epub file -* `rpub package` -- create zip file with compiled book and other listed files -* `rpub preview` -- generate preview HTML file -* `rpub generate` -- copy default layout.html, styles.css and config.yml -* `rpub help` -- get help on subcommands -* `rpub clean` -- remove generated files +`rpub compile` +: generate .epub file +`rpub package` +: create zip file with compiled book and other listed files + +`rpub preview` +: generate preview HTML file + +`rpub generate` +: copy default layout.html, styles.css and config.yml + +`rpub help` +: get help on subcommands + +`rpub clean` +: remove generated files + +### Configuration reference + +`title` +: the book title (string) + +`descrption` +: one-line summary of the book (string) + +`creator` +: author name (string) + +`publisher` +: publisher name (string) + +`subject` +: book subject/category (string) + +`language` +: language code of the book contents, e.g. 'en' (string) + +`rights` +: copyright line (string) + +`version` +: version number of the book to include in the .epub filename (string) + +`toc` +: whether to generate a table of contents as book page (boolean, default false) + +`max_level` +: the maximum depth of the .epub table of contents (number, default 2) + +`ignore` +: list of files not to include in the epub, that otherwise would (array) + +`package` +: list of files to be included in the archive created by the package task (array) + + ### Examples -See the [examples directory](https://github.com/avdgaag/rpub/example) for two example projects. +See the [examples directory](https://github.com/avdgaag/rpub/tree/master/example) for two example projects. ### Documentation See the inline [API docs](http://rubydoc.info/github/avdgaag/rpub/master/frames) for more information. @@ -169,10 +255,10 @@ Please report any issues, defects or suggestions in the [Github issue tracker](https://github.com/avdgaag/rpub/issues). ### What has changed? -See the [HISTORY](https://github.com/avdgaag/rpub/HISTORY) file for a detailed changelog. +See the [HISTORY](https://github.com/avdgaag/rpub/blob/master/HISTORY.md) file for a detailed changelog. ### Credits Created by: Arjan van der Gaag URL: [http://arjanvandergaag.nl](http://arjanvandergaag.nl)