Usage

Basic Usage

Once installed, Writer2ePub (W2E) is ready to use. After opening a Writer document, the word processor of OpenOffice (OO) or LibreOffice (LO), the following three icons will appear in the toolbar:

The three buttons perform the following actions.

1. 
   Convert the current document into an EPUB file. This operation starts only if the document has been saved. Otherwise, an error dialog will ask to save it before converting.
   If not disabled in the Preferences, the Metadata window will appear before the beginning of the conversion. You need to provide the title and the author of the ebook. All the other metadata are optional.
   The conversion might take from few seconds to several minutes, depending on the size and complexity of the document, the presence of images, links, etc.
2. 
   Open the Metadata window. You can provide or edit the metadata for the current ebook; title and author are required.
3. 
   Open the Preferences window. You can modify the parameters that alter the default behavior of W2E, as descripted in the relevant section of this manual.

Metadata Window

In this window you can provide the metadata of the ebook. Following the EPUB specification, all the metadata fields are optional, except for

• Title: the title of the ebook (no length limits);
• Author: the name of the principal author (no length limits). Right now W2E does not manage multiple-authors books, but you can input all the authors' names in this field; and
• Language: you can choose it from the drop-down menu. By default, W2E uses the OpenOffice (OO) / LibreOffice (LO) language.

Without these values W2E cannot proceed in generating the EPUB. The unique identifier of the ebook, required by the EPUB specification, is generated by W2E but cannot be modified from this window (v. 1.1.15).

The following fields are optional, but specifying them is a good practice:

• Editor: the name of the editor of the ebook. In many ereaders it is shown along with Title and Author;
• ISBN: the ISBN code for the book. (Note for the self-publishers: the ISBN code is a book identifier, and allows the ebook to be added to catalogs and libraries. Hence, you might want to consider asking a professional or a self-publishing service for obtaining an ISBN code for your ebook, as it is quite cheap nowadays.)
• Publication date: date of publication, not necessarily the same as the creation date for the file. You must use one of the following formats:
  • YYYY : year, expressed with four digits (e.g., 2012)
  • YYYY-MM : year and month, expressed with four and two digits each, separated by an hyphen (e.g., 2012-01)
  • YYYY-MM-DD : year, month, and day, expressed with four, two, and two digits, separated by hyphens (e.g. 2012-01-26)

In case of errors, the date will be displayed in red.

• Original Title: if you are converting a translated text, you can specify here the original title (in the original language). The Translator field will be added in a future release of W2E.
• Tag: you can insert your own tags for the ebook, for example the genre (horror, thriller, etc.). Usually these tags are used by programs like Calibre to sort and manage collections of books.
• Description: you can insert a description or abstract of the ebook. As for the Tag field, usually this field is managed by Calibre and friends.
• Cover: you can choose among three options:
  • First Image: the first image included in the document will be used as the ebook cover. The first image in the document will be displayed in the frame below. Warning: please note that sometimes the first image inserted in the Writer document is not the first to be displayed. Please use this option only if you are sure that the cover image is the first image inserted in the document.
  • Nothing: shall I explain it?
  • File...: a file dialog will be opened, allowing you to select a file to be used as the ebook cover. You should use JPEG, PNG, GIF or SVG images, not bigger than 600x800 pixels. The chosen image will be displayed in the frame below. If the image file is moved or deleted, a question mark will appear in the frame and the conversion will halt.
• Background color: in the three fields you can specify the color components (red, green, and blue) that form the background color that will surround the cover image. Since the cover image might not fill the entire screen of an ereader, this option lets you specify the background color to be used to fill the screen. Each value should be between 0 and 255, and the resulting color might be seen on the frame above. For example, (0,0,0) corresponds to black, (255,255,255) to white, (255,0,0) to red, (0,0,255) to blue, and so on.

The window features the following buttons:

• OK: Save all the metadata inside the .odt file, so that they will appear every time the Metadata window is opened.
• Cancel: Do not save the changes and stop the conversion (if the window was not manually opened)
• Help: Since version 1.1.15, it opens this manual. In previous releases, it opened the W2E author's blog.
• Donate: Gives you the opportunity to give a (substantial, please!) donation to the W2E author. Money will be used for running the blog and keeping W2E and the documentation online --- besides granting some modest gifts to the W2E author's wife, as a partial compensation for the time spent developing W2E ;) Overflowing money will be donated to the eBook Club Italia, a non-profit organization for the promotion of reading and ebooks in Italy (and beyond).

Finestra delle Preferenze

In this window you can specify some parameters that alter the behavior of W2E while generating EPUB files.

