Revision as of 15:06, 22 August 2011

Overview

EPUB is an open standard for electronic publications. It declares set of features that reading system must implement to render all documents and describes structure and contents of electronic publication.

EPUB 2.0.1

Current version of EPUB standard is 2.0.1 (work in progress on EPUB3). It consist of three specifications:

Open publication structure (OPS)
Open packaging format (OPF)
Open container format (OCF)

You can find more details at the official EPUB website(http://idpf.org/epub/201). In brief, OPS defines in what way the content of publication is stored(HTML/XHTML and CSS) and what file types reading system should always support(so called "Core media types"); OPF defines what files are obligatory and describes their contents.

EPUB 3

EPUB 3 standard is the newest version of EPUB specification and currently is in the state of IDPF Proposed Specification. This new generation standard for electronic publications supports such things as media content(called Media Overlays), embedding MathML into documents, using JavaScript and HTML5 to create really nice-looking electronic publications. And Abiword is one of the first software that allow creating such documents (of course, they won`t contain media overlays, but who knows, maybe in the nearest future abiword will allow users to embed video and audio in the documents).

Using HTML exporter to create another plugin on top of it

In this section I`ll describe how it`s possible to create custom plugin based on HTML exporter without no changes to HTML exporter itself. To describe the process I`ll use references to existing code - EPUB2 export code.

Creating OPS documents

To create OPS part of EPUB 2.0.1 document(which is HTML/XHTML) we`ll use HTML exporter. It will generate all needed files in some temporary location and we`ll use it to create package. Everything we need is to tell HTML plugin where to place files. Let`s see at IE_Exp_EPUB::_writeDocument() to understand process of exporting in general:

   UT_Error errOptions = doOptions();

   if (errOptions == UT_SAVE_CANCELLED) //see Bug 10840
   {
       return UT_SAVE_CANCELLED;
   }
   else if (errOptions != UT_OK) {
       return UT_ERROR;
   }

   m_root = gsf_outfile_zip_new(getFp(), NULL);

   if (m_root == NULL)
   {
       UT_DEBUGMSG(("ZIP output is null\n"));
       return UT_ERROR;
   }

   m_oebps = gsf_outfile_new_child(m_root, "OEBPS", TRUE);
   if (m_oebps == NULL)
   {
       UT_DEBUGMSG(("Can`t create oebps output object\n"));
       return UT_ERROR;
   }

   // mimetype must a first file in archive
   GsfOutput *mimetype = gsf_outfile_new_child_full(m_root, "mimetype", FALSE,
           "compression-level", 0, NULL);
   gsf_output_write(mimetype, strlen(EPUB_MIMETYPE),
           (const guint8*) EPUB_MIMETYPE);
   gsf_output_close(mimetype);

   // We need to create temporary directory to which
   // HTML plugin will export our document
   m_baseTempDir = UT_go_filename_to_uri(g_get_tmp_dir());
   m_baseTempDir += G_DIR_SEPARATOR_S;

   // To generate unique directory name we`ll use document UUID
   m_baseTempDir += getDoc()->getDocUUIDString();
   // We should delete any previous temporary data for this document to prevent
   // odd files appearing in the container
   UT_go_file_remove(m_baseTempDir.utf8_str(), NULL);
   UT_go_directory_create(m_baseTempDir.utf8_str(), 0644, NULL);

   if (writeContainer() != UT_OK)
   {
       UT_DEBUGMSG(("Failed to write container\n"));
       return UT_ERROR;
   }
   if (writeStructure() != UT_OK)
   {
       UT_DEBUGMSG(("Failed to write document structure\n"));
       return UT_ERROR;
   }
   if (writeNavigation() != UT_OK)
   {
       UT_DEBUGMSG(("Failed to write navigation\n"));
       return UT_ERROR;
   }
   if (package() != UT_OK)
   {
       UT_DEBUGMSG(("Failed to package document\n"));
       return UT_ERROR;
   }

   gsf_output_close(m_oebps);
   gsf_output_close(GSF_OUTPUT(m_root));
   
   // After doing all job we should delete temporary files
   UT_go_file_remove(m_baseTempDir.utf8_str(), NULL);
   return UT_OK;

Let`s look at the IE_Exp_EPUB::writeStructure() method. It checks what version of EPUB is used an if it`s EPUB2 version, IE_Exp_EPUB::EPUB2_writeStructure() is called.

Temporary directories are created with following code:

   m_oebpsDir = m_baseTempDir + G_DIR_SEPARATOR_S;
   m_oebpsDir += "OEBPS";

   UT_go_directory_create(m_oebpsDir.utf8_str(), 0644, NULL);

   UT_UTF8String indexPath = m_oebpsDir + G_DIR_SEPARATOR_S;
   indexPath += "index.xhtml";

Next step is export process itself:

   // Exporting document to XHTML using HTML export plugin 
   char *szIndexPath = (char*) g_malloc(strlen(indexPath.utf8_str()) + 1);
   strcpy(szIndexPath, indexPath.utf8_str());
   m_pie = new IE_Exp_HTML(getDoc());
   m_pie->suppressDialog(true);
   m_pie->setProps(
           "embed-css:no;html4:no;use-awml:no;declare-xml:yes;mathml-render-png:yes;split-document:yes;add-identifiers:yes;");
   m_pie->writeFile(szIndexPath);
   g_free(szIndexPath);

All settings that are needed for export are passed to HTML exporter using IE_Exp_HTML::setPros call. You can find descriptions of all available options in IE_Exp_HTML.cpp source file.

EPUB plugin

From AbiWiki

Revision as of 15:06, 22 August 2011

Contents

Overview

EPUB 2.0.1

EPUB 3

Using HTML exporter to create another plugin on top of it

Creating OPS documents

Packaging

Views

Personal tools

Navigation

Search

Toolbox