Add a meaningful title to the HTML file

[flittle8]

Goal:

1. Take the <h1> in a file and move it into the <title> element, replacing the text that currently exists in the Title element (if anything).

[LauraB7]

InDesign's reflex is to populate the <title> element in each HTML file with an iteration of the InDesign file name. It's not meaningful in that it does not describe the content -- i.e., chapter two.

[zwettemaan]

@LauraB7, @flittle8 can you attach some sample files to this GitHub issue? How do you see this working? I can set up a drag/drop tool that would execute this kind of operation, but what would be most useful?

E.g. I can make a drag/drop tool which you'd drag an HTML file on, and it'd find the <h1> and copy it into the <title>

Or I could make a drag/drop tool which you'd drag an EPUB on, and it'd find all HTML inside and perform this operation. This is more effort than the previous option.

I envision you'd probably use this on an 'exploded' EPUB, and use it to manage individual HTML files.

Would it be better to make the tool show a dialog for each HTML file to confirm the title it has selected? That way you can click OK or first edit the title, then click OK.

[LauraB7]

A drag-and-drop tool would definitely do the trick. The key is to wipe out what InDesign populates that field with; i.e., FileName-1, FileName-2, etc. See the attached rough EPUB export for a sample.

9781487006730_EPUB.epub.zip

[zwettemaan]

I've made a first stab at this. It's not satisfactory, but it has some functionality.

To try out on a Mac (I'll document this soon and will then also cover Windows and Linux):

1) Download DropToScript from

https://github.com/BCLibCoop/nnels-a11y-publishing/raw/master/ReleaseVersions/DropToScript.1.0.0.zip

2) Decompress and pick the right version (Mac, Windows, Linux)

3) Go into the folder for your platform, where you see the DropToScript application icon

4) Create a new empty folder 'DropScripts'

5) Right-click and save the following file into this DropScripts folder:

https://raw.githubusercontent.com/BCLibCoop/nnels-a11y-publishing/master/ReleaseVersions/DropScripts/AutoTitle/AutoTitle.php

E.g. on Mac:

6) Drag/drop a bunch of XHTML files on the DropToScript app icon.

[zwettemaan]

More info here:

https://github.com/BCLibCoop/nnels-a11y-publishing/wiki/DropToScript-Documentation

The current AutoTitle.php script is not finished; you'll get some error dialogs on some files, but it is already somewhat useful.

Issues that I found are:

• there is not always a h1
• the h1 sometimes contains nested tags (e.g. a chapter number prefix in a span).

To fix this, I am planning on the following changes:

• Make the AutoTitle try multiple hN tags (h1, if not found use h2, ...)
• If no hN tag found, try with the first p tag. If the text is too long, chop it off
• ignore any subtags (e.g. if I have <h1><span>viii</span>A Nice Chapter</h1> the span would be ignored and the title would be set to A Nice Chapter
• Make the script test whether the title is really the file name, and do nothing if the title is something else. This would be when you already manually changed the title: we don't want the script to overwrite that. Only if the bland file name is used as a title should the script do something.

@LauraB7 I'll do some videos later, once it's all more finished.

[zwettemaan]

Ok, the script should now be smart enough to be useful. Please see the docs

https://github.com/BCLibCoop/nnels-a11y-publishing/blob/master/DropScripts/AutoTitle/AutoTitle.ReadMe.md

https://github.com/BCLibCoop/nnels-a11y-publishing/wiki/DropToScript-Documentation

Quick and dirty video here (3 parts 'DropToScript...')

https://app.box.com/folder/72916582816

[zwettemaan]

Please have a look at:

https://github.com/BCLibCoop/nnels-a11y-publishing/wiki/AutoTitle-Documentation https://github.com/BCLibCoop/nnels-a11y-publishing/wiki/DropToScript-Documentation https://github.com/BCLibCoop/nnels-a11y-publishing/wiki/DropScript-Template-Documentation

[flittle8]

@zwettemaan I downloaded the latest DropToScript release and ran an epub through the AutoTitle however it didn't work (it didn't replace the title element with the top-level headings; no changes were made). Github won't let me attach the HTML file here (unsupported file type) so I've uploaded it to dropbox.