Usually you do not need to modify these values, and for the majority of the cases the default settings are fine.

Here is a description of the parameters:

• File Split: EPUB files must be split into small sections, so that even older ereader devices can assure quick page turns and chapter navigation. Each file split corresponds to a page turn while reading. Therefore, it is a good practice to split the text into separate files, one for each chapter, to avoid interruptions while reading.
  • Split Files Before Headings 1/2/3: these three options allow you to choose which heading(s) should be consider for splitting the document. By default, Heading 1 and Heading 2 are enabled. Sometimes you might want to disable the latter to avoid sub-chapter page turns, while you should never disable Heading 1, except for very short documents where you want a "continuous" reading experience.
  • Split Files every XXX Kb: if your document has very long chapters, you can use this option to limit each file size. EPUB specification requires the files to be less than 300 Kb in size, but a best practice demands for less than 200 Kb files. This is the default value set for W2E, but you can choose your own. If a book is not segmented into chapters, instead of using this option you should specify page breaks in your document, so that W2E will split your document in correspondence of the split you chose.

• Fonts: this section contains options (still to be refined!) for choosing dimension and type of fonts.
  • Base font height: usually the user of an ereader device can choose the base font height. Sometimes, however, a good choice for the font height cannot be found, especially if the set of font sizes is narrow. You can try adjusting the base font size using this option, by increasing or decreasing it by 10-20%, until the generated EPUB looks good on the ereader. If you are using W2E to generate an EPUB to be distributed to other readers, please leave this parameter to 100% to avoid compatibility issues with other ereader devices.
  • Font: do not use this option, it is not properly working. It will be fixed in a future release.
  • Embed font in the ePub file: this feature is currently disabled. It will be implemented in a future release.

• Advanced: these options are reserved for special needs.
  • Image quality: it will be implemented in a future release; it will allow to control the size and resolution of images in the EPUB.
  • Keep working files: disabled by default, this option keeps a directory containing all the EPUB files, so that advanced users can edit XHTML, CSS, and XML files directly.
  • Hide messagges: disabled by default, this option hides the messages that W2E usually prints. Useful when automating the production of several EPUB files.
  • Close document after conversion: disabled by default, this option closes the document after the conversion. Useful when automating the production of several EPUB files.

• Metadata: in this section you can control metadata preferences.
  • Meta extraction from file name: extact some metadata from the file name and use them in the specified fields. To identify the type and sequence, separated by a hyphen, you should use:
    • A = Author
    • T = Title
    • P = Publisher
    • Y = Year
      For example, if the file name is: "George Orwell - Animal Farm - 1945", by specifying: "A - T - Y - P", the file name will be interpreted as follows: "George Orwell" is the author (A), "Animal Farm" is the title (T), "1945" is the year (Y), the publisher (P) is ignored.
  • Show metadata window before creation: if enabled, W2E will open the Metadata window every time the document is being converted. By disabling it, the window will not be shown, unless some of the required metadata is missing.

• Insert W2E credits: enabled by deafult, adds a page at the end of the ebook stating that the EPUB file was created by W2E. If the EPUB file is for personal use, this option can be disabled. If the EPUB file is intended for distribution (non-profit or commercial), please let this option enabled, or give proper credit to W2E somewhere else in the ebook.

Text Formatting

To obtain the best results with W2E, you must follow some formatting rules while you compose your document. As mentioned before, W2E is not a format converter, hence it does not replicate the formatting you see on screen, but it adapts the text and sets the formatting rules so that the generated EPUB file is specification-compliant.

Thinking in EPUB

Before starting writing an ebook in EPUB format, you should abandon the concept of paginated book. Ebooks do not feature pages, only a continuous flow of text and images exists. You should think a book as a sequence of headings, paragraphs, images, etc. that appear according to the order the author chose. Since in an ebook there are not pages, absolute positioning of objects is impossible. When inserting an image, we can decide after which paragraph it should be displayed, and how much space --- relative to the width and height of the screen --- it should occupy in the final EPUB file.

Using Styles

One of the strengths of OO/LO is the excellent style management. You can assign to a portion of text a style that will identify the properties of that portion of text. W2E uses the styles to identify the different sections of a book and to convert it properly. The styles that are currently recognized are:

• Text body: the style of the main part of a book
• Heading 1: used for chapter titles. In the generated EPUB it will be rendered as centered, in bold face and with a slightly bigger font size.
• Heading 2:
• Heading 3:
• Heading 4-6:
• Title:
• Subtitle:
• Quotations:
• Caption:
• Marginalia:
• Footnote: