[Plugin] ReworkChapterHeads - Add, replace and reformat chapter headings

[slowsmile]

Automatically replaces or adds selected file headings or a single selected file heading in multiple user-defined formats and styles

Requirements
Plugin Type: Edit
MIT Licence(OSI)
Minimum Sigil requirement: v0.9.3 or higher
Python Requirements: Python 3.4+ (Bundled or External)
OS Requirements: Windows, OSX or Linux
*** Tested on Windows 7, 8 & 10, OSX and Linux ***
Current Version: "0.2.2"

Installation
* Select Manage Plugins from the Plugins menu. In the dialog box, select either the Bundled Python or the External Python(Python 3.4+ should be installed on your computer to run this plugin externally).

* Click Add Plugin and select ReworkChapterHeads_vXXX.zip. This will load and install the plugin into Sigil, which you can then select and run using Plugins > Edit > ReworkChapterHeads

Description
This plugin tries to provide an easy and quick way of replacing or adding either multi-file headings or a single file heading in your epub 2 or epub 3 file(added in v0.2.2.) that will be formatted according to the user's own individual styling preferences. The plugin allows the user to do the following:

* Remove and/or add heading(s)
* Add or change the heading text name
* Add or change heading styles
* Change the heading number style to numeric string, number as text or roman numerals
* Change the heading number case to titlecase, uppercase or lowercase
* Add classes to heading tag(s)
* Create numbered headings only
* Hide heading(s)

This plugin automatically inserts all selected file group number types consecutively in various user-defined formats and styles using normal file selection from Sigil's Book Browser(See Plugin Run for details).

User Options 1 -- Remove heading(s) (via dialog)

* Remove heading(s) formatted with...
This option allows the user to initially select and remove all selected heading lines in the epub or a single selected single heading line that is formatted in h1 to h6 heading style. If the Remove button is pressed the appropriate heading lines from the selected files will all be removed. But if the Skip button is pressed then this dialog will do nothing and the plugin will continue. So if you are replacing your heading(s) you should select the relevant heading style and use the Remove button but if you are adding new heading(s) then you should just use the Skip button(no headings will be removed). This remove/add feature is quite flexible and can also be used in other ways e.g. like removing the current h1 chapter headings in an epub and perhaps replacing them with formatted and styled h2 chapter headings.

User Options 2 -- Add new heading(s)(via dialog)

* Add heading name template
This option allows the user to type and add the heading name part of the new heading into the textbox either in title case, lower case or upper case i.e. whatever you type into the textbox will be used as the main heading name throughout.

* Select heading style
Now allows a choice of h1 to h6 heading style for all newly generated headings(changed in v0.1.6).

* Select chapter number style
Allows the user to select the chapter or part numbering style e.g. numeric string, number as text or roman numerals.

* Select chapter number case
This option only works if you have previously chosen Select chapter number style > Number as Text. Available user choices: titlecase, uppercase or lowercase. Chapter number as text case examples: one, Ten and TWENTY-THREE.

* Add classes to heading tag(s)
The user just types a class name into the textbox for that class to be included in all the newly generated chapter heading tags. Also make sure that the class has already been properly defined in the css. If you need to add more than one class per chapter heading, then just add in each class separated by a comma or a space.

* Use numbered headings only(added in v0.1.4)
Allows the user to just use numbered headings for all chapter or part headings e.g. 1, 2, 3 or ONE, TWO, THREE or I, II, III. If Number as Text is selected, the text will always display in upper case whenever numbered headings is selected.

* Hide heading(s)
This feature is particularly useful if you are using jpeg images as chapter headings throughout your epub. By selecting and tagging the same pages containing these heading images using this plugin feature, these new chapter headings will remain invisible in Text View but they will still be present in HTML View, so this should help to make those chapter heading images both linkable and searchable in your epub.

Caveat
The new maximum number of chapters allowed when using the Number as Text or Roman Numerals dialog options has been increased to 100 (added in v0.1.7). Otherwise you'll get overrun errors.

Depending on whether you use h1 to h6 heading styles, be sure that the chosen heading style for your heading is already properly defined by you in the css, otherwise the default heading style will be used. This plugin does not add or change styling in the css.

Plugin Run

* Using Ctl-Click and Shift-Click with your mouse, select either a single file or a multi-file group from Sigil's Book Browser.

* Then just run the plugin and the chapter heading(s) will automatically be replaced or added and formatted according to your dialog choices.

* Also bear in mind, for all chapter file group selections, that this plugin does not automatically update the epub TOC file or the Logical TOC(toc.ncx) to your new chapter heading style, so you should perhaps also run Create TOC and Generate TOC in Sigil to match up all ebook/device displays after running this plugin.

This plugin can now add, replace or modify both selected file groups as well as modify a single heading from a selected xhtml file(added in v0.1.6).

Plugin users should now be able to use single file selection to add or replace the main heading from any selected epub xhtml file e.g. any chapter heading, TOC file, Title, Introduction, Preface, About the Author etc.


Changes

Spoiler:

v0.2.2

-- Removed epub 2 validation. This plugin will now work with epub 2 or epub 3 files. Thanks to @lumpynose.

v0.2.1

-- Fixed a minor bug in the epub validation routine.

v0.2.0

-- Converted User Options 2 dialog from a single column to two column display to prevent widget crossover problems occurring when Windows Accessibility options are used. Thanks to Thasaidon.

v0.1.9

-- Fixed a bug concerning the Add numbered heading only option where the chapter heading text was also being wrongly displayed with the chapter number. Thanks to BeckyEBook.

v0.1.8

-- In the dialog, the text typed into the Add heading name template textbox will now always be saved and displayed on the next plugin run. Thanks to BeckEBook.
-- Fixed a problem in the version updater, which wasn't working.

V0.1.7

-- The new maximum number of chapters allowed when using the Number as Text or Roman Numerals dialog options has been increased to 100.

v0.1.6

-- Plugin functionality has been extended with the following added features:
* Users can now use the plugin to modify a single selected file heading.
* The heading styles available have been increased to h1 to h6 to help accommodate the change.
* Added various cosmetic/notification enhancements to the dialogs to aid ease of use.

v0.1.5

-- The user will now be able to select h1, h2 and h3 heading styles from both dialogs.

v0.1.4

-- Added a new dialog option that allows the user to select numbered headings only. Examples: 1,2,3 or ONE, TWO, THREE or I, II, III.

v0.1.3

-- The plugin will now automatically save the last settings from both dialogs as default settings.

v0.1.2

-- Fixed a bug with roman numerals formatting which was caused by a mispelling by me.

v0.1.1

-- Switched to using ComboBoxes in all dialogs for better visibility.

v0.1.0

-- Initial release

[slowsmile]

My thanks to AlanHK, theducks and DNSB for all their helpful suggestions for this plugin.

[slowsmile]

Not applicable anymore.

[DNSB]

One oddity. I opened Sigil with no input file, installed the plugin and then split the Sigil startup file into two chunks before running the plugin. It worked but which of the two files was Chapter 1 seems to depend on the order I selected the files in. Click on Section0001 and then control-click on Section0002 and I got Section0001 as Chapter 1 and Section0002 as Chapter 2. Select Section0002 first and then Section0001, and Section0002 was Chapter 1 while Section0001 was Chapter 2.

For a real world test, I tried a backup copy of an images as chapter title epub and the plugin worked well adding the chapter numbers.

Did I forget to say thanks? If so, thanks!

[slowsmile]

DNSB...The way Sigil's file selection works has nothing really to do with the plugin. I'm pretty sure that Sigil selection works whereby the files are stored in an ascending list according to the order of selection(usually top to bottom if you use group selections or random selections). As it stands now the user's selection will collect your filenames from top to bottom in the Book Browser and process them exactly like that in the plugin. I must also admit that I never had any selection problems at all when testing the plugin. Perhaps it might be split file which caused these problems.

Also, as advised in the release notes, you must always select all chapter files from the Book Browser for this plugin to work properly. If your file selection does not include all chapter files then you will probably get differences in formatting and chapter file mis-numbering occurring as errors in the result.

[Thasaidon]

Hi



Have downloaded the plugin ready to use tomorrow.

Thank you.

[slowsmile]

Plugin Update: Switched to using combo-boxes in all dialogs for better visibility (v0.1.1)

[slowsmile]

Plugin Update: Fixed a bug with roman numerals formatting which was caused by a mispelling by me(v0.1.2).

[DiapDealer]

Added this to the plugin index thread.

Thanks.

[DNSB]

Originally Posted by slowsmile

DNSB...The way Sigil's file selection works has nothing really to do with the plugin. I'm pretty sure that Sigil selection works whereby the files are stored in an ascending list according to the order of selection(usually top to bottom if you use group selections or random selections). As it stands now the user's selection will collect your filenames from top to bottom in the Book Browser and process them exactly like that in the plugin. I must also admit that I never had any selection problems at all when testing the plugin. Perhaps it might be split file which caused these problems.

Also, as advised in the release notes, you must always select all chapter files from the Book Browser for this plugin to work properly. If your file selection does not include all chapter files then you will probably get differences in formatting and chapter file mis-numbering occurring as errors in the result.

I re-tested with the book that used images for the chapter titles since it recycled chapters numbers for each part. It seems that the first file selected became chapter 1, the next chapter 2 and so forth. Basically, I'm just going to have to select from top to bottom which is my normal procedure. The two file situation is unlikely in a real book but fenceposts are handy test points.

For the heck of it, I ctrl-click selected Chapter 1, 5, 2 ,4 ,3 and the following was generated in toc.ncx:

     <navPoint id="navPoint-3" playOrder="3">
        <navLabel>
          <text>Chapter 1</text>
        </navLabel>
        <content src="Text/part0004.html"/>
      </navPoint>
      <navPoint id="navPoint-4" playOrder="4">
        <navLabel>
          <text>Chapter 3</text>
        </navLabel>
        <content src="Text/part0005.html"/>
      </navPoint>
      <navPoint id="navPoint-5" playOrder="5">
        <navLabel>
          <text>Chapter 5</text>
        </navLabel>
        <content src="Text/part0006.html"/>
      </navPoint>
      <navPoint id="navPoint-6" playOrder="6">
        <navLabel>
          <text>Chapter 4</text>
        </navLabel>
        <content src="Text/part0007.html"/>
      </navPoint>
      <navPoint id="navPoint-7" playOrder="7">
        <navLabel>
          <text>Chapter 2</text>
        </navLabel>
        <content src="Text/part0008.html"/>
      </navPoint>

edit: retested with new plugin version and same result. Also note that once I knew I had to select the chapter files in chapter sequence, the plugin made adding chapter 1 to whatever with class=hidden much easier than my previous workflow.

[DiapDealer]

I'll take a look at how the C++ PluginRunner transfers the selected files to Python bk.selected_iter() function. I know how it logically happens (via a written/read config file), but I won't swear that UI selection order couldn't possibly be relevant to the ultimate iteration order of the files in the plugin. After all... this is the first situation I can think of that the order of the files in selected_iter() would even matter. I'll report back when I know more.

[DiapDealer]

Yep. bk.selected_iter() is definitely populated in the order that files were selected in Book Browser.

[slowsmile]

Thanks for the more detailed explanation(my explanation was just a guess really).

Just to also make the point again that plugin users must always select all chapter files whenever they use this plugin otherwise users are likely to get mismatched chapter styling and incorrect chapter numbering as a result.

[slowsmile]

Plugin Update: The plugin will now automatically save the last settings from both dialogs as default settings(v0.1.3).

[DNSB]

Originally Posted by DiapDealer

Yep. bk.selected_iter() is definitely populated in the order that files were selected in Book Browser.

Good to know that I was not hallucinating and there is a reason for the odd behaviour I noticed.