[Editor Plugin] Editor Chains

capink · 11-22-2021, 05:13 AM

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:

Code:

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:

capink · 11-22-2021, 05:13 AM

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 · 11-22-2021, 05:14 AM

Attached are examples to "Tag Actions" chains.

jbacelar · 11-25-2021, 05:05 AM

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

jbacelar · 11-27-2021, 04:35 AM

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 · 11-28-2021, 04:17 AM

Quote:

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 · 01-07-2022, 05:31 AM

Changes for the upcoming PyQt6.

capink · 11-29-2022, 12:14 AM

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 · 12-04-2022, 01:44 AM

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:

Code:

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

Terisa de morgan · 12-04-2022, 03:46 AM

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 · 12-04-2022, 12:37 PM

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 · 12-04-2022, 01:40 PM

Ok, thank you.

capink · 12-06-2022, 06:41 PM

This version introduces two new Actions

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.
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 · 12-12-2022, 12:58 AM

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 · 12-26-2022, 10:07 AM

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:

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.
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.

11-22-2021, 05:13 AM	#2
capink Wizard Posts: 1,139 Karma: 1954142 Join Date: Aug 2015 Device: Kindle	Tag Actions 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 Individual Tag(s) The default option where you select single tag(s) based on criteria, and apply action on them individually 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: First tag in the range 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: (Optional) Abort: Here you specify criteria for tag that if found between the first and last tags, the range broken and not selected</dd> (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: Tag Name: Allows for regular expression or exact matching of tag name. 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. 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 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. Style Property: Allows you choose a tag based on its style e.g. font-size, color .... etc 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: 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 Delete: Delete tag(s) and its contents Wrap: Wrap the tag(s) in a new tag Unwrap: Delete only the tag but keeping its text Insert Before: Insert a text or tag before Insert After: Insert a text or tag after 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 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. Attached Thumbnails Last edited by capink; 12-12-2022 at 01:38 AM.

01-07-2022, 05:31 AM	#7
capink Wizard Posts: 1,139 Karma: 1954142 Join Date: Aug 2015 Device: Kindle	Version 0.5.0 Changes for the upcoming PyQt6.

11-29-2022, 12:14 AM	#8
capink Wizard Posts: 1,139 Karma: 1954142 Join Date: Aug 2015 Device: Kindle	Version 0.7.0 This new version adds some new actions that fall under three categories: Plugin specific actions Add Templates Calibre editor builtin actions Create TOC. MultiSplit. Transform Styles Calibre polish actions Embed Fonts. Subset Fonts. Remove Unused CSS. Update Book Internals. Smarten Punctuation. Fix HTML. Beautify All. 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).

12-04-2022, 01:44 AM	#9
capink Wizard Posts: 1,139 Karma: 1954142 Join Date: Aug 2015 Device: Kindle	Version 0.7.1 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: Code: calibre-debug -r "Editor Chains" chain_name input_file output_file

12-06-2022, 06:41 PM	#13
capink Wizard Posts: 1,139 Karma: 1954142 Join Date: Aug 2015 Device: Kindle	New Version 0.7.2 This version introduces two new Actions 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. Expand Styles This is the same functionality you see when using calibre convert books. It basically expands shorthand properties like margin, padding, border ... etc Last edited by capink; 12-07-2022 at 01:24 PM.

11-25-2021, 05:05 AM	#4
jbacelar Interested in the matter Posts: 421 Karma: 426094 Join Date: Dec 2011 Location: Spain, south coast Device: Pocketbook InkPad 3	I think it could be very useful to me. I will give it a try. Thank you in advance!

11-27-2021, 04:35 AM	#5
jbacelar Interested in the matter Posts: 421 Karma: 426094 Join Date: Dec 2011 Location: Spain, south coast Device: Pocketbook InkPad 3	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!

12-04-2022, 03:46 AM	#10
Terisa de morgan Grand Sorcerer Posts: 6,393 Karma: 12408443 Join Date: Jun 2009 Location: Madrid, Spain Device: Kobo Clara/Aura One/Forma,XiaoMI 5, iPad, Huawei MediaPad, YotaPhone 2	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.

12-04-2022, 12:37 PM	#11
capink Wizard Posts: 1,139 Karma: 1954142 Join Date: Aug 2015 Device: Kindle	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.

12-04-2022, 01:40 PM	#12
Terisa de morgan Grand Sorcerer Posts: 6,393 Karma: 12408443 Join Date: Jun 2009 Location: Madrid, Spain Device: Kobo Clara/Aura One/Forma,XiaoMI 5, iPad, Huawei MediaPad, YotaPhone 2	Ok, thank you.

Similar Threads
Thread	Thread Starter	Forum	Replies	Last Post
[Editor Plugin] EpubCheck	Doitsu	Plugins	163	07-23-2024 09:07 AM
[Editor Plugin] LanguageTool	Doitsu	Plugins	17	04-20-2024 03:21 PM
[Editor Plugin] - Enabling 'Customize plugin' dialog directly from the Editor	thiago.eec	Development	7	01-09-2019 09:05 PM
Sample Plugin for the Editor	DiapDealer	Editor	77	12-10-2014 08:16 AM
Editor plugin question	DiapDealer	Development	2	07-28-2014 11:23 PM

Advert

Advert