update the guide to sigil 2.3.0 (2nd chance)

Sigil-Ebook · Aug 10, 2024 · cae0175 · cae0175
1 parent 9df6756
commit cae0175
Show file tree

Hide file tree

Showing 65 changed files with 515 additions and 240 deletions.
diff --git a/src/OEBPS/Images/copy-icon.svg b/src/OEBPS/Images/copy-icon.svg
diff --git a/src/OEBPS/Images/cp-menu.png b/src/OEBPS/Images/cp-menu.png
diff --git a/src/OEBPS/Images/cycle-css-icon.svg b/src/OEBPS/Images/cycle-css-icon.svg
diff --git a/src/OEBPS/Images/docx-import-plugin5.png b/src/OEBPS/Images/docx-import-plugin5.png
diff --git a/src/OEBPS/Images/find-replace-basic.png b/src/OEBPS/Images/find-replace-basic.png
diff --git a/src/OEBPS/Images/find-replace-options.png b/src/OEBPS/Images/find-replace-options.png
diff --git a/src/OEBPS/Images/inspect-icon.svg b/src/OEBPS/Images/inspect-icon.svg
diff --git a/src/OEBPS/Images/preferences-appearance-mainUI.png b/src/OEBPS/Images/preferences-appearance-mainUI.png
diff --git a/src/OEBPS/Images/preferences-general-advanced.png b/src/OEBPS/Images/preferences-general-advanced.png
diff --git a/src/OEBPS/Images/preview-window.png b/src/OEBPS/Images/preview-window.png
diff --git a/src/OEBPS/Images/print-icon.svg b/src/OEBPS/Images/print-icon.svg
diff --git a/src/OEBPS/Images/reload-icon.svg b/src/OEBPS/Images/reload-icon.svg
diff --git a/src/OEBPS/Images/saved-searches-editing-controls.png b/src/OEBPS/Images/saved-searches-editing-controls.png
diff --git a/src/OEBPS/Images/select-all-icon.svg b/src/OEBPS/Images/select-all-icon.svg
diff --git a/src/OEBPS/Images/sigil_dark.png b/src/OEBPS/Images/sigil_dark.png
diff --git a/src/OEBPS/Images/sigil_light.png b/src/OEBPS/Images/sigil_light.png
diff --git a/src/OEBPS/Images/tutorial-find-adv-options.png b/src/OEBPS/Images/tutorial-find-adv-options.png
diff --git a/src/OEBPS/Images/tutorial-find-adv-page.png b/src/OEBPS/Images/tutorial-find-adv-page.png
diff --git a/src/OEBPS/Images/tutorial-find-adv-regex.png b/src/OEBPS/Images/tutorial-find-adv-regex.png
diff --git a/src/OEBPS/Images/tutorial-find-adv-replace.png b/src/OEBPS/Images/tutorial-find-adv-replace.png
diff --git a/src/OEBPS/Images/tutorial-find-all.png b/src/OEBPS/Images/tutorial-find-all.png
diff --git a/src/OEBPS/Images/tutorial-find-count.png b/src/OEBPS/Images/tutorial-find-count.png
diff --git a/src/OEBPS/Images/tutorial-find-regex-chapter.png b/src/OEBPS/Images/tutorial-find-regex-chapter.png
diff --git a/src/OEBPS/Images/tutorial-find-start.png b/src/OEBPS/Images/tutorial-find-start.png
diff --git a/src/OEBPS/Images/tutorial-load-html.png b/src/OEBPS/Images/tutorial-load-html.png
diff --git a/src/OEBPS/Images/tutorial-main-window.png b/src/OEBPS/Images/tutorial-main-window.png
diff --git a/src/OEBPS/Images/tutorial-preview.png b/src/OEBPS/Images/tutorial-preview.png
diff --git a/src/OEBPS/Images/ui_View.png b/src/OEBPS/Images/ui_View.png
diff --git a/src/OEBPS/Images/ui_book-browser-context-menu.png b/src/OEBPS/Images/ui_book-browser-context-menu.png
diff --git a/src/OEBPS/Images/ui_buttons-moved.png b/src/OEBPS/Images/ui_buttons-moved.png
diff --git a/src/OEBPS/Images/ui_customize_window_floating.png b/src/OEBPS/Images/ui_customize_window_floating.png
diff --git a/src/OEBPS/Images/ui_customize_window_redock_as_panel.png b/src/OEBPS/Images/ui_customize_window_redock_as_panel.png
diff --git a/src/OEBPS/Images/ui_customize_window_redocked_as_panel.png b/src/OEBPS/Images/ui_customize_window_redocked_as_panel.png
diff --git a/src/OEBPS/Images/ui_customize_window_redocked_as_tab.png b/src/OEBPS/Images/ui_customize_window_redocked_as_tab.png
diff --git a/src/OEBPS/Images/ui_customize_window_redocking.png b/src/OEBPS/Images/ui_customize_window_redocking.png
diff --git a/src/OEBPS/Images/ui_rearranged-and-undocked.png b/src/OEBPS/Images/ui_rearranged-and-undocked.png
diff --git a/src/OEBPS/Images/ui_toolbar-back.png b/src/OEBPS/Images/ui_toolbar-back.png
diff --git a/src/OEBPS/Images/ui_user-interface-default.png b/src/OEBPS/Images/ui_user-interface-default.png
diff --git a/src/OEBPS/Text/about_epub.xhtml b/src/OEBPS/Text/about_epub.xhtml
@@ -14,7 +14,7 @@
 
   <p>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.</p>
 
