Warning if reference cannot be found

[vogella]

I frequently find that a reference is not working anymore. Would be great if Asciidoctor could (either always or optional) issue a warning for that.

We use a small Gradle extension to fail our documentation builds if a warning is issued.

Would be great if we could avoid having missing cross-references also.

Example:

[[testing]]
== Section 1

== Section 2

See <<testing1>>.

[vogella]

@fap- can you please have a look?

[mojavelinux]

This is all part of the fix I'm working on for #858. Pulling one thread tugs on a whole row of related behaviors.

The reason we aren't warning for invalid xrefs is because we don't yet catalog all the targets (i.e., anchors). We've added some additional ones, but we still have some to go. What we could do in the meantime is report any mismatches when the verbose flag is on. Once we can validate all of them, we can warn even when the verbose flag is not on.

Related: #2257.

[mojavelinux]

Btw, this required some design work because AsciiDoc Python never tracked references at all. So we've had to define what it means to catalog the references so we're in a position to validate them. It's definitely a process.

[mojavelinux]

Here's the line in substitutors.rb where the xref is matched to a ref:

asciidoctor/lib/asciidoctor/substitutors.rb

Lines 1025 to 1034 in 4f78f60

	# handles: id or Section Title
	else
	# resolve fragment as reftext if it's not a known ID and resembles reftext (includes space or has uppercase char)
	if !(@document.catalog[:ids].key? fragment) &&
	((fragment.include? ' ') || fragment.downcase != fragment) &&
	(resolved_id = @document.catalog[:ids].key fragment)
	fragment = resolved_id
	end
	refid, target = fragment, %(##{fragment})
	end

Notice we don't yet validate there. But we could.

[vogella]

Thanks, @mojavelinux for applying the patch and thanks to @fap- for providing the patch. This is very, very helpful to avoid errors in our documentation build.

[mojavelinux]

👍

And this will only get better as we continue to map out more of the reference graph. I'm looking forward to #44, #1918, and #2257, all slated for 1.5.7.

[astubbs]

This doesn't seem to work from the gradle plugin..? I don't get any warnings printed out..

[mojavelinux]

Most reference warnings only show when verbose mode is enabled. I can't remember if this setting is available via the Gradle plugin. I would follow-up there: https://github.com/asciidoctor/asciidoctor-gradle-plugin