[Editor Plugin] Editor Chains

[capink]

For people familiar with the Action Chains plugin, this is a similar plugin for the calibre editor. It allows the user to chain multiple actions and run them together.

Currently Available Actions:

• Plugin Actions
  1. Tag Actions: Allows the user to apply a variety of actions on tags, which are located based on range of tag criteria configured by the user. See here for more on this action can do.
     
  2. Style Actions: For more on this action including sample chains, see here.
     
  3. Search and replace: This action is based on calibre editor's search and replace. I included this mainly to be able to do search and replace on multiple books, leveraging the editor's function replace mode. More on this on the section on how to integrate the plugin with the action chains plugin.
     
  4. Mark cursor tag: Using this action you can mark tags, so that you can later apply batch operations on them using the Tag Actions. The way to do this, is the to make a chain containing the mark action and bind it to a keyboard shortcut. After that you can mark the tags by simply clicking on the shortcut when the cursor inside the tag.
     An example for using this can be found in this post.
  5. Add Templates: Add templates (css, images ... etc) to the ebook from predefined locations.
  6. Remove Files
  7. Remove Unused Images
  8. Flatten TOC
  9. Inline Styles To CSS: You can read more about this action here.
  10. Expand Styles
  11. Run command: Run a command of files inside the book.
      
• Calibre editor builtin actions
  1. Create TOC.
  2. Insert Inline TOC.
  3. MultiSplit.
  4. Transform Styles.
  5. Transform HTML.
  6. Embed Fonts.
  7. Subset Fonts.
  8. Remove Unused CSS.
  9. Update Book Internals.
  10. Smarten Punctuation.
  11. Fix HTML.
  12. Beautify All.
  13. Compress Images.
  14. Arrange Into Folders.

How to use the plugin:

To make a new chain follow these steps:

• From the drop-down menu choose the "Add/Modify chains" entry to open the config dialog.
• In the config dialog press the add button to add a new empty chain.
• Double click on the name field to give the new chain a name, and optionally choose a sub-menu and an icon.
• To start adding actions to the chain, press the settings button in the chain row, which will open the add actions dialog.
• In the add actions dialog, press on the add action button. After this choose and action you want from the actions combo-box. Press the action settings button configure the action.
• Repeat for all actions you want to add, and then press OK.

Integration with Action Chains:
First, you must have the latest version of both the Editor Chains plugins and the Actions Chains plugin installed.

The combination of the two plugins will allow you to run your editor chains on multiple books in your library. You can do that be choosing to run whatever editor chain you want from Action Chains (which have action called "Run Editor Chain").

See here for more on how to use the Action Chains plugin.

Examples of how to use Tag Actions:
Below you can find links to two chains that you can import (Editor Chains > Add/Modify Chains > Right Click > Import Chain)

• The first chain will match a range(s) of adjacent span tags that all share one similar class called "italic". This is an exact match, so it will not apply for spans containing other additional classes (although you can modify to do so if you want). And then, it merges all these spans into one span. You can download it from here.
  
• The second chain goes one step further, by merging any adjacent spans with similar classes without having to specify what the classes are. You can download it from here.

Note: The criteria above makes sure there is no text between the spans that can break their continuity. But it still allows for text containing only white-space. You can refine this to include whatever punctuation characters you want, by modifying the regular expression in the text filters.

Running the plugin from the command line
You can run the plugin from the command line as follows:

calibre-debug -r "Editor Chains" chain_name input_file output_file

Note that before running the chain, it will be validated to make sure all member actions can be run from the command line. Currently, all actions in the plugin can run from the command line. Sometimes, However, a certain setting will make an action unavailable for the command line. e.g "Search and replace" with a setting to search "selected files", will not run from the command line (or from Action Chains plugin), because the setting needs the editor GUI to be open with files selected.


Note on Module Editor:

• Similar to Action Chains plugin, this plugin provides a module editor for people who want to write their own actions. For information on how to write your own actions, see the comments in calibre_plugins.editor_chains.actions.base

Paypal Donations:

• If you find this useful please feel free to show your appreciation.
  

Version History:

Spoiler:

Version 1.1.4 - 17 January 2024
Fix: Run Command: further problems when joining filename parts if directory is empty

Version 1.1.3 - 16 January 2024
Fix: Run Command: Don't join file components using os.path.join, because on Windows it uses backslashed and messes up the ebook filename.

Version 1.1.2 - 16 January 2024
Update: Run Command: Update media_type after running command.

Version 1.1.1 - 11 January 2024
Update: Modifications to "Run Command" action.
Fix: Actions Chains should not be installed for the plugin command line mode to work.

