Potential Enhancement: Links Report

[Tex2002ans]

Current Functionality

Open the attached sample EPUB with Sigil's Tools > Reports > Links. Double-click on any link:



If you click on any link in Chapter 1, Sigil will jump to the very top of Chapter1.xhtml.

If you click on any link in Chapter 2, Sigil will jump to the very top of Chapter2.xhtml.

(Not very helpful.)

Expected Functionality

Jumping to the link's exact location in the HTML file (see the way Calibre's Editor Tools > Reports > Links handles it).

If you click on "Example Link #3", Calibre jumps directly to the <a> containing "Example Link #3".

Why This Would Be Helpful

I was working on a book with 100+ hyperlinks (a collection of online articles). While Sigil's Links Report is very helpful for spotting general errors (typos, broken links, errors), I had to manually find/search each individual link if there was a problem:

<p>As the fantastic W<a href="http://www.wikipedia.org/">ikipedi</a>a article said.</p>

[KevinH]

I should be able to modify that report to keep track of the line number of the file where the link is located, and then at least move you to the right line in that file without too much dificulty.

The only issue is where in that particular line (the column number) it will be. For normal length lines in CodeView it should be easy to see the link itself. Unfortunately, the current signal design only passes the line number no column or offset info.

Let me see if I can get at least the right line of the file to come up. Would that help?

[BetterRed]

I occasionally edit texts with a lot of links to endnotes, references etc. I never did 'get' what Sigil's Links Report was supposed to do for me, but when Kovid produced his Links report I 'got' it immediately.

I'd have to do a side-by-side comparison to say anything further as its been a while since I've used either. But I do seem to remember I had the impression that Sigil's Links Report was a work-in-progress.

Pssst - I also like calibre's word list, handy for spotting inconsistent spelling, especially of proper nouns, abbreviations, and acronyms. Had a paper from Yale the other day, at least three FIBs that should have been FBIs Deliberate? Don't think so, there were a couple of other valid 'wrong' words that were obvious typos or ignorance (e.g. effect that should have been affect), otherwise it was as dry as moon-dust.

BR

[KevinH]

So is that a "it would help"?

[KevinH]

BTW: I just pushed this change to master. It seems to work quite well with your test epub.
Thanks for your request and test epub to illustrate exactly what you needed.

If moving to the line is not enough, then a more major reworking of Report signals will be needed sometime in the future.

Hope this helps.

[BetterRed]

