diff --git a/README.md b/README.md deleted file mode 100644 index 231b4e8..0000000 --- a/README.md +++ /dev/null @@ -1,2 +0,0 @@ -# smd_ebook -Create e-books (e.g. Kindle/ePub) from Textpattern content diff --git a/README.textile b/README.textile new file mode 100644 index 0000000..9402104 --- /dev/null +++ b/README.textile @@ -0,0 +1,235 @@ +h1. smd_ebook + +There are a few ways to create E-books suitable for e-readers like Kindle / Kobo / Nook / etc: + +* "Install Calibre":http://calibre-ebook.com/ and use the software to guide you towards creating your book +* Install a plugin for Adobe InDesign and let it help you create the book from your DTP files +* Download the "command-line Kindlegen":http://www.amazon.com/gp/feature.html?ie=UTF8&docId=1000234621 tool, create all the input files manually and hope +* Upload the Kindlegen program to your Textpattern web host and use this plugin to convert one or more articles into an E-book + +The last one is of course the focus of this plugin! Features: + +* Choose articles to be converted -- order of articles in final book is alphabetical by URL title +* Standard Textile formatting governs the (multi-level) table of contents and document entry points (plugin will automatically create ToC entry points if you choose) +* Set cover art as article image +* Enter Description, Publisher, Genre, Author notes and Price in plugin or use article fields (useful for publisher sites to allow authors to publish their own content) +* Tweak files if necessary before final E-book generation +* Download files for distribution via third party sites, or send them to Txp's Files tab ready for direct download by others + +h2. Installation / uninstallation + +Requires Textpattern 4.5.0+ and PHP5+ + +Download the plugin from either "textpattern.org":http://textpattern.org/plugins/NNNN/smd_ebook, or the "software page":http://stefdawson.com/sw, paste the code into the Txp _Admin->Plugins_ pane, install and enable the plugin. Visit the "forum thread":http://forum.textpattern.com/viewtopic.php?id=YYYYY for more info or to report on the success or otherwise of the plugin. + +To remove the plugin, simply delete it from the _Admin->Plugins_ pane. + +h2. Setting up + +# Obtain the "kindlegen program":http://www.amazon.com/gp/feature.html?ie=UTF8&docId=1000234621 that is compatible with your web host -- most likely the Linux version. While you're there you might as well grab the (huge!) Kindle Previewer too as it's very handy to test files made with this plugin. +# Upload kindlegen via your FTP program *as binary* to a location of your choosing on your web host; preferably outside document root so it can't be run by other people. Double check it is uploaded as binary -- some FTP software (e.g. FileZilla) is set to auto-negotiate the file type and often gets it wrong. If the plugin doesn't work, this is the most likely source of failure. +# Visit the _Content->E-books_ tab with a Publisher level account and hit the _Settings_ button. Configure the _Path to kindlegen executable_ to reflect the location of your uploaded kindlegen file. Set up any other relevant settings while you are here and save them. +# *After saving the settings* you can click the _Test kindlegen program_ link to check that the program is uploaded correctly and the plugin can find it. If everything's OK, you will be told so in a text box that appears below the link. If the kindlegen file produces errors or cannot be found, the error messages will be shown instead. + +h2. Writing content suitable for E-readers + +While the technology and tools are improving, there are some guidelines and things to be aware of when creating content in Textpattern that will translate well into a good e-reader experience: + +* Use headings to create chapters or logical breaks in your prose. You can create many articles if you wish -- perhaps one article per chapter -- and create a single file from them, or create it all in one article. +* Supply cover art. This must be a GIF or JPG image of dimensions 500 (w) x 600 (h) pixels. Assign the ID of the cover image uploaded to Textpattern in the _Article Image_ field of the first chapter. +* Create a stylesheet to lay out your table of contents or alter facets of your book. Formatting is often hit and miss because the e-readers use their own internal styles, but some things can be influenced with a stylesheet. Tinker with it to see what effects you can create. +* "Inline images":#smd_ebook_images cannot flow around text -- they always appear block style. +* Add author notes to a field in your first article -- such notes appear after the cover image and before the ToC. Copyright info and acknowledgements are useful here. See the setting _Get author notes from field_. + +h3. Formatting for Table of Contents (ToC) + +The concept of a ToC maps nicely in Textile / HTML to the @