Version 1.1.0 - 8 January 2024
Update: Add "Arrange Into Folder" action.

Version 1.0.2 - 28 December 2023
Tag Actions: Search & Replace: Fix overlapping tags.

Version 1.0.1 - 15 December 2023
Tag Actions: Search & Replace: Some modifications.

Version 1.0.0 - 12 December 2023
Update: Add Templates: Action is rename into "Add Files". It now supports adding a directory tree into the book.
Update: Bump up config schema to 1.1

Version 0.9.6 - 4 December 2023
Fix: Bug in multisplit action.

Version 0.9.4 - 20 November 2023
Update: Action Chains: Add the ability to embed a chain instead of referencing and already existing chain.

Version 0.9.2 - 7 November 2023
Fix: Transform HTML: missing scope setting.

Version 0.9.1 - 15 September 2023
Update: Add another option to scopes to be able to select text file by performing a regex search on them.

Version 0.9.0 - 9 September 2023
Modifications to "Run Command" Action. Not backward compatible, so chains containing the action need to be recreated.

Version 0.8.9 - 29 August 2023
Update: New "Run Command" Action.
Update: Modifications to scopes.

Version 0.8.8 - 11 July 2023
Add API for imported actions and on_modules_update.

Version 0.8.7 - 22 May 2023
Fix: When running from Action Chains, notify calibre to update filesizes of modified files.

Version 0.8.6 - 15 May 2023
Update: Style Actions: New "Add Properties" Action.
Fix: Scopes: Enable (*.opf, *.ncx, *.txt, *.xml) files in both Include Filenames and Exclude Filenames.

Version 0.8.5 - 12 April 2023
Update: Add Templates Action: New options.

Version 0.8.4 - 9 April 2023
Fix: Bug when copying a separator.
Fix: Escape ampersands in menu entries.
Fix: Contamination of chain vars.

Version 0.8.3 - 19 December 2022
Update: New "Styles Actions" Actions.

Version 0.8.1 - 14 December 2022
Update: Add Templates: Add option to link added xhtml files to css sheets already in container.
Fix: Tag Actions: Style Property Filter: TypeError exception on comparison with None values.
Fix bug in Flatten TOC.

Version 0.8.0 - 11 December 2022
Update: Tag Actions: Add Style filter
Update: Tag Actions: Modifications to config widget.
Update: Tag Actions: Add ability to narrow down the nodes by css selectors.
Update: Tag Actions: set regex.DOTALL flag for "Tag Text" filter.
Fix: Tag Actions: Fix bug when specifying xpath and not configuring any tag filters.
Fix: Search & Replace: Replace function name not loading in config widget.
Fix: Expand Styles: Font size not updated in inline styles.
Fix: Tag Actions: regex values returning match object instead of True.

Version 0.7.2 - 5 December 2022
Update: Add "Expand Styles" Action.
Update: Add "Inline Styles To CSS" Action.
Update: Insert Inline TOC: Add option to insert TOC at tha back of the book.
Update: Insert Inline TOC: Add option to change the name of the inserted TOC.

Version 0.7.1 - 29 November 2022
Update: Add "Remove Files" Action.
Update: Add "Remove Unused Images" Action.
Update: Add "Insert Inline TOC" Action.
Update: Add "Flatten TOC" Action.
Update: Add "Transform HTML" Action.
Update: Add option to run suitable chains from command line using calibre-debug -r "Editor Chains" chain_name input_file output_file
Update: Multisplit: Add option to prevent splitting if no preceding sibling is found. Helpful in case or multiple runs, as it prevents creating empty pages.
Update: Tag Actions: New "Search And Replace" Action.
Update: Tag Actions: Add Xpath wizard to the context menu of the line edit.
Update: Modify behavior of xpath expressions in Tag Actions to include the element and its descendants (as opposed to descendants only).
Add validation for regex.
Fix: Search and Replace: Bug with multiple searches.

Version 0.7.0 - 28 November 2022
Update: Add some editor builtin actions.
Misc fixes.

Version 0.6.2 - 25 November 2022
Update: Don't add save point for chains invoked by chainer caller action.

Version 0.6.1 - 05 November 2022
Update: "Insert Before Cursor Tag" Action.
Update: "Insert After Cursor Tag" Action.
Update: Use regex module instead of re for consistency with calibre editor regex.

Version 0.6.0 - 25 October 2022
Update: Add "Run Python Code" Action.
Update: Add "Mark Cursor Tag".
Update: Add scope to some actions.
Misc fixes.