-  <p>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 <span class="example">&lt;h1&gt;</span> or <span class="example">&lt;p&gt;</span>) 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.</p>
+  <p>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 <span class="example">&lt;h1&gt;</span> or <span class="example">&lt;p&gt;</span>) 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.</p>
 
   <p>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. <span class="example">&lt;h1&gt;</span> (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.</p>
 
@@ -52,7 +52,7 @@
   <p>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:</p>
 
   <ul>
-    <li><a href="http://idpf.org/epub/201">Official EPUB 2.0.1 IDPF Standard</a> <br/> <a href="http://idpf.org/epub/30">Official EPUB 3.0 IDPF Standard</a> <br/> <a href="https://www.w3.org/publishing/epub32/epub-spec.html">Official EPUB 3.2 (Current Standard)</a>
+    <li><a href="http://idpf.org/epub/201">Official EPUB 2.0.1 IDPF Standard</a> <br/> <a href="http://idpf.org/epub/30">Official EPUB 3.0 IDPF Standard</a> <br/> <a href="https://www.w3.org/TR/epub-33/">Official EPUB 3.3 (Current Standard)</a>
 
 
     <ul>

diff --git a/src/OEBPS/Text/advanced_topics.xhtml b/src/OEBPS/Text/advanced_topics.xhtml
@@ -0,0 +1,137 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!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>Advanced Topics</title>
+  <link href="../Styles/styles.css" type="text/css" rel="stylesheet"/>
+</head>
+
+<body>
+  <h1 id="user_interface">Advanced Topics</h1>
+
+  <h2 id="sigil_toc_id_35">Using Sigil's Environment Variables</h2>
+
+
+  <p>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 <a href="https://en.wikipedia.org/wiki/Environment_variable">https://en.wikipedia.org/wiki/Environment_variable&gt;</a> for more information on setting and using environment variables on your computer.</p>
+
+  <p>Sigil Uses the following Environment Varabiles:</p>
+
+  <ul>
+    <li><p><span class="listheading">SIGIL_DISABLE_VERSION_META</span> Set this environment variable to any value to prevent Sigil from adding the metadata that identifies Sigil as the producer of this epub.</p></li>
+
+    <li><p><span class="listheading">SIGIL_DISABLE_NFC_NORMALIZATION</span> 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.</p></li>
+
+    <li><p><span class="listheading">SIGIL_FOCUS_HIGHLIGHT_COLOR</span> 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.</p></li>
+
+    <li><p><span class="listheading">SIGIL_ALLOW_CODEVIEW_DROP</span> 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).</p></li>
+
+    <li><p><span class="listheading">SIGIL_DEBUG_LOGFILE</span> 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.</p></li>
+
+  <li><p><span class="listheading">SIGIL_USE_FREETYPE_FONTENGINE</span> This environment variable is <b>Windows Only</b>. 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.</p></li>
+
+    <li><p><span class="listheading">SIGIL_PREVIEW_TIMEOUT</span> 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.</p></li>
+
+    <li><p><span class="listheading">SIGIL_DRAG_DISTANCE_TWEAK</span> This environment varaible is <b>Windows Only</b>. 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.</p></li>
+
+    <li><p><span class="listheading">SIGIL_DISABLE_CURSOR_BLINK</span> 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.</p></li>
+
+    <li><p><span class="listheading">SKIP_SIGIL_UPDATE_CHECK</span> 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.</p></li>
+
+   <li><p><span class="listheading">SIGIL_PREFS_DIR</span> This environment Variable is primarily <b>Linux Only</b>. Setting this tells Sigil where your Sigil Preferences Location folder is located.</p></li>
+
+   <li><p><span class="listheading">SIGIL_EXTRA_ROOT</span> This environment Variable is primarily <b>Linux Only</b>. Setting this tells Sigil where your share/sigil folder is located.</p></li>
+
+   <li><p><span class="listheading">SIGIL_DICTIONARIES</span> This environment Variable is primarily <b>Linux Only</b>. Setting this tells Sigil where to locate the hunspell dictionaries installed on your system.</p></li>
+  </ul>
+
+  <div class="tip">
+    <p class="tiptext">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.</p>
+  </div>
+
+<hr class="narrow"/>
+
+  <h2 id="sigil_toc_id_36">Using Sigil's Template Files</h2>
+
+  <p>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.</p>
+
+  <ul>
+     <li><p><span class="listheading">user-template2.xhtml</span> Epub2 specific xhtml file.</p></li>
+
+     <li><p><span class="listheading">user-template3.xhtml</span> Epub3 specific xhtml file.</p></li>
+
+     <li><p><span class="listheading">user-template2.css</span> Epub2 specific css file.</p></li>
+
+     <li><p><span class="listheading">user-template3.css</span> Epub3 specific css file.</p></li>
+
+</ul>
+
+  <p>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.</p>
+  <p>Sigil allows these cover templates to use a set of PLACEHOLDERS that Sigil will automatically fill in values for when creating the cover: </p>
+    <ul>
+        <li>SGC_IMAGE_FILENAME - the relative path to the chosen image.</li>
+        <li>SGC_IMAGE_WIDTH - the width in pixels of the chosen image.</li>
+        <li>SGC_IMAGE_HEIGHT - the height in pixels of the chosen image.</li>
+    </ul>
+
+  <p>Here is an example of a cover-template3.xhtml that uses SVG and makes use of these PLACEHOLDERS:</p>
+
+<pre><code>
+    &lt;?xml version="1.0" encoding="UTF-8" standalone="no" ?&gt;
+    &lt;!DOCTYPE html&gt;
+
+    &lt;html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" lang="en" xml:lang="en"&gt;
+    &lt;head&gt;
+      &lt;title&gt;Cover&lt;/title&gt;
+    &lt;/head&gt;
+
+    &lt;body&gt;
+      &lt;div style="height: 100vh; text-align: center; padding: 0pt; margin: 0pt;"&gt;
+        &lt;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"&gt;
+          &lt;image width="SGC_IMAGE_WIDTH" height="SGC_IMAGE_HEIGHT" xlink:href="SGC_IMAGE_FILENAME\"/&gt;
+        &lt;/svg&gt;
+      &lt;/div&gt;
+    &lt;/body&gt;
+    &lt;/html&gt;
+</code></pre>
+
+<hr class="narrow"/>
+
+  <h2 id="sigil_toc_id_37">Embedding a PDF inside an Epub3</h2>
+
+  <p> 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.</p>
+
+  <p>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.</p>
+
+  <p>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.</p>
+
+  <p>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.</p>
+
+
+<pre><code>
+&lt;?xml version="1.0" encoding="utf-8"?&gt;
+&lt;!DOCTYPE html&gt;
+
+&lt;html xmlns="http://www.w3.org/1999/xhtml"&gt;
+&lt;head&gt;
+  &lt;title&gt;PDF Test Page&lt;/title&gt;
+&lt;/head&gt;
+
+&lt;body&gt;
+
+  &lt;object type="application/pdf" data="../Misc/demo.pdf" width="500" height="500"&gt;
+
+        &lt;!-- The child of the object tag holds the xhtml fallback --&gt;
+        &lt;h3 class="sigil_not_in_toc"&gt;PDF Fallback text&lt;/h3&gt;
+
+        &lt;p&gt;This text is being displayed, if the reader or reading device doesn't support embedded .pdf files.&lt;/p&gt;
+
+  &lt;/object&gt;
+
+&lt;/body&gt;
+&lt;/html&gt;
+</code></pre>
+
+ <p>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.</p>
+</body>
+</html>