[Plugin] LogicalTOCStyler

[slowsmile]

Changes the styling of the Logical TOC(Device TOC)

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

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 LogicalTOCStyler _vXXX.zip. This will load and install the plugin into Sigil, which you can then select and run the plugin by selecting Plugins > Edit > LogicalTOCStyler

Description
This plugin allows the user to quickly and safely re-style the Logical TOC in titlecase/uppercase without the user going near the toc.ncx file. This simple plugin just reformats the Logical TOC according to the needs of the plugin user.

This plugin will also convert to proper titlecase headings in the toc.ncx file. This means that words like "and", "the", "in", "on", "from" etc. will remain in lower case in all titlecased headings after conversion. See titlecase_exclude_list in Using Preferences for more details.(added in v0.1.1)

User Options(via dialog)

* Convert all headings to titlecase

* Convert all headings to uppercase

* Convert only chapter headings to uppercase

* Convert only user-defined headings to uppercase (set in plugin prefs -- see Using Preferences)

* Default prefs reset -- Resets the user-defined heading list back to the original default list.

Using Preferences
You can use prefs for this plugin in Sigil by going to Plugins > Manage Plugins > Open Preferences Location > plugin_prefs > LogicalTOCStyler > LogicalTOCStyler.json.

user_defined_search_list
The default user-defined settings in the json file are shown below:

user_defined_search_list: [

"preface",
"introduction",
"foreword",
"epigraph",
"prologue",
"chapter",
"epilogue",
"Index"

]

The user can add or remove headings to and from this search list as preferred. Additional headings should always be added in lowercase. If any of the above headings in the heading list are found in your Logical TOC then they will be formatted in uppercase. Any headings not included in the search list will all be formatted in titlecase.

titlecase_exclude_list(added in v0.1.1)
This is a default list of words like "and", "in", "on", "from" etc(in plugin prefs) that will always remain in lowercase whenever headings are titlecased. Users can also add or remove words to or from this list as they prefer in order to ensure that "proper" titlecase is implemented for all headings in the Logical TOC. So if you want a word excluded from titlecase that isn't already in the default list -- then you can just add it to this list(in lowercase) in plugin prefs and it will stay in lowercase. The default list in plugin prefs is shown here:

"titlecase_exclude_list": [

"the",
"a",
"an",
"at",
"of",
"with",
"to",
"and",
"on",
"by",
"for",
"in",
"from"

]

Plugin Run
First load your epub into Sigil and then just run this plugin. Users can also run this plugin multiple times on the same epub if they want. After running this plugin users can then easily check and verify the new heading format within the toc.ncx file using html view.

Changes;

Spoiler:

v0.1.0

-- Initial Release

v0.1.1

-- Proper titlecase has been implemented(See Using Preferences). Thanks to AlanHK.
-- Fixed apostrophe problem.

[AlanHK]

Thanks. Will be handy.

However..."titlecase" simply capitalises every word.
Title case normally leaves some words:

Articles (a, an, the)
Conjunctions (e.g., and, but, or)
Prepositions (e.g., on, in, with)

in lower case (except at beginning).

If that seems too much hassle, maybe just rename your option "Capitalise".

See e.g :
http://www.grammar-monster.com/lesso...title_case.htm
http://blog.apastyle.org/apastyle/20...apa-style.html
https://saijogeorge.com/title-case-converter/ seems accurate

PS -- also found some anomalies: it will convert
"CHAPTER XVII–FINDS PRINT OF MAN’S FOOT ON THE SAND" to
"Chapter Xvii—Finds Print Of Man’S Foot On The Sand"
which I need to make several manual changes to make it true title case:
"Chapter XVII—Finds Print of Man’s Foot on the Sand".
The capital after an apostrophe is wrong even for simple capitalising.

[slowsmile]