Version 0.5.4 - 9 August 2022
Update: update to calibre6 icon fetching. Code from @JimmXinu.
Fix: But where submenus where not working.

Version 0.5.3 - 17 July 2022
Fix PyQt6 migration bugs.

Version 0.5.2 - 29 June 2022
Fix: Export chain not working in PyQt6

Version 0.5.1 - 10 February 2022
Fix PyQt6 migration bug.

Version 0.5.0 - 6 January 2022
Changes for the upcoming PyQt6.

Version 0.4.1 - 8 November 2021
Misc updates.

Version 0.4.0 - 8 November 2021
Misc updates.

Version 0.3.1 - 6 November 2021
Misc updates.

Version 0.3.0 - 3 November 2021
Misc updates.

Version 0.2.0 - 30 October 2021
Fix toolbar action not updating.

Version 0.1.0 - 16 October 2021
Initial Release.

[capink]

This is the main action of the plugin. It allows the user to apply a variety of actions on tags, which are located based on range of tag criteria configured by the user.

• TAG_SELECTION
  There are two mode to tag TAG_SELECTION
  1. Individual Tag(s)
     The default option where you select single tag(s) based on criteria, and apply action on them individually
  2. Range(s) of Tags
     Here you can choose range(s) of tags, where you will be able to apply actions on them collectively. e.g wrap them in another tag. To be able to select a range, you need to set criteria of two tags:
     1. First tag in the range
     2. Last tag in the range
     Also there two optional settings to abort the range, even if you are able to match the first and last tags:
     1. (Optional) Abort: Here you specify criteria for tag that if found between the first and last tags, the range broken and not selected</dd>
        
     2. (Optional) Max Steps: The maximum number of tags between the first and last tag. If actual number in a range is higher than the value specified here, the range will not be selected.
  
  
• Info on Tag Criteria
  Opens a dialog for you to select criteria by which to select tags. It allows for boolean or/and criteria, or even nested groups of or/any (by choosing "match all"/"match any") from the dropdown menu.
  Here is a list of the filters by which you can match a tag:
  1. Tag Name: Allows for regular expression or exact matching of tag name.
  2. Attribute: Allows for regular expression or exact matching of different attributes. For multivalue attributes like classes, you can also match a single class by choosing the contain option from the dropdown.
  3. Text: This can apply to the text of tag itself. Or the text immediately before or after i.e. The tail of the previous or next sibling if any
  4. Related Tag: Allows you choose a tag by criteria of its relative tag. e.g. a tag that has a child tag with certain class name.
  5. Style Property: Allows you choose a tag based on its style e.g. font-size, color .... etc
  6. Code: If you know how to code in python, you can refine your criteria by using this filter.
  
  
  
• ACTIONS:
  Perform one of the following actions on the selected tags/ranges:
  1. Modify Tag: Allows you modify a tag in a variety of way:
     • Modify tag name
     • Delete classes or other attributes
     • Add or append new classes
     • Add new attributes
  2. Delete: Delete tag(s) and its contents
  3. Wrap: Wrap the tag(s) in a new tag
  4. Unwrap: Delete only the tag but keeping its text
  5. Insert Before: Insert a text or tag before
  6. Insert After: Insert a text or tag after
  7. Search and Replace: Perform a search and replace on the on the whole element (tag and text). This supports regex and calibre's replace function
  8. Code: If you can program in python, you can use this to apply your custom action

Sample chains

• Merge adjacent span tags that have the class "italic" into single span tag. Can be adapted for different tag e.g. <i> tags. You can download the chain from here.
• Merge adjacent span tags that have the exact same classes. You can download the chain from here.
• Convert paragraphs into headings based on font-size. You can
  download the chain from here.
• Modified version of the above chain, which adds other criteria to convert into h1, h2 heading. The paragraph must have less than 80 letters, must be centered and the text must be bold. You can download the chain from here.

[capink]

Attached are examples to "Tag Actions" chains.

[jbacelar]

I think it could be very useful to me. I will give it a try.
Thank you in advance!

[jbacelar]

I have tried it with "Run Editor Chain" (until now it was impossible to modify something in several books at the same time) and it works great.
Thank you very much again!

[capink]

Originally Posted by jbacelar

I have tried it with "Run Editor Chain" (until now it was impossible to modify something in several books at the same time) and it works great.
Thank you very much again!

Nice to heat that . Make sure to backup and examine the results.

[capink]

Changes for the upcoming PyQt6.

[capink]

This new version adds some new actions that fall under three categories:

• Plugin specific actions
  1. Add Templates
• Calibre editor builtin actions
  1. Create TOC.
  2. MultiSplit.
  3. Transform Styles