[zwettemaan]

Hi Farrah,

Have you tried setting

"forcedReplaceTitle": 0

in the config.txt file for AutoTitle?

To attach an HTML to a GitHub issue you have to first zip it (compress it). Right-click it on your Mac, and select 'Compress file...'.

[zwettemaan]

In the meantime, I'll have a look at the file... I might have broken something when I added support for whole EPUB files.

[flittle8]

@zwettemaan yes, the "forcedReplaceTitle": 0 is already there

[flittle8]

good to know about zipping HTML files, thanks :)

[zwettemaan]

Oops. I meant to say: try setting forcedReplaceTitle to 1. That disables the test for the file name vs the title.

[flittle8]

@zwettemaan ok, I changed it to 1 and re-ran it. Still no luck. It didn't work on either of these files 41_Chapter_34.html.zip chapter06.xhtml.zip

[zwettemaan]

Cool, thanks for trying. I'll look into it ASAP...

[flittle8]

@zwettemaan I think we need an option here to move the first heading in the file (or first p tag content) into the <title> regardless of filenames. Is that what setting the forcedReplaceTitle to 1 is supposed to allow for?

[flittle8]

@zwettemaan also, on a related note, if you're taking the content of the first p tag we should ensure there is actually content in the p tag. if it's empty then skip to the 1st p tag with text in it. i've noticed that sometimes ebooks have empty p tags at the beginning of the page (I assume the publisher's way of adding extra spacing)

[zwettemaan]

Hi Farrah; I checked the two files and it actually works as designed; it's just that 'as designed' is not very useful in this case. The script needs more thought.

The issue is that both files have nested tags. So, if you edit the config.txt file and set keepTitleSubtags to 1 as well as forcedReplaceTitle, it works, sort of.

Chapter06 finds ' Rain Delay ' and 41_Chapter_34 finds '11'.

Neither substitutions look very useful to me.

At present, I'd say AutoTitle is only useful on InDesign-generated EPUBs. Other EPUBs have too much variability to them, and the odds of the tool picking something silly as a title are too high. E.g. in 41_Chapter_34, 11 is a logical choice for a dumb script that has no comprehension of the text in the document.

[zwettemaan]

The script does not know any better.

[zwettemaan]

Is that what setting the forcedReplaceTitle to 1 is supposed to allow for?

Yes

[zwettemaan]

See

https://github.com/BCLibCoop/nnels-a11y-publishing/blob/master/DropScripts/AutoTitle/AutoTitle.ReadMe.md

[zwettemaan]

also, on a related note, if you're taking the content of the first p tag we should ensure there is actually content in the p tag

Good point. Hadn't considered that yet, but that is easy to fix - I'll add that in.

[flittle8]

@zwettemaan so I set both keepTitleSubtags and forcedReplaceTitle to 1 and it's not working for me... I can email you the EPUB if that helps.

The issue is that both files have nested tags. So, if you edit the config.txt file and set keepTitleSubtags to 1 as well as forcedReplaceTitle, it works, sort of.

Chapter06 finds ' Rain Delay ' and 41_Chapter_34 finds '11'.

[flittle8]

Also, is there a reason why we can't just set the default to ignore nested tags? All tags should be ignored and only text extracted and put into the title

[zwettemaan]

Also, is there a reason why we can't just set the default to ignore nested tags? All tags should be ignored and only text extracted and put into the title

The only reason was that I did not have much test-material to go on, and if I set that flag, the sample Laura provided me came out mangled because it has chapter numbers prefixed to the titles.

I think I'll probably need to refine this so we can tell it to only suppress very specific CSS classes.

[zwettemaan]

Yes, provide me the EPUB. Just to make sure: you are trying the latest version, right? If not, make sure to download it:

https://github.com/BCLibCoop/nnels-a11y-publishing/tree/master/ReleaseVersions

The latest is 1.0.3_1.0.3

[flittle8]

@zwettemaan That's fine if both chapter number and chapter title are in the . The chapter number and title might be styled differently but if both are inside a heading tag then both should be put into the title tag