AlanHK...I hear what you are saying but, in terms of coding, you are actually asking for quite alot. Nevertheless, I am currently testing a mod for this plugin where I have implemented an exclusion list of words for titlecase headings only. Any word in this list will automatically be converted to lowercase for titlecase headings only. The list is only comprehensive or rudimentary but, because I've implemented the list in plugin prefs, users should be easily able to add or remove words to this exclusion list as they prefer. The upgrade should hopefully be ready in a day or two. I must also add that this mod probably isn't going to be perfect but it's as far as I am willing or able to go with your "proper" titlecase issue.

[AlanHK]

Originally Posted by slowsmile

an exclusion list of words for titlecase headings only. Any word in this list will automatically be converted to lowercase for titlecase headings only.

OK, thanks.
Also note the bug of letter after an apostrophe.

While roman numerals might seem a bit obscure, in chapter titles they are very common so consider those too.

[slowsmile]

My plugin update only does a word by word comparison for titlecase headings only. Any words that it finds in the list will be converted to lower case. That's all it does. It will not fix specific cases like you mention above. If you think about it, there are probably hundreds of specific titlecase instances where this plugin wont work for titlecase. Sorry, but I'm not willing to fix orinclude every possible instance of a "proper" titlecase problem that could arise. I really don't have the time or inclination to go that far because this plugin is specfically about formatting the Logical TOC and is not about specifically fixing or formatting titlecase in a particular way.

[slowsmile]

Duplicate

[AlanHK]

OK. My comment was that "Titlecase" is not what a book editor would expect, so would be better under a more descriptive name if you aren't actually doing that.

However, I think cap after apostrophe should be considered a bug.

[slowsmile]

Update: The plugin has been updated with new functionality in v0.1.1:

* The plugin now implements "proper" titlecase where words like "and", "the", "or", "on", "in" etc will remain in lowercase whenever headings are titlecased. To this end I've also implemented a default titlecase_exclusion_list in plugin prefs so that plugin users can also add or remove words from this list as they prefer. So if you want a word excluded from titlecase that isn't already in the default list -- then just add it to this list and it will remain in lowercase.

* The plugin will now correctly format apostrophe's like "don't", "won't", "John's" and "'Tis".

For more details on these changes please read Using Preferences.

[AlanHK]

Originally Posted by slowsmile

Update: The plugin has been updated with new functionality in v0.1.1:

Thanks.
At the risk of seeming greedy, the exclusion list is for words that should be lower case. How about including words that should always be upper case: eg acronyms, Roman numerals? So I can add FBI, NASA, XIV, etc to it.

[slowsmile]

Sorry but your further request for things like maintaining roman numerals and acronyms in allcaps within titlecased headings is a straight no.

The reason I'm not going to fulfill that request is because I recently tested your heading shown here:

CHAPTER XVII–FINDS PRINT OF MAN’S FOOT ON THE SAND

...using four online titlecase converters and they all gave the following conversion:

Chapter Xvii – Finds print of Man's Foot on the Sand

Your roman numeral request really requires two things that are difficult to achieve:

* Convert the heading to "proper" titlecase

* But also maintain differing roman numeral combinations or acronyms as allcaps in all titlecased headings.

And that's why I regard this request as completely unrealistic.

Regarding acronyms -- do you really think it's reasonable to expect this plugin to be able to guarantee that all English acronyms used by all indie authors be maintained as a list on this plugin? Get real !!

So for acronyms or allcap abbreviations as well as roman numerals as allcaps within titlecase headings are both a no I'm afraid. You also appear to be using en dash or em dash in your Logical TOC titles which is also quite dangerous(UNICODE not ASCII ???).

[AlanHK]

Originally Posted by slowsmile

So for acronyms or allcap abbreviations as well as roman numerals as allcaps within titlecase headings are both a no I'm afraid.

I didn't ask you to determine if any given string is an acronym. That is obviously impossible.

What I meant was that your exclusion list could be not just words that should be in lower case; but made more general, so that words in the list did not have their case changed. So adding a word in all caps (e.g. acronyms, Roman numerals) means it would not be lowercased.
So I could, e.g., include the first 100 Roman numerals myself if I wanted to protect them.
Or have a separate all caps list if that's easier to do.

Originally Posted by slowsmile