• Calibre polish actions
  1. Embed Fonts.
  2. Subset Fonts.
  3. Remove Unused CSS.
  4. Update Book Internals.
  5. Smarten Punctuation.
  6. Fix HTML.
  7. Beautify All.
  8. Compress Images.

All of the newly added actions can be used in chains inside the editor, or run on multiple books in from the Action Chains plugin (see first post for howto).

[capink]

• Add "Remove Files" Action.
• Add "Remove Unused Images" Action.
• Add "Insert Inline TOC" Action.
• Add "Flatten TOC" Action.
• Add "Transform HTML" Action.
• Multisplit: Add option to prevent splitting if no preceding/following sibling is found. This prevents creating empty pages when splitting.
• Add option to run suitable chains from command line using:
  

  calibre-debug -r "Editor Chains" chain_name input_file output_file

[Terisa de morgan]

Thank you for including some of the actions, as they will be useful for me. I've got a request: could this plugin be included in the index of plugins? So I can handle it in the same way than others? Excuse me if you're not interested in it or you have said why it's not there, but it would be useful for me.

[capink]

I need to make sure it is well tested before including it in the index. I have not received any bug reports, but I discovered some major bugs myself.

[Terisa de morgan]

Ok, thank you.

[capink]

This version introduces two new Actions

1. Inline Styles To CSS
   As the name implies this action convert inline styles to CSS. There are some points to note:
   • For documents that mix inline styles and css, blindingly converting inline styles can mess up the formatting because it can disrupt css rules of specificity, precedence ... etc.
   • However, this action actually tries to avoid this, by resolving the effective style values for every element before and after the conversion. If the results are not the same, the changes are rolled back. The heavy-lifting for resolving the styles is done by calibre code. (Thanks Kovid). Still this validation is done on a best effort basis.
   • By default, if one or more styles are found not to be suitable for conversion to CSS, the action will roll back the changes for all the styles.
   • There is a setting to disable the behavior described above, whereby valid styles are converted to CSS while those not suitable for conversion will remain as inline styles.
   • You can configure this option to exclude some elements using an xpath expression.
   • It is still advisable to double check the changes on documents that have a mix of inline and CSS.
2. Expand Styles
   This is the same functionality you see when using calibre convert books. It basically expands shorthand properties like margin, padding, border ... etc

[capink]

Version 0.8.0 - 11 December 2022

• Update: Tag Actions: Add Style filter.
• Update: Tag Actions: Modifications to config widget.
• Update: Tag Actions: Add ability to narrow down the nodes by css selectors.
• Fix: Tag Actions: Fix bug when specifying xpath and not configuring any tag filters.
• Fix: Search & Replace: Replace function name not loading in config widget.
• Fix: Expand Styles: Font size not updated in inline styles.

Style Property Filter

This filter allows you to locate tags by their style and apply actions on them. For example you can filter elements with a certain color or font-size and perform any of the available actions on them.


This filter has the following options:

• Text comparison operators to search for textual styles e.g. font-style "matches" italic
• Numerical operators for dimension based styles like font-size, margin-top, ... etc
• It supports the In-memory (not in the ebook itself) conversion of dimension units (px,pt,..etc) to be able to make a comparison on actual size regardless of the unit used.

To illustrate this, attached below is couple of chains that do the following:

• A chain that changes paragraphs to different headings (h1, h2, h3) based on the paragraph font-size. This first makes an In-memory (not in the ebook itself) conversion of all font-sizes to px.
• A modified version of the above chain: It adds another couple of limitations to paragraphs that will be converted to headings:
  
  1. It only applies to paragraphs with 80 letters or less. This is done by using the "Text Filter" with regex.
  2. For paragraphs to be converted into h1 and h2 headings, they must be centered and bold (by using two other style filters).

Starting with this version, the plugin has been added to the plugins index, and can be downloaded through calibre.

[capink]

Version 0.8.3

• Update: New "Style Actions" action.

This version introduces a new action that allows you to filter and apply actions on styles. It works whether the style is an CSS sheet, in style tag or an inline tag. It Allows you to apply the current actions on styles:

• Style arithmetic: Allows you to do mathematical operations on styles.
• Convert: Allows you to convert dimensions e.g. from pt to px. Only supports absolute dimensions.
• Delete properties.

Attached below are two example chains:

1. Round dimensions to an increment: This chain uses the style arithmetic to round all margin, padding and text-indent properties to an increment of 5.
2. Delete default properties: This chain will delete all properties that have a value that is equal to the default value. e.g. margin-top: 0 ... etc.