README.adoc in asciidoctor-epub3-1.5.0.alpha.8 vs README.adoc in asciidoctor-epub3-1.5.0.alpha.9

- old
+ new

@@ -1,8 +1,8 @@ = {project-name}: A _native_ EPUB3 converter for AsciiDoc Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]> -v1.5.0.alpha.8, 2018-02-20 +v1.5.0.alpha.9, 2019-04-04 // Settings: :experimental: :idprefix: :idseparator: - :imagesdir: data/samples/images @@ -402,11 +402,11 @@ |Effectively ignored. The master document is assumed to be a book and each chapter an article. |publication-type |Used to control the inclusion of special content in the generated HTML. -If set to a value other than book, the byline information (author and avatar) is included below the chapter header. +If set to a value other than book, the byline information (author and avatar) is included below the chapter header and a typographic end mark is added at the end of the last paragraph. Suggested values include: book (default), anthology, magazine, journal, article. |=== When using the EPUB3 converter, the `ebook-format` attribute resolves to the name of the e-book format being generated (epub3 or kf8) and the corresponding attribute `ebook-format-<name>` is defined, where `<name>` is `epub3` or `kf8`. You can use these attributes in a preprocessor directive if you only want to show certain content to readers using a particular device. @@ -775,37 +775,47 @@ * won't style footers without an explicit class * `-webkit-hyphens: auto` causes Kindle for Mac (and perhaps others) to crash * `text-rendering: optimizeLegibility` causes file to be rejected by KFP (and causes the text to disappear in some previewers) * Kindle Direct Publishing (KDP) strips out select font-related CSS rules (e.g., `font-family`) under certain conditions (for reasons that have proved nearly impossible to reverse engineer); the known workaround is to add a layer of indirection by using `@import` to hide the CSS files from the script +=== Kindle Direct Publishing + +If you want to publish your book to the Amazon Kindle store, and have your styles and fonts preserved, you must use https://kdp.amazon.com[Kindle Direct Publishing]. +No other method of publishing to the Amazon Kindle store will leave your book intact. + +This workflow also allows you to preview the book the way your readers will see it. +So it's a good way to acceptance test your custom styles to discover which ones are honored and which ones are ignored. + +==== Look Inside + +The Amazon Kindle store offers a “Look Inside” feature for reader. +This so-called feature aims to gives readers a glimpse at the contents of the book. +Sadly, it does no such thing. +Instead, it shows pages from the legacy MOBI document that kindlegen adds to your e-book file, not the higher fidelity KF8 document. +This means the preview won't look at all like what the Kindle reader or application will actually show. +Custom fonts, font-based icons, and most styles will be missing. + +This situation is unfortunate for authors. +What we recommend is to complain loudly to Amazon that they are hurting your sales by displaying a crippled version of your product. +Tell them that under no circumstances should they show an altered version of your product. +Another option is to contact Amazon to opt-out of this program. + === Send to Kindle WARNING: Don't use it! -{uri-send-to-kindle}[“Send to Kindle”] is a tempting choice for transferring MOBI files to a Kindle device. +{uri-send-to-kindle}[Send to Kindle] is a tempting choice for transferring MOBI files to a Kindle device. However, it's utterly broken. If you use this tool, don't be surprised if you see missing font-based icons, default fonts, and other font and style errors in your manuscript. It's known to strip out all the font files and break the encoding of the document. We *strongly* recommend you transfer the file to your device using either a USB cable or a sync service such as Dropbox. Once transferred, Whispersync will detect the new file (usually looking in the Books folder) and add it to the “On Device” library. It's important to note that “Send to Kindle” is not reflective of the experience readers will have when shopping in the Kindle store. If you use Kindle Direct Publishing (KDP) to publish your book, the integrity of your book will be preserved (to the degree that Amazon allows). -=== Look Inside - -The Amazon Kindle store has a “Look Inside” feature, which aims to gives readers a glimpse at the contents of the book. -Sadly, it does no such thing. -Instead, it shows pages from the legacy MOBI document that kindlegen adds to your e-book file, not the higher fidelity KF8 document. -Therefore, the preview won't look at all like what the Kindle reader or application will actually show. -Custom fonts, font-based icons, and most styles will be missing. - -This situation is unfortunate for authors. -What I recommend is to complain loudly to Amazon that they are hurting your sales by displaying a crippled version of your product. -Another option is to contact Amazon to opt-out of this so-called feature. - //// head-stop (default '.') stack-head role (run-in is default) signature role (sets hardbreaks option) @@ -951,10 +961,10 @@ {project-name} was written by https://github.com/mojavelinux[Dan Allen] and https://github.com/graphitefriction[Sarah White] of OpenDevise on behalf of the Asciidoctor Project. == Copyright -Copyright (C) 2014-2018 OpenDevise Inc. and the Asciidoctor Project. +Copyright (C) 2014-2019 OpenDevise Inc. and the Asciidoctor Project. Free use of this software is granted under the terms of the MIT License. For the full text of the license, see the <<LICENSE#,LICENSE>> file. Refer to the <<NOTICE#,NOTICE>> file for information about third-party Open Source software in use.