class Softcover::Builders::Epub
Public Instance Methods
# File lib/softcover/builders/epub.rb, line 145 def build!(options={}) @preview = options[:preview] Softcover::Builders::Html.new.build! if manifest.markdown? opts = options.merge({ source: :polytex, origin: :markdown }) self.manifest = Softcover::BookManifest.new(opts) end remove_html remove_images create_directories write_mimetype write_container_xml write_ibooks_xml copy_image_files write_html(options) write_contents(options) create_style_files(options) write_toc write_nav make_epub(options) move_epub end
# File lib/softcover/builders/epub.rb, line 603 def chapter_name(n) n == 0 ? language_labels["frontmatter"] : strip_html(chapters[n].menu_heading) end
Returns the HTML template for a chapter.
# File lib/softcover/builders/epub.rb, line 647 def chapter_template(title, content) %(<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>#{title}</title> <link rel="stylesheet" href="styles/pygments.css" type="text/css" /> <link rel="stylesheet" href="styles/softcover.css" type="text/css" /> <link rel="stylesheet" href="styles/epub.css" type="text/css" /> <link rel="stylesheet" href="styles/custom.css" type="text/css"/> <link rel="stylesheet" href="styles/custom_epub.css" type="text/css"/> <link rel="stylesheet" type="application/vnd.adobe-page-template+xml" href="styles/page-template.xpgt" /> </head> <body> #{content} </body> </html>) end
Returns the chapters to write.
# File lib/softcover/builders/epub.rb, line 221 def chapters preview? ? manifest.preview_chapters : manifest.chapters end
Removes the '#book' CSS id. For some reason, EPUB books hate the book ids in the stylesheet (i.e., such books fail to validate), so remove them.
# File lib/softcover/builders/epub.rb, line 443 def clean_book_id(filename) File.read(filename).gsub(/#book /, '') end
# File lib/softcover/builders/epub.rb, line 513 def container_xml %(<?xml version="1.0"?> <container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container"> <rootfiles> <rootfile full-path="OEBPS/content.opf" media-type="application/oebps-package+xml"/> </rootfiles> </container>) end
Returns the content configuration file.
# File lib/softcover/builders/epub.rb, line 532 def content_opf(options={}) man_ch = chapters.map do |chapter| %(<item id="#{chapter.slug}" href="#{xhtml(chapter.fragment_name)}" media-type="application/xhtml+xml"/>) end toc_ch = chapters.map do |chapter| %(<itemref idref="#{chapter.slug}"/>) end image_files = Dir['epub/OEBPS/images/**/*'].select { |f| File.file?(f) } images = image_files.map do |image| ext = File.extname(image).sub('.', '') # e.g., 'png' ext = 'jpeg' if ext == 'jpg' # Strip off the leading 'epub/OEBPS'. sep = File::SEPARATOR href = image.split(sep)[2..-1].join(sep) # Define an id based on the filename. # Prefix with 'img-' in case the filname starts with an # invalid character such as a number. label = File.basename(image).gsub('.', '-') id = "img-#{label}" %(<item id="#{id}" href="#{href}" media-type="image/#{ext}"/>) end manifest.html_title content_opf_template(manifest.html_title, manifest.copyright, manifest.author, manifest.uuid, cover_id(options), toc_ch, man_ch, images) end
Copies the image files from the HTML version of the document.
# File lib/softcover/builders/epub.rb, line 448 def copy_image_files # Copy over all images to guarantee the same directory structure. FileUtils.cp_r(File.join('html', 'images'), File.join('epub', 'OEBPS')) # Parse the full HTML file with Nokogiri to get images actually used. html = File.read(manifest.full_html_file) html_image_filenames = Nokogiri::HTML(html).css('img').map do |node| node.attributes['src'].value end # Form the corresponding EPUB image paths. used_image_filenames = html_image_filenames.map do |filename| "epub/OEBPS/#{filename}" end.to_set # Delete unused images. Dir.glob("epub/OEBPS/images/**/*").each do |image| next if File.directory?(image) rm image unless used_image_filenames.include?(image) end end
# File lib/softcover/builders/epub.rb, line 576 def cover_id(options) cover?(options) ? "img-#{cover_img.sub('.', '-')}" : nil end
# File lib/softcover/builders/epub.rb, line 560 def cover_page %(<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>Cover</title> </head> <body> <div id="cover"> <img width="573" height="800" src="images/#{cover_img}" alt="cover" /> </div> </body> </html> ) end
# File lib/softcover/builders/epub.rb, line 185 def create_directories mkdir('epub') mkdir(path('epub/OEBPS')) mkdir(path('epub/OEBPS/styles')) mkdir(path('epub/META-INF')) mkdir(images_dir) mkdir('ebooks') end
# File lib/softcover/builders/epub.rb, line 422 def create_style_files(options) html_styles = File.join('html', 'stylesheets') epub_styles = File.join('epub', 'OEBPS', 'styles') FileUtils.cp(File.join(html_styles, 'pygments.css'), epub_styles) File.write(File.join(epub_styles, 'softcover.css'), clean_book_id(path("#{html_styles}/softcover.css"))) # Copy over the EPUB-specific CSS. template_dir = Softcover::Utils.template_dir(options) epub_css = File.join(template_dir, epub_styles, 'epub.css') FileUtils.cp(epub_css, epub_styles) # Copy over custom CSS. File.write(File.join(epub_styles, 'custom.css'), clean_book_id(path("#{html_styles}/custom.css"))) end
Returns HTML for HTML source that includes math. As a side-effect, html_with_math
creates PNGs corresponding to any math in the given source. The technique involves using PhantomJS to hit the HTML source for each page containing math to create SVGs for every math element. Since ereader support for SVGs is spotty, they are then converted to PNGs using Inkscape. The filenames are SHAs of their contents, which arranges both for unique filenames and for automatic disk caching.
# File lib/softcover/builders/epub.rb, line 284 def html_with_math(chapter, images_dir, texmath_dir, pngs, options={}) content = File.read(File.join("html", "#{chapter.slug}.#{html_extension}")) pagejs = "#{File.dirname(__FILE__)}/utils/page.js" url = "file://#{Dir.pwd}/html/#{chapter.slug}.#{html_extension}" cmd = "#{phantomjs} #{pagejs} #{url}" silence { silence_stream(STDERR) { system cmd } } # Sometimes in tests the phantomjs_source.html file is missing. # It shouldn't ever happen, but it does no harm to skip it. return nil unless File.exist?('phantomjs_source.html') raw_source = File.read('phantomjs_source.html') source = strip_attributes(Nokogiri::HTML(raw_source)) rm 'phantomjs_source.html' # Remove the first body div, which is the hidden MathJax SVGs. if (mathjax_svgs = source.at_css('body div')) mathjax_svgs.remove else # There's not actually any math, so return nil. return nil end # Remove all the unneeded raw TeX displays. source.css('script').each(&:remove) # Remove all the MathJax preview spans. source.css('MathJax_Preview').each(&:remove) # Suck out all the SVGs svgs = source.css('div#book svg') frames = source.css('span.MathJax_SVG') svgs.zip(frames).each do |svg, frame| # Save the SVG file. svg['viewBox'] = svg['viewbox'] svg.remove_attribute('viewbox') # Workaround for bug in Inkscape 0.91 on MacOS X: # extract height/width from svg attributes and move them to style attr svg_height = svg['height'] # in ex svg_width = svg['width'] # in ex svg['style'] += ' height:'+svg_height+';' + ' width:'+svg_width+';' svg.remove_attribute('height') svg.remove_attribute('width') # /Workaround first_child = frame.children.first first_child.replace(svg) unless svg == first_child output = svg.to_xhtml svg_filename = File.join(texmath_dir, "#{digest(output)}.svg") svg_abspath = File.join("#{Dir.pwd}", svg_filename) File.write(svg_filename, output) # Convert to PNG named: png_filename = svg_filename.sub('.svg', '.png') png_abspath = svg_abspath.sub('.svg', '.png') pngs << png_filename # # Settings for texmath images in ePub / mobi ex2em_height_scaling = 0.51 # =1ex/1em for math png height ex2em_valign_scaling = 0.481482 # =1ex/1em for math png vertical-align ex2px_scale_factor = 20 # =1ex/1px scaling for SVG-->PNG conv. # These are used a three-step process below: Compute, Convert, Replace # STEP1: compute height and vertical-align in `ex` units svg_height_in_ex = Float(svg_height.gsub('ex','')) # MathJax sets SVG height in `ex` units but we want `em` units for PNG png_height = (svg_height_in_ex * ex2em_height_scaling).to_s + 'em' # Extract vertical-align css proprty for inline math equations: if svg.parent.parent.attr('class') == "inline_math" vertical_align = svg['style'].scan(/vertical-align: (.*?);/) vertical_align = vertical_align.flatten.first if vertical_align valign_in_ex = Float(vertical_align.gsub('ex','')) png_valign = (valign_in_ex * ex2em_valign_scaling).to_s + 'em' else png_valign = "0em" end else # No vertical align for displayed math png_valign = nil end # STEP2: Generate PNG from each SVG (unless PNG exists already). unless File.exist?(png_filename) unless options[:silent] || options[:quiet] puts "Creating #{png_filename}" end # Generate png from the MathJax_SVG using Inkscape # Use the -d option to get a sensible size: # Resolution for bitmaps and rasterized filters cmd = "#{inkscape} #{svg_abspath} -o #{png_abspath} -d 2" if options[:silent] silence { silence_stream(STDERR) { system cmd } } else puts cmd silence_stream(STDERR) { system cmd } end end rm svg_filename # STEP 3: Replace svg element with an equivalent png. png = Nokogiri::XML::Node.new('img', source) png['src'] = File.join('images', 'texmath', File.basename(png_filename)) png['alt'] = png_filename.sub('.png', '') png['style'] = 'height:' + png_height + ';' if png_valign png['style'] += ' vertical-align:' + png_valign + ';' end svg.replace(png) end # Make references relative. source.css('a.hyperref').each do |ref_node| ref_node['href'] = ref_node['href'].sub('.html', xhtml('_fragment.html')) end source.at_css('div#book').children.to_xhtml end
# File lib/softcover/builders/epub.rb, line 522 def ibooks_xml %(<?xml version="1.0" encoding="UTF-8"?> <display_options> <platform name="*"> <option name="specified-fonts">true</option> </platform> </display_options>) end
Returns the Inkscape executable (if available).
# File lib/softcover/builders/epub.rb, line 398 def inkscape @inkscape ||= executable(dependency_filename(:inkscape)) end
Make the EPUB, which is basically just a zipped HTML file.
# File lib/softcover/builders/epub.rb, line 469 def make_epub(options={}) filename = manifest.filename zfname = filename + '.zip' base_file = "#{zip} -X0 #{zfname} mimetype" fullzip = "#{zip} -rDXg9" meta_info = "#{fullzip} #{zfname} META-INF -x \*.DS_Store -x mimetype" main_info = "#{fullzip} #{zfname} OEBPS -x \*.DS_Store \*.gitkeep" rename = "mv #{zfname} #{filename}.epub" commands = [base_file, meta_info, main_info, rename] command = commands.join(' && ') Dir.chdir('epub') do if Softcover.test? || options[:quiet] || options[:silent] silence { system(command) } else system(command) end end end
Returns true if a string appears to have LaTeX math. We detect math via opening math commands: (, [, and begin{equation} This gives a false positive when math is included in verbatim environments and nowhere else, but it does little harm (requiring only an unnecessary call to page.js).
# File lib/softcover/builders/epub.rb, line 418 def math?(string) !!string.match(/(?:\\\(|\\\[|\\begin{equation})/) end
Move the completed EPUB book to the `ebooks` directory. Note that we handle the case of a preview book as well.
# File lib/softcover/builders/epub.rb, line 494 def move_epub origin = manifest.filename target = preview? ? origin + '-preview' : origin FileUtils.mv(File.join('epub', "#{origin}.epub"), File.join('ebooks', "#{target}.epub")) end
Returns the PhantomJS executable (if available).
# File lib/softcover/builders/epub.rb, line 393 def phantomjs @phantomjs ||= executable(dependency_filename(:phantomjs)) end
Returns true if generating a book preview.
# File lib/softcover/builders/epub.rb, line 169 def preview? !!@preview end
Removes HTML. All the HTML is generated, so this clears out any unused files.
# File lib/softcover/builders/epub.rb, line 175 def remove_html FileUtils.rm(Dir.glob(path('epub/OEBPS/*.html'))) FileUtils.rm(Dir.glob(path('epub/OEBPS/*.xhtml'))) end
Removes images in case they are stale.
# File lib/softcover/builders/epub.rb, line 181 def remove_images rm_r images_dir end
Returns a list of the section names and CSS ids. Form is [['Beginning', 'sec-beginning'], ['Next', 'sec-next']]
# File lib/softcover/builders/epub.rb, line 635 def section_names_and_ids(article) # Grab section names and ids from the article. filename = File.join('epub', 'OEBPS', xhtml(article.fragment_name)) doc = Nokogiri::HTML(File.read(filename)) names = doc.css('div.section>h2').map do |s| s.children.children.last.content end ids = doc.css('div.section').map { |s| s.attributes['id'].value } names.zip(ids) end
Strip attributes that are invalid in EPUB documents.
# File lib/softcover/builders/epub.rb, line 403 def strip_attributes(doc) attrs = %w[data-tralics-id data-label data-number data-chapter role aria-readonly target] doc.tap do attrs.each do |attr| doc.xpath("//@#{attr}").remove end end end
Strip HTML elements from the given text.
# File lib/softcover/builders/epub.rb, line 608 def strip_html(text) Nokogiri::HTML.fragment(text).content end
Returns the Table of Contents for the spine.
# File lib/softcover/builders/epub.rb, line 581 def toc_ncx chapter_nav = [] if article? article = chapters.first section_names_and_ids(article).each_with_index do |(name, id), n| chapter_nav << %(<navPoint id="#{id}" playOrder="#{n+1}">) chapter_nav << %( <navLabel><text>#{escape(name)}</text></navLabel>) chapter_nav << %( <content src="#{xhtml(article.fragment_name)}##{id}"/>) chapter_nav << %(</navPoint>) end else chapters.each_with_index do |chapter, n| chapter_nav << %(<navPoint id="#{chapter.slug}" playOrder="#{n+1}">) chapter_nav << %( <navLabel><text>#{chapter_name(n)}</text></navLabel>) chapter_nav << %( <content src="#{xhtml(chapter.fragment_name)}"/>) chapter_nav << %(</navPoint>) end end toc_ncx_template(manifest.html_title, manifest.uuid, chapter_nav) end
Writes the container XML file. This is required by the EPUB standard.
# File lib/softcover/builders/epub.rb, line 202 def write_container_xml File.write(path('epub/META-INF/container.xml'), container_xml) end
Writes the content.opf file. This is required by the EPUB standard.
# File lib/softcover/builders/epub.rb, line 216 def write_contents(options={}) File.write(path('epub/OEBPS/content.opf'), content_opf(options)) end
Writes the HTML for the EPUB. Included is a math detector that processes the page with MathJax (via page.js) so that math can be included in EPUB (and thence MOBI).
# File lib/softcover/builders/epub.rb, line 228 def write_html(options={}) texmath_dir = File.join(images_dir, 'texmath') mkdir images_dir mkdir texmath_dir if cover?(options) File.write(path("epub/OEBPS/#{cover_filename}"), cover_page) end pngs = [] chapters.each_with_index do |chapter, i| target_filename = path("epub/OEBPS/#{xhtml(chapter.fragment_name)}") File.open(target_filename, 'w') do |f| content = File.read(path("html/#{chapter.fragment_name}")) doc = strip_attributes(Nokogiri::HTML(content)) # Use xhtml in references. doc.css('a.hyperref').each do |ref_node| ref_node['href'] = ref_node['href'].sub('.html', xhtml('.html')) end body = doc.at_css('body') if body.nil? $stderr.puts "\nError: Document not built due to empty chapter" $stderr.puts "Chapters must include a title using the Markdown" $stderr.puts " # This is a chapter" $stderr.puts "or the LaTeX" $stderr.puts " \\chapter{This is a chapter}" exit(1) end inner_html = body.children.to_xhtml if math?(inner_html) html = html_with_math(chapter, images_dir, texmath_dir, pngs, options) html ||= inner_html # handle case of spurious math detection else html = inner_html end f.write(chapter_template("Chapter #{i}", html)) end end # Clean up unused PNGs. png_files = Dir[path("#{texmath_dir}/*.png")] (png_files - pngs).each do |f| if File.exist?(f) puts "Removing unused PNG #{f}" unless options[:silent] FileUtils.rm(f) end end end
Writes iBooks-specific XML. This allows proper display of monospace fonts in code samples, among other things.
# File lib/softcover/builders/epub.rb, line 209 def write_ibooks_xml xml_filename = 'com.apple.ibooks.display-options.xml' File.write(path("epub/META-INF/#{xml_filename}"), ibooks_xml) end
Writes the mimetype file. This is required by the EPUB standard.
# File lib/softcover/builders/epub.rb, line 196 def write_mimetype File.write(path('epub/mimetype'), 'application/epub+zip') end
Writes the Table of Contents. This is required by the EPUB standard.
# File lib/softcover/builders/epub.rb, line 503 def write_toc File.write('epub/OEBPS/toc.ncx', toc_ncx) end
# File lib/softcover/builders/epub.rb, line 488 def zip @zip ||= executable(dependency_filename(:zip)) end