You also appear to be using en dash or em dash in your Logical TOC titles which is also quite dangerous(UNICODE not ASCII ???).

Actually, those were from a Library Gutenberg edition of Robinson Crusoe; so while ugly, it was surely syntactically correct. And it tested OK with ePubCheck.
Also, that's how Sigil would generate them if you used dashes in the chapter heads.

While your tool only affects the logical TOC, that is used to generate the HTML TOC (which this book didn't have as I got it), and if it's correct grammatically it makes the TOC page right without further tweaking.
That's why I was using this as while having each chapter title as all caps looks OK individually, all together on a TOC page they are pretty ugly.

[slowsmile]

AlanHK said:

What I meant was that your exclusion list could be not just words that should be in lower case; but made more general, so that words in the list did not have their case changed. So adding a word in ALL CAPS (e.g. acronyms, Roman numerals) means it would not be lowercased.
So I could, e.g., include the first 100 Roman numerals myself if I wanted to protect them.

If I tried to fulfil your requests I would either have to create separate large lists for roman numerals and acronyms or create extra dialogs to gather that information from the user or create two more plugin prefs entries. Any way you look at this, doing that would make the plugin code more complicated and make the plugin much more difficult to use. My policy has always been to make all my plugins as simple as possible to use to allow as many people as possible to easily use the plugin. But if I also implemented the changes you request for acronyms and roman numerals this might well make the plugin less usable for the average plugin user.

As far as I'm concerned the current plugin should now satisfy the needs of the average user who uses standard headings like "Chapter 1" or "CHAPTER 12" or "Chapter Six" or "Across the Dark Street"etc. I cannot possibly satisfy every request from people who use highly individual, non-standard headings that contain acronyms as well as roman numerals in allcaps within titlecased headings.

While your tool only affects the logical TOC, that is used to generate the HTML TOC (which this book didn't have as I got it), and if it's correct grammatically it makes the TOC page right without further tweaking.
That's why I was using this as while having each chapter title as all caps looks OK individually, all together on a TOC page they are pretty ugly.

My LogicalTOCStyler should really do nothing to the HTML TOC or docTOC in the epub(TOC.xhtml). It's only used to style the Logical TOC in the toc.ncx and that's all.

If the TOC pages look ugly then perhaps you could change the TOC page styling to a more standard format for a better look.

Still a no I'm afraid.

[AlanHK]

Originally Posted by slowsmile

If I tried to fulfil your requests I would either have to create separate large lists for roman numerals and acronyms or create extra dialogs to gather that information

Again, I did not ask you to create a list.
It was your idea to include an exclusion list the user could maintain.
No new dialog woud be needed.

Originally Posted by slowsmile

My LogicalTOCStyler should really do nothing to the HTML TOC or docTOC in the epub(TOC.xhtml). It's only used to style the Logical TOC in the toc.ncx and that's all.

If the TOC pages look ugly then perhaps you could always change the TOC page styling to a more standard format for a better look.

You aren't familiar with the Sigil tool "Create HTML table of contents" that converts the logical TOC to HTML?

Its not hard to edit the HTML, but a lot less hassle to have the logical TOC right first.

When I said "ugly" I was not referring to the CSS, which I always adjust (I have been doing DTP for about 25 years) but the look of page in all caps. A headline in all caps can work, but a page of all caps is a mess. Same as an entire page in bold.

[slowsmile]

You aren't familiar with the Sigil tool "Create HTML table of contents" that converts the logical TOC to HTML?

Yes I am familiar with the Create TOC tool. Why do you ask? This feature also allows you to style the Logical TOC how you like in Sigil.

Its not hard to edit the HTML, but a lot less hassle to have the logical TOC right first.

It's certainly true what you say. But the problem is you are now being greedy -- you want or ask for too much. As I've said, requesting that the LogicalTOCStyler plugin style your headings as "proper" titlecase is OK. But then when you further insist(yes, insist) that the plugin code should also allow roman numerals or acronyms in allcaps within the titlecase then, in my opinion, that's when your request becomes wildly unrealistic and unreasonable.

I'm also not going to change my mind on this.