[Plugin] LOI-Generator - edit] plugin to generate a List of Illustrations

[KevinH]

Updated: January 19, 2023
Current Version: "0.4.0"

See the attached: LOI-Generator_v040.zip

License/Copying: GNU LGPL Version 2 or Version 3 your choice. Any other license terms are only available directly from the author in writing.

Change Log

Spoiler:

v040
1) first public release

Important Caveats

A list of illustrations (loi) is NOT a list of links to all images found in an epub.

The loi only contains links to images that are major structural components of the work and these structural components typically include image title and or captions, and are generally referenced in some way in the text of the book.

Quoting https://standardebooks.org:

An illustration is a major structural component if, for example: it is an illustration of events in the book, like a full-page drawing or end-of-chapter decoration; it is essential to the plot, like a diagram of a murder scene or a map; or it is a component of the text, like photographs in a documentary narrative.

An illustration is not a major structural components if, for example: it is a drawing used to represent a person’s signature, like an X mark; it is an inline drawing representing text in alien languages; it is a drawing used as a layout element to illustrate forms, tables, or diagrams.

Before Running the Plugin
1. Make sure your epub validates under EpubCheck

2. If an loi file already exists and you want to update it, make sure you have indicated the loi semantic for that file in the epub2 OPF guide or epub3's NAV landmarks by using BookBrowser's Add Semantics.

3. If you want to override any existing images caption/title for use in the loi entry, add a "title" attribute and value to that images parent svg, div, or figure tag. This added title attribute will take precedence over all other sources for image descriptions by this plugin when creating the loi.


How this Plugin Works
1) This plugin will walk all of the xhtml files listed in the spine (in spine order) and look for images represented by an "img" or "svg image" tag that are wrapped in particular parent tags that would allow for a caption or title to be present.

The list of currently recognized patterns is:

• figure tags with child figcaption (epub3)
• div tag with child p to hold a title or caption
• div tag with child div tag to hold a title or caption
• svg tag with svg title or svg desc child tag to hold a title or caption

2) When an "img" or "image" tag is found, its immediate parent is determined. This parent is then searched for descriptive information such as a title, caption, or alt description. If found, a link to this image is added to the loi and its id attribute. If a target loi entry does not have a suitable id attribute, a unique one is added.

Not all files in the spine are searched for images to prevent any cover images from being included.
The following file types are skipped: ["loi", "cover", "toc", "loa", "lov", "index", "other.loa", "other.lov", "lot"]

3) If no descriptive information is found (no caption, title, or alt value) for a particular entry, the plugin will handle it in different ways depending on its "mode" of operation:

4) Modes of Operation

• drop mode, these entries will be discarded (not become part of the generated loi).
• comment mode, these entries will be added as xhtml comments to the list
• keep mode, these entries will be added as normal to the loi but will need to have descriptive information added later by the user

5) Once a complete list of links to these illustrations has been built, an existing loi xhtml is looked for.
An existing loi file is identified by having the "loi" entry in the OPF guide under epub2, or in the NAV landmarks under epub3. You can use BookBrowser Add Semantics on that file to set it. If no existing loi xhtml file is found, a new "loi.xhtml" file will be created and added to the epub upon completion of the plugin. The language to use for the newly created loi is determined by the value of the first dc:language entry in the OPF. The newly create loi.xhtml file will have an "ol" tag containing the full list of loi entries.


Upon Completion
If a newly built loi.xhtml file is added, the user should drag and drop it where desired in BookBrowser and when satisfied regenerate any and all TOCs.


Summary of Changes Made to epub by the plugin
As stated earlier, if ids are missing from images, they will be added where needed in the files. In addition, to minimize any potential data loss, if an existing loi file is found inside the epub when the plugin in launched, it is parsed to look for an "ol" tag and will only replace the contents of that "ol" tag. If no "ol" tag is found in that loi file, one is added at the end of the file just before its closing body tag. If a new loi.xhtml file needs to be created, it is added as a "loi" type to the NAV Landmarks under epub3 or to the OPF Guide under epub2.


User Preference Settings
After first run, inside the Sigil Preferences folder, inside the plugins_prefs folder you will see a LOI-Generator folder that contains the json preferences used by LOI-Generator


LOI-Generator.json

{
  "mode": "comment",
  "tabwidth": 4,
  "heading": "h1",
  "numbers": "no"
}

The possible mode values are "keep", "comment" or "drop" which controls how images without captions are treated. (See above description of Modes of Operation).

The tabwidth value is numeric and determines how tabs are converted to spaces.

The heading value is one of ["h1", "h2", "h3", "h4", "h5", "h6"] and its value is used to wrap the translated title "List of Illustrations" at the top of a newly created loi.xhtml file.

The numbers has two possible values:
- "no" then style="list-style-type: none;" is added to the ol tag in the newly generated loi file
- "yes" means that no style attribute is added to that tag

The default values are shown above.

Artwork
Please thank BeckyEbook for contributing the icon (both png and svg) used by this plugin.


Very Important Note
Support for this plugin is only provided for Sigil 1.0.0 or later. This plugin requires Sigil 1.0.0 or later to even operate.


Take care,

KevinH

[Tenome]

Thanks again!