The only reason was that I did not have much test-material to go on, and if I set that flag, the sample Laura provided me came out mangled because it has chapter numbers prefixed to the titles.

I think I'll probably need to refine this so we can tell it to only suppress very specific CSS classes.

[zwettemaan]

No, it's more complicated than that. I've explained that in the documentation I linked to earlier. If I don't omit the span, the title comes out

iiiMy Chapter

without a space between the title and the number.

So without setting the keepTitleSubtags to 0, Laura's example comes out mangled - i.e. unusable. You'd have to manually go through and add those spaces. The XHTML input from InDesign does not have a space between the number and the title text.

[zwettemaan]

I don't think a default 'works for all' is possible - i.e. we cannot avoid having some config so the user can adjust to the job at hand.

[zwettemaan]

Hi Farrah, the EPUB seems to work for me. I've made a video of what I do and will email it.

[flittle8]

@zwettemaan would it be possible to set a rule where you just replace the tags of any nested tags with a space? We can assume that all nested tags are separating words (or #'s and words).

No, it's more complicated than that. I've explained that in the documentation I linked to earlier. If I don't omit the span, the title comes out

iiiMy Chapter

without a space between the title and the number.

So without setting the keepTitleSubtags to 0, Laura's example comes out mangled - i.e. unusable. You'd have to manually go through and add those spaces. The XHTML input from InDesign does not have a space between the number and the title text.

[flittle8]

@zwettemaan a suggestion, at first I wasn't sure which generated epub was the new and which the old. to be consistent with how individual files are differentiated, could we rename the old ebook with "_old" at the end?

[zwettemaan]

Yes, that is possible, but I am not sure that will always work. E.g. if the first character of something is formatted in a different font, e.g. 'The Title' and the first 'T' is in a different font or has a different style, then there would be a span around that first T, but that first T should not be separated by a space.

E.g.

<p><span class="fancy">T</span>he Title Is here</p>

What I think I need to do is make it flexible through the config file. There are just too many possibilities to try and make a 'catch all'. It will depend on the ebook - e.g. an ebook out of InDesign will need a different treatment than other ebooks. We could have a number of pre-made config files for the most common cases (e.g. always insert a space, don't insert a space) so for basic users it would be a matter of picking a file. More complex use cases would involve a user manually editing a config file to match their exact situation...

[zwettemaan]

Yes, that makes sense. I need to give DropToScript a bit of an overhaul (to show pages processed etc...) and I'll add that in at the same time.

[flittle8]

ah yes... sounds good about having some ready-to-go config options

What I think I need to do is make it flexible through the config file. There are just too many possibilities to try and make a 'catch all'. It will depend on the ebook - e.g. an ebook out of InDesign will need a different treatment than other ebooks. We could have a number of pre-made config files for the most common cases (e.g. always insert a space, don't insert a space) so for basic users it would be a matter of picking a file. More complex use cases would involve a user manually editing a config file to match their exact situation...

[zwettemaan]

Aha. I think I figured it out. El Capitan comes by default with PHP 5.3.8 or so. I found that before version PHP 5.6 a critical feature the AutoTitle.php uses is not supported.

https://www.php.net/manual/en/class.domnode.php#95545

On the PHP I have installed, I can simply do something like

$title->textContent = "some new content";

but for pre-5.6 versions that does not work; it simply silently fails (so none of my normal logging and error trapping is triggered and it simply does not work).

I've now re-written AutoTitle.php to use a workaround that should also work on PHP 5.3.8.

Try the next update...

https://github.com/BCLibCoop/nnels-a11y-publishing/tree/master/ReleaseVersions

The 'inject space' should now also work - i.e. I get '1 Hou Hou le hibou' instead of '1Hou Hou le hibou' with the default AutoTitle.config.txt provided.

[zwettemaan]

@flittle8 Forgot to 'tag' you... I've got another new version to try...

[zwettemaan]

P.S. Note: so the whole idea about accented characters in file paths is moot: it was not that...

[flittle8]

@zwettemaan great, so the script worked, the