What would help (assuming it's possible) is a facility to filter by 'link purpose' - i.e. endnotes, references, index entry, toc entry, image reference, etc. My primary concerns are endnotes and references, if the book has an extensive index they tend to get swamped by the index entries. The endnote, reference and index entries in some of my texts span multiple xhtml files.

I have never seen anything in 'Target Text', 'Target's Target File', 'Target's Target ID' or 'Match', including in books where all the links seem to work as I would expect them to work. That observation is where my 'work-in-progress' comment originates.

Would also help if the window had max and min available, and if the window remembered the column sizes last set.

NB: I didn't mean to infer the calibre Links report isn't without it's problems too, only that it seems to be closer to what I want.

BR

[KevinH]

A links purpose (endnote, index, etc) can't actually be determined without additional semantic epub:type info and that would only be in epub3. I can try and determine why the target info is empty. It should not be. The provided testcase has all external links so it did not test that.

Sigil also doesn't need to remember column sizes, as they are auto resized to hold the required info in each column. Sigil should also remember any window sizes set.

I will look to see why the target info is not set for internal link targets in the report. With target file set and sortable you should be able to group/identify index entries from the filename. Possibly endnotes too if they are stored in a recognizable filename or names.

[KevinH]

I checked the code and 'Target Text', 'Target's Target File', 'Target's Target ID' or 'Match' are only filled in when the target of a link is itself an achor tag with a link someplace else (or back).

So that appears to work as designed. I will test this tomorrow and verify that.

[BetterRed]

@KevinH - re filtering by link purpose, I had a feeling that might not be easy, except perhaps via semantic tags, but then I run into the problem that endnotes, references and indexes often span multiple files, I would prefer not to merge them. How about include/excluding by file - then I could exclude the files containing index links.

The problem with the auto sizing the columns is that they seem to auto size to the widest value, when they contain web addresses they can be a mile wide e.g.

http://www.bundesfinanzministerium.de/Content/DE/Standardartikel/hemen/Internationales_Finanzmarkt/Finanzmarktpolitik/2011-02-15-gutachten-bankenbeteiligung-anlage.pdf?__blob=publicationFile&v=3

Another thing I would value is better visibility of the target, i.e. if its an endnote I'd like to see the endnote - in full. Same with a reference, the calibre report gives a truncated value - which isn't much use if there are several references starting with "Dimon, Jamie - On..."

The Links Report is not a major issue for me, I'm happy to take whatever is on offer, and I'm totally agnostic regarding which tools I use, whatever gets the job done at the time... and if it means using two tools, so be it.

BR

[Tex2002ans]

Originally Posted by KevinH

Let me see if I can get at least the right line of the file to come up. Would that help?

Jumping to the correct line is a "good enough" solution (at least for all of the use-cases I could think of). When I noticed Calibre jump directly to the <a> link I just took that as icing on the cake!

The real thing that was making me pull my hair out was Sigil just jumping to the top of the HTML files.

Originally Posted by BetterRed

I occasionally edit texts with a lot of links to endnotes, references etc. I never did 'get' what Sigil's Links Report was supposed to do for me, but when Kovid produced his Links report I 'got' it immediately.

I'd have to do a side-by-side comparison to say anything further as its been a while since I've used either.

Just like the Word List, the Links Report can be used to catch all the inconsistent usages in the <a> tags.

See attached EPUB for all these examples:



Example #1: Take your FBI example, maybe they link throughout the book as:

Spoiler:

<a href="http://fbi.gov/"> FBI.gov</a>
<a href="http://fbi.gov/">FBI.gov </a>
<a href="http://fbi.gov/">FBI.gov</a>
<a href="http://fib.gov/">FBI.gov</a>
<a href="http://fbi.gov/">fbi.gov</a>
<a href="http://fbi.gov/">fib.gov</a>

Spaces very easily creep their way into <a> when using the mouse + WYSWIG editors. These things stand out like a sore thumb when sorted. :P

And a typo (fib.gov) can also easily sneak in the href (this is very hard to spot just looking through the Code View).

Example #2: In the case of this specific book I was working on, there was an article that referenced (Author Year) with a link to the specific book/paper:

Spoiler:

(<a href="http://example.com">Tex 2002</a>)
(<a href="http://example.com">Tex 2002)</a>
<a href="http://example.com">(Tex 2002</a>)
<a href="http://example.com">(Tex 2002)</a>

After sorting, you could see it show up in the list as:

Spoiler:

(Tex 2002
(Tex 2002)
Tex 2002
Tex 2002)

Example #3: It is also very helpful when you do things like changing footnotes from ^## -> [##].

If I sort and see a giant list of:

Spoiler:

4
[1]
[2]
[3]
[5]

I can go take a closer look. That single digit number should not be there!

Example #4: The "Target Exists?" column is also fantastic for catching missing footnotes:

Spoiler:

<p>This is the beginning.<a href="#fn1" id="ft1">[1]</a></p>

<p>And the middle.<a href="Endnotes.xhtml#fn2" id="ft2"><sup>2</sup></a></p>

<p>And this is more middle.<a href="#fn3" id="ft3">[3]</a></p>

<p>And this is the end.<a href="#fn4" id="ft4">[4]</a></p>

<hr/>

<p class="footnote"><a href="#ft1" id="fn1">[1]</a> Footnote #1.</p>
<p class="footnote"><a href="#ft3" id="fn3">[3]</a> Footnote #3.</p>

you can sort "Target Exists?" and see "no" in the column, then you can investigate.

Example #5: You can also sort all the links by "Target File" and take a very close look at external websites.

For example, if there are lots of Youtube links, you may want to check to see if those still exist, what the titles are, etc. etc.

(This particular article pointed to a Youtube Embed link instead of just pointing directly to the normal Youtube video.)

This sort of stuff is EASILY spotted in the Report.

Side Note: Calibre's Links Report also lets you click on the links right there and open them up in your browser. Pretty helpful.

Side Note #2: I don't know when it was added, but Calibre's Tools > External Links > Check External Links is absolutely fantastic for catching HTTP 403/404 Errors.

When you import/work from a collection of web articles it helps you can then go hunting and replacing with newer/working ones (for example, there may be broken Facebook/Twitter links, or a site has updated and hasn't redirected links properly).

Originally Posted by KevinH

I checked the code and 'Target Text', 'Target's Target File', 'Target's Target ID' or 'Match' are only filled in when the target of a link is itself an achor tag with a link someplace else (or back).

So that appears to work as designed. I will test this tomorrow and verify that.

Yep, they work as intended. See attached EPUB. I put together a variety of different links.

Those columns are used if you do something like link to a separate Endnotes file:

Spoiler:

---Chapter01.xhtml---

<p>And the middle.<a href="Endnotes.xhtml#fn2" id="ft2"><sup>2</sup></a></p>

---Endnotes.xhtml---

<h2>End Notes</h2>

<p class="footnote"><a href="Chapter01.xhtml#ft2" id="fn2">[2]</a> Footnote #2.</p>