For most of the last 36 hours I've spent a hell of a lot of time trying various things in Calibre to resolve problems which I became aware of with a recent e-pub. When I made the e-pub for the Clan Amir of Berant anthology a couple of months ago I didn't realise there was an issue in the e-pub created finally got to the point it caused an issue with the e-pub. They all relate to the way Calibre uses the CSS code and changes it.
(NB: I'll add extra space when I list code so that it doesn't run.)
Here are the big issues which I've identified and found a work around:
1. The use of the word 'head' in a style name within the CSS code.
2. The use of a style code with 'head' in it's name within the HTML code of the document.
3. The order in which styles with 'head' it their name or the 'headings' are used in the HTML code of the document.
4. Calibre will frequently make styles which have the same attributes into the one style and use the style name of the first listed in the CSS code.
5. The use of the < br > code in the HTML code of the document.
6. Calibre will change style attribute code to what it thinks it should be and will create new styles as it feels it should.
How they cause problems:
a. Calibre automatically assumes that any style type with the word 'head' in it is a heading style and it automatically assumes any paragraph that uses a style with 'head' in it is a heading.
b. Calibre will reassign heading hierarchy designations as it feels it should.
c. Calibre will delete styles it deems aren't needed.
d. Calibre will create new styles as it decides it needs to. Mind you, it will allow itself to create styles with the same attributes and similar names but often won't let you do that.
3. Calibre will change style attributes to what it thinks they should be.
How to stop the problems happening.
a. There are some Calibre setting that will reduce a lot of this problem. Open Calibre and go to the Preferences then got to Common Options
1. In Look & Feel select Fonts place a 'tick' in the box beside Disable font size rescaling by clicking on the box.
2. set the Minimum line height to 100%.
(These changes will ensure whatever font and line sizes you have in your styles will be used by Calibre instead of being adjusted by Calibre.)
3. In Table of Contents set the ToC levels to use your H1, H2, and H3 headings with the code '/ / h : h 1' etc. adjust the number for the appropriate levels. NB: only set for the number of levels you wish to use or do not use the the third level in your HTML code.
Note: Technically you can set the system to detect and use a H3 above H2 or H1 by adjusting the code here, but doing that may cause some issues.
b. There are changes to the CSS styles that will resolve a lot of the issues.
1. Only use the word 'head' in the name of a style type you intend to use only for headings, and ensure those four letters in that order are not used in any other style name.
2. Only every use the styles with 'head' in their name for the headings in your HTML and match them with the appropriate H1, H2, H3 HTML tags.
3. Ensure all of the attributes of a named style in the CSS code does not match that of another style.
4. The named styles have all the attribute settings have a line-height and have as many attribute as you feel needed to ensure they don't match up with another style.
5. Make the attributions listed for each style as complete as you can.
6. Where you wish to use a style that's the same as for a heading create a new one with a different name and give it a slightly different attribute. (examples later)
7. Where ever you wish to use a < br > create a new style with an attribute of 'padding-top : 0.0 em' and the other attributes to suit what you want to match it to. One style for each different type of usage. (examples later)
If you don't have a style set and named Calibre will create its own and add it to the CSS, and it will create a new style for each split the < br > code appears in.
8. Make sure the first headings you use within the document code are in their hierarchy order. The first use of a heading and heading style after the title should always be H1 with the intended H1 style, then you can use another H1 or a H2 but do not use a H3 until after you've used a H1 then a H2 style headings.
You can go H1, H2, H3, H1 or H1, H1, H1, H2, H2, H1, H2, H3 and all will be well. However, if you go H1, H3, H2 Calibre is likely to adjust the style attribute and names of H3 and H2 on you based on the first usage order. Once each has been used the first time it seems you can then use them in any order - but I'm not 100% positive of this, just it seems that way, so far.
...............
One thing I had done in some stories was to use the same style I use for the H2 heading to have it appear mid-story as a special notice. The difference in how I coded it in the HTML was:
< h2 class = " head2 " > Sub-chapter title < / h2 >
< p class = "head2 " > Notice sign within the story < / p >
The above is valid HTML code and will display as I wish it to. However, Calibre will see the style name and disregard the < p > designation as a normal paragraph. I tried resolving this by copying the 'head2' code and creating a new style named 'notice' but Calibre saw they had the same attributes and merged them, thus recreating the initial problem. I got around this by changing the line-height and font-size for the notice style from 1.6 em to 1.4 em.
Another major change was to rename every style that used 'head' in its name except for 'head,' 'head1,' and 'head2' which are the ones I use for story titles, chapter, titles, and sub-chapter titles. This eliminated the mistake by Calibre in the use of the 'head5' which I use for section headings.
I resolved the issue with the < br > commands by creating new styles for the subsequent lines for each situation in which I used them. Most of the times I used < br > was with poetry and lists I didn't want lines between the lines in. I simple copied the style I used for the first line, gave it a new name to be in the css code below what it relates to and changed the 'padding-top' attribute from 1.0 em to 0.0 em.
Note: After all of these changes the HTML code displayed the same when run as HTML, but it also eliminated all of the problems I noticed in the e-pub Calibre created before I made the changes.
The worst part of this is that I recently updated and reposted my writer guide and I now have to update it to include all of this information.
