An EPUB ebook is simply a collection of files each with different functionality stored together using the common zip format. These files include your words, images, Table of Contents, stylesheets, fonts and details about your book like author or title. EPUB’s standard format means your book can be read on many e-readers or converted easily to other e-readers not using EPUB.
-Your EPUB stores your words and text in the book using the an XML form called XHTML of the HTML format (Hyper Text Markup Language) – the same code used by web pages to display text and images. This just means that the files contain your text along with markup codes and tags (like <h1> or <p>) which tell e-readers how to format and display the text – some words could be bold or italic, others could be a paragraph or a heading, etc.
+Your EPUB stores your words and text in the book using an XML form called XHTML of the HTML format (Hyper Text Markup Language) – the same code used by web pages to display text and images. This just means that the files contain your text along with markup codes and tags (like <h1> or <p>) which tell e-readers how to format and display the text – some words could be bold or italic, others could be a paragraph or a heading, etc.
In addition to XHTML tags to control or style the layout, EPUB books typically make use of stylesheets to help organise the use of styles used by the XHTML files. A stylesheet is another file in the EPUB that contains a list of XHTML tags, classes, and selectors along with instructions on how to display any text using that matches the tag, class or selector, e.g. <h1> (heading level 1) should be larger and centered. This allows you to separate the content of your book from its layout and allows you to easily adjust the look of the EPUB.
@@ -52,7 +52,7 @@If you really want to dig into the details of the official EPUB standard on which Sigil is built you can read the original technical specifications:
Some rarely needed settings in Sigil are controlled by "Environment Variables". An environment variable is a user-definable value that can affect the way running processes will behave on a computer. See https://en.wikipedia.org/wiki/Environment_variable> for more information on setting and using environment variables on your computer.
+ +Sigil Uses the following Environment Varabiles:
+ +SIGIL_DISABLE_VERSION_META Set this environment variable to any value to prevent Sigil from adding the metadata that identifies Sigil as the producer of this epub.
SIGIL_DISABLE_NFC_NORMALIZATION Set this environment variable to disable conversion of user content to use Unicode Normalization Form C. Please note, disabling use of NFC form means that many e-readers will be unable to properly search your epub for texts that include accents.
SIGIL_FOCUS_HIGHLIGHT_COLOR This allows the user to control the color used when Focus Highlight Rectangles are enabled. Its value should be a standard css color value beginning with '#' followed by 6 hex digits.
SIGIL_ALLOW_CODEVIEW_DROP If this value is set, drag and drop editing inside CodeView is enabled. Be warned that on some platforms, using drag and drop to edit inside CodeView can be unstable causing Sigil to crash. No support will be provided to people who decide to enable drag and drop as fixing these issues are outside our control (internal to Qt6).
SIGIL_DEBUG_LOGFILE Setting this to the full path (including file name and extension) to a user-writeable location will cause Sigil to output any additional debug information to that log file. Unset this environment after debugging is important as this file will continue to build up output eventually filling up user disk space and slowing down Sigil.
SIGIL_USE_FREETYPE_FONTENGINE This environment variable is Windows Only. Setting this will tell Sigil to use the FreeType Font Engine. This is useful on Windows for users who make heavy use of // Woff/woff2 fonts in their epub. Current Qt version of the Windows Font Engine does not support these font types.
SIGIL_PREVIEW_TIMEOUT Setting this to a number (of milliseconds) will determine the length of time after user input stops while editing in CodeView until Preview is updated. The minimum delay is 1000 milliseconds and the maximum delay can be set up to 10000 milliseconds. Therre is typically no reason to set this unless you are editing huge xhtml files that take too long for Preview to update.
SIGIL_DRAG_DISTANCE_TWEAK This environment varaible is Windows Only. You can set this to change the distance in pixels needed to move something before drag and drop is detected by the system. Its valid values range from -20 to 20 pixels.
SIGIL_DISABLE_CURSOR_BLINK Many people have senstivities to flashing and blinking. If you are one of those people, you can set this environment variable to disable the constant cursor blinking used in CodeView and in many input dialogs.
SKIP_SIGIL_UPDATE_CHECK Setting this tells Sigil *NOT* to use the network to query for the latest version of Sigil. This may be important for Linux distributions who build and release their own versions of Sigil and would prefer you use their builds.
SIGIL_PREFS_DIR This environment Variable is primarily Linux Only. Setting this tells Sigil where your Sigil Preferences Location folder is located.
SIGIL_EXTRA_ROOT This environment Variable is primarily Linux Only. Setting this tells Sigil where your share/sigil folder is located.
SIGIL_DICTIONARIES This environment Variable is primarily Linux Only. Setting this tells Sigil where to locate the hunspell dictionaries installed on your system.
In addition to the Sigil specific environment variables, you can also use Qt6 specific environment varaibles including QT_QPA_PLATFORM and QTWEBENGINE_CHROMIUM_FLAGS. You will need a search engine to find recent Qt6 information on how these environment variables can be used to control Sigil as these change with newer releases.
+Many users of Sigil develop their own versions of starting xhtml, and css files that they would much prefere using over what Sigil defaults to. To address these concerns, Sigil has added the ability to load user defined starting xhtml, and css files. To create these "templates" simply edit any blank xhtml or css page to your liking and then save it to your Sigil Preferences Location with one of these specific filenames. When you are a Blank HTML or Blank CSS files using Sigil's BookBrowser, sigil will use your templates instead. To prevent their use simply rename or delete them.
+ +user-template2.xhtml Epub2 specific xhtml file.
user-template3.xhtml Epub3 specific xhtml file.
user-template2.css Epub2 specific css file.
user-template3.css Epub3 specific css file.
In a similar manner, many people prefer specific layouts for their cover images xhtml pages. To facilitate thise Sigil allows the user to create a cover-template2.xhtml or cover-template3.xhtml file and store it in Sigil's Preferences Location.
+Sigil allows these cover templates to use a set of PLACEHOLDERS that Sigil will automatically fill in values for when creating the cover:
+Here is an example of a cover-template3.xhtml that uses SVG and makes use of these PLACEHOLDERS:
+ +
+ <?xml version="1.0" encoding="UTF-8" standalone="no" ?>
+ <!DOCTYPE html>
+
+ <html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" lang="en" xml:lang="en">
+ <head>
+ <title>Cover</title>
+ </head>
+
+ <body>
+ <div style="height: 100vh; text-align: center; padding: 0pt; margin: 0pt;">
+ <svg xmlns="http://www.w3.org/2000/svg" height="100%" preserveAspectRatio="xMidYMid meet" version="1.1" viewBox="0 0 SGC_IMAGE_WIDTH SGC_IMAGE_HEIGHT" width="100%" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <image width="SGC_IMAGE_WIDTH" height="SGC_IMAGE_HEIGHT" xlink:href="SGC_IMAGE_FILENAME\"/>
+ </svg>
+ </div>
+ </body>
+ </html>
+Many e-readers employ the Adobe Digital Editions Software Development Kit as their underlying rendering and display engine. Many other employ Web Browser-based display engines. All of these e-readers have the capability to include Adobe PDF documents inside their epub.
+ +Unfortunately many older e-readers do not support PDF. The epub3 specification does allow for this case by providing "fallback" resources (or sometimes OPF bindings) to handle the cases when the e-reader does not have the ability to display a resource type.
+ +More unfortunately, according to the developers of Epubcheck, few e-readers actually support the use of fallback resources or OPF bindings. This leaves epub3 developers in a quandary. Luckily the "object" tag can be used to create an xhtml/html based fallback allowing the spine to be comprised of purely xhtml files.
+ +Here is an example of how to use the "object" tag in an xhtml file to display an embedded PDF or an xhtml-based alternative as a fallback that works on many older e-readers for that can not handle the PDF format.
+ + +
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html>
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+ <title>PDF Test Page</title>
+</head>
+
+<body>
+
+ <object type="application/pdf" data="../Misc/demo.pdf" width="500" height="500">
+
+ <!-- The child of the object tag holds the xhtml fallback -->
+ <h3 class="sigil_not_in_toc">PDF Fallback text</h3>
+
+ <p>This text is being displayed, if the reader or reading device doesn't support embedded .pdf files.</p>
+
+ </object>
+
+</body>
+</html>
+In addition direct links to the PDF are possible and loading the links into a iframe is alo possible but these approaches do not allow for fallbacks for older e-readers and should be avoided if at all possible.
+ + \ No newline at end of file diff --git a/src/OEBPS/Text/book_browser.xhtml b/src/OEBPS/Text/book_browser.xhtml index 995b488..b52b3a9 100644 --- a/src/OEBPS/Text/book_browser.xhtml +++ b/src/OEBPS/Text/book_browser.xhtml @@ -65,7 +65,7 @@Video: The MP4, OGG, WEBM, M4V and any other embedded video files that might be in the book.
Misc: Other files that are not typically used by EPUB readers but can be stored with the book. This includes things like javascript (JS) files under EPUB3.
Misc: Other files that are typically used by EPUB readers and are stored with the book. This includes things like javascript (JS) files, SMIL files, and other pure XML files.
No virtual folder: The NCX (.ncx) and OPF (.opf) files are not placed in a virtual folder. The NCX contains a an EPUB2 readable table of contents of the book (required for EPUB2, optional for EPUB3). The OPF contains a list of files in the book (manifest). It also holds the book metadata, and determines chapter display order (spine), and some semantic data. The OPF is basically the controlling document for the EPUB.
Sigil has many powerful tools to automate repairing, splitting, merging, renaming, and moving xhtml, images, stylesheets, and other resources. These tools can make numerous changes that a simple Undo/Redo can not handle. To help prevent inadvertent data loss and to provide a way to “undo” even larger scale changes, we have added a Checkpoint capability to Sigil.
-A checkpoint is a quick snapshot of the entire state of the EPUB that is stored in its own git style repository that is kept inside your Sigil Preferences folder. Creating a checkpoint can be as simple as one click on the Checkpoint icon or by using the Checkpoint Menus. Each Checkpoint made of an EPUB is named/numbered sequentially.
+A checkpoint is a quick snapshot of the entire state of the EPUB that is stored in its own git repository that is kept inside your Sigil Preferences folder inside the "repo" folder. Creating a checkpoint can be as simple as one click on the Checkpoint icon or by using the Checkpoint Menus. Each Checkpoint made of an EPUB is named/numbered sequentially.
Once a Checkpoint is made, users can feel safe to make larger changes to their copy knowing that they can easily restore to their last checkpoint.
+Users can also edit and attach their own short description of each Checkpoint: to help keep track of at what point in the editing process this checkpoint was made.
+An added advantage of using checkpoints is that a user can always compare the current state of their EPUB against any of their earlier checkpoints to see exactly what was changed and how. Here is image showing the output of a comparison done against an earlier checkpoint during an editing session. After selecting the checkpoint to compare against the following dialog is shown showing which files have changed:
Or they can generate a summary of the changes made in each checkpoint to help them select earlier versions to restore from if needed.
+Or they can generate a summary of the changes made in each checkpoint: to help them select earlier versions to restore from if needed.
Clip Bar and Clip Bar2 are optional toolbars that will show buttons for the first 40 clips (20 clips per bar) that are not in a group. You can display the clip bars by selecting the menu item and :
+Clip Bar and Clip Bar2 are optional toolbars that will show buttons for the first 60 clips (30 clips per bar) that are not in a group. You can display the clip bars by selecting the menu item and :
diff --git a/src/OEBPS/Text/code_view.xhtml b/src/OEBPS/Text/code_view.xhtml
index 3da79b9..33baba0 100644
--- a/src/OEBPS/Text/code_view.xhtml
+++ b/src/OEBPS/Text/code_view.xhtml
@@ -10,7 +10,7 @@
— Direct XHTML Editing —
+— Direct XHTML and CSS Editing —
Code View allows you to directly edit the XHTML and CSS code included in your EPUB and is the most common way to edit files for advanced users.
@@ -19,12 +19,12 @@Use the Preview window to display a read-only book view version of the page you are editing in Code View.
+Use the Preview window to display an auto-updated, read-only web browser like version of the page you are editing in Code View.
Code View is very powerful, but you must be careful when editing it to ensure you enter valid XHTML or CSS code.
-In addition to displaying your XHTML code exactly as it is in your EPUB, Code View highlights tags and elements in colors to make it easier to read and identify issues.
+In addition to displaying your XHTML and CSS code exactly as it is in your EPUB, Code View highlights tags and elements in colors to make it easier to read and identify issues.
You can change the colors used for highlighting in Code View using Preferences: Appearance.
diff --git a/src/OEBPS/Text/external_xhtml_editor.xhtml b/src/OEBPS/Text/external_xhtml_editor.xhtml index af5cd6f..4c45c8f 100644 --- a/src/OEBPS/Text/external_xhtml_editor.xhtml +++ b/src/OEBPS/Text/external_xhtml_editor.xhtml @@ -12,7 +12,7 @@— Integrating PageEdit WYSIWYG Editor into Sigil —
-WYSIWYG editing mode – referred to as BookView in older Sigil User Guides – was removed from Sigil in version 0.9.15 because that editing mode used live html editing based on the QtWebKit/Webkit browser engine that often resulted in incorrect or broken xhtml. Since this browser engine was embedded in Qt, we had no way of changing or fixing that behaviour. This broken xhtml was often rejected by epubcheck and therefore most publishers would not accept it. Sigil 0.9.14 is the last version of Sigil to include the BookView mode of editing.
+WYSIWYG editing mode – referred to as BookView in older Sigil User Guides – was removed from Sigil in version 0.9.15 because that editing mode used live html editing based on the QtWebEngine/Chromium browser engine that often resulted in incorrect or broken xhtml. Since this browser engine was embedded in Qt, we had no way of changing or fixing that behaviour. This broken xhtml was often rejected by epubcheck and therefore most publishers would not accept it. Sigil 0.9.14 is the last version of Sigil to include the BookView mode of editing.
If you need still need the ability to do minor editing and proofing in a WYSIWYG environment, the maintainers of Sigil have created a standalone app called PageEdit that can be launched via Sigil’s Preferred External XHtml Editor tool by setting the path to the external editor’s executable in Sigil’s preferences ().
diff --git a/src/OEBPS/Text/features.xhtml b/src/OEBPS/Text/features.xhtml index 76729c7..f246611 100644 --- a/src/OEBPS/Text/features.xhtml +++ b/src/OEBPS/Text/features.xhtml @@ -18,7 +18,7 @@You edit your book using Code View. The Code View editor allows you to directly edit the XHTML formatting of your files to give you complete control over your book and will allow you to use all of Sigil’s advanced features. You can use Sigil’s live Preview window with Code View to show you what your page will look like as you type.
+You edit your book using Code View. The Code View editor allows you to directly edit the XHTML formatting of your files and edit the CSS stylesheets that style it, to give you complete control over your book and will allow you to use all of Sigil’s advanced features. You can use Sigil’s live Preview window with Code View to show you what your page will look like as you type.
*NOTE*: Book View and its WYSIWYG editing was removed from Sigil in version 0.9.15. See this chapter on integrating PageEdit with Sigil as an alternative WYSIWYG editing mechanism.
@@ -62,6 +62,6 @@Sigil has been translated into over 23 languages and makes it easy to change the user interface language as needed. It is written in C++ for high performance and includes full Unicode UTF-8 support.
+Sigil has been translated into over 20 languages and makes it easy to change the user interface language as needed. It is written in C++ for high performance and includes full Unicode UTF-8 and UTF-16 support.