Some text(1)
-``` - -##### Footnote - -``` - -``` - -#### CSS - -``` - .footnotes { - margin: 3em 0 0 5%; -} -.footnote { - text-indent: 0; - font-size: 0.875em; - line-height: 1.7142857143; -} -.inline-iBooks { - display: inline; -} -.call { - color: inherit; - -webkit-text-fill-color: inherit; - text-decoration: none !important; - border: none !important; - font-weight: normal; -} -.callback { - font-family: Symbol, Arial, sans-serif; - font-weight: bold; - text-decoration: none !important; - border: none !important; -} -``` - -To clarify: - -- we’re not using a `` for the footnote call as we need a target “tappable” enough on RMSDK-powered devices/apps (eInk readers for instance), hence the number between `(` and `)` to make it bigger. -- we need to link the call and the footnote (using `id`, `href` and the callback); -- because the footnote is not in a `aside` with the `epub:type` inflection, **iBooks will display this footnote** at the end of the XHTML document—you may want to add a horizontal rule before, as in print books. - -On the one hand, **if you’re publishing in the iBookStore only, changing the markup is your call.** You’d probably be better off with Ulysses’ default output. - -On the other hand, **if you want to publish anywhere else, you’ve got no choice.** Footnotes’ UX will be abysmal as they won’t work properly. Then some readers will say that you don’t know shit because you can’t hyperlink. Finally you’ll get a bad rap and it’s game over. - -### Converting to Kindle - -Use [Kindle Previewer](http://www.amazon.com/gp/feature.html?docId=1000765261). Seriously. Your Kindle readers will enjoy a better UX than with a Kindle Mobi generated using some third-party software—and it will be easier to maintain if you edit your epub files manually. - -If you’re running El Capitan, please also [apply this patch from Amazon.](https://s3.amazonaws.com/kindlepreviewer/Kindle+Previewer+Patch.zip) - -### Editing Soma - -Oh OK. Yeah, look, I didn’t document it very well… ¯\_(ツ)_/¯ - -But documenting a CSS for ePub is a really tough job—basically, comments everywhere leading to bloat, BLOAT, **BLOAT!** So let’s say that if something is surprising to you, don’t change it. - -However, I may give some pieces of advice for some really important stuff. - -- `-webkit-text-fill-color` is allowing the override of iBooks’ `a` default color. Now, iBooks got 4 themes (white, sepia, gray, black) and the value of the default color is modified dynamically based on the theme currently in use—in order to meet WCAG 2.0’s contrast ratio. In other words, don’t override and stick to default if you want to use color for links. As far as I can tell, there is no color meeting this WCAG requirement for all 4 themes. -- **Do not ever** declare black or shades of gray using `color` for text: some apps won’t invert this value when the user enables night mode and, as a result, they’ll get dark text on a dark background, making the text unreadable. If you really need black, use `color: inherit`. -- **Do not ever** declare `font-family` for `p` or `li` and other critical bodycopy elements as it will disable the typeface setting for users in a shitload of apps and devices. Let the cascade do its job, making those elements inherit from `body`. -- **Do not ever** declare `font-size` in `px` as it will disable the font size setting in RMSDK. Moreover, Kindle eInk devices don’t map `1em` and `100%` to `16px` but a multiple of `16px` depending on display resolution (e.g. `32px`, `64px` and so on and so forth). -- Don’t rely on the `html` selector. Please note RS usually declare `text-rendering: optimizeLegibility` when it doesn’t have issues (rendering or performance) so do not impose it on users—especially as there are wild bugs out there. -- Don’t rely on `text-transform` and `font-variant`, pseudo-classes and -elements for “critical styling”, e.g. headings, strong emphasis, list style type, thematic break (`hr`), &c. This is not supported in RMSDK. -- If you have snippets of code in your eBook, you’d better embed a monospace font in your ePub file. Some devices/apps don’t have a default one and will render code as serif or sans-serif. -- Be insanely cautious with `em` values for margins and paddings, especially left and right; if the user increases font-size, margins will increase accordingly. As a result, you get bigger text in a smaller container. This is the reason why I am using values in `%` (computed based on `width` of container). -- Styling of HTML5 elements (e.g. `aside`, `figure`, `section`, &c.) relies on the mini reset. Don’t ever get rid of this reset, please, because ePub2-only RS are still popular worldwide. -- If you change the modular scale (i.e. `font-size`), all line-heights and margins have to be recalculated if you want to keep vertical rhythm. -- Don’t use decimal values in `@media amzn-mobi{}`, KindleGen converter will round them quite harshly. **Please also note Mobi7 supports ± HTML 3.2.** -- Cover img styling in ePub is crap. **Design your cover with a 16:9 aspect ratio and you should be safe.** 16:10 or 4:3 and you’re screwed–unless you modify `img.cover` styles, that is. -- Whatever you do, don't leave the proprietary Amazon media queries (`amzn-kf8` + `amzn-mobi`) empty: **it will crash RMSDK.** CSS comments won’t fix this issue. - -### How do you manage your stylesheets? - -I’m basically using [LESS](http://lesscss.org) so that I can automatically compute vertical rhythm in `em` based on body’s `font-size`, `line-height` and a predefined modular scale. - -This in-house tool is currently being extended into a CSS framework for eBooks. More about that soon. - -For the record, the backbone of Soma’s styling was generated using v.0.66.6 of this framework. - -### Is Soma offerring some sort of Universal Support? - -Alright, you want to know if this stylesheet is likely to save your arse absolutely everywhere? - -Not. Even. Close. - -I can’t guarantee Soma is bulletproof since a lot of ePub apps don’t even fully implement ePub2 specs–I’m looking at you, Android apps… Die, Die, DIE! - -Listen, some apps don’t even support the `hr` tag because their developers don’t give a damn about structure and semantics. Others don’t even support CSS and I’m not kidding. - -So if some readers complain, tell them to use another app, a better one. And if you want to publicly shame bad apps, rest assured I won’t stand in your way–Yeah, that guy far away, cheering you on, that’s me. - -### Issues & feature requests - -**If you’ve got issues, file them.** To the extent possible (see previous question), I’ll do my best to fix them. - -**If you’ve got feature requests, fork Soma and make it happen.** Soma is covering all stuff output by Ulysses and I won’t add features for editing afterwards. - -Disclaimer: got an awful amount of work to deal with like, say, making eBooks to pay my rent + developing the “CSS framework for eBooks” that should have been launched like one year ago. In other words, my spare time is scarce. - -**Nota Bene: all disrespectful messages are belong to “is:issue is:closed”.** - -### Useful links for eBook Production - -eBook Production is a little bit different than web development. So here are some links that could prove useful… - -- [MobileRead Forums](http://www.mobileread.com/forums/) -- [Twitter’s #eprdctn](https://twitter.com/hashtag/eprdctn) -- [ePub Zone](http://epubzone.org) -- [my blog](http://jiminy.chapalpanoz.com) if you speak French - -### Will you push Soma to Ulysses’ Style Exchange? - -Yeah, probably. But only when I’m sure everything is OK and there are no critical issues with it. - -### Are companion themes (e.g. PDF, HTML, &c.) planned? - -Nope. For lack of time and courage, I’m not planning to do that. But again, this is just a fork away…. - -### How to contact you? - -OK, look, I’m a freelance so I must deal with so many things in so little time… Having more stuff to deal with would probably kill me. - -Here are 3 simple rules to follow: - -- if you have problems using or editing Soma, use Github issues; -- if you want to say hello—or maybe thank me?—, use [Twitter](https://twitter.com/jiminypan); -- **only if** you want to talk business, use the contact form on my website. - -Thank you in advance. +See [Wiki](https://github.com/JayPanoz/Soma/wiki) \ No newline at end of file