OPENNLP-587: Document the Entity Linker framework

[jerry317395616]

Summary

• add a dedicated Entity Linker chapter covering inputs, implementation, configuration, and CLI usage
• clarify that sentence and token spans use document offsets while name spans use sentence-local token indexes
• provide examples that use the actual TokenNameFinder, EntityLinker, LinkedSpan, and BaseLink APIs
• add EntityLinkerManualExamplesTest to keep the offset-conversion example aligned with the API
• link the generated CLI reference to the new chapter and terminate its sample document with a blank line

Validation

• mvn -pl opennlp-api -Dtest=EntityLinkerManualExamplesTest test — 1 test, 0 failures
• mvn -pl opennlp-api verify — 287 tests, 0 failures, 0 errors; Checkstyle and RAT passed
• validated entitylinker.xml against the OASIS DocBook 5.0 DTD
• mvn -pl opennlp-docs -P!doc-manual-html,!doc-manual-pdf -DskipTests package
• extracted the Java examples into a real class and compiled them with JDK 21 against opennlp-api and opennlp-runtime
• the previous GitHub Actions build generated opennlp.html, opennlp.pdf, and opennlp.fo; all six OS/JDK matrix builds passed

Local DocBook generation under this checkout path is affected by docbkx 2.0.17 interpreting the Windows drive letter as a URL protocol. The Linux CI generation completed successfully and validated the generated documentation path.

[mawiesne]

NOTE

Needs checks for correct DTD in new xml file and generated output validaten.

[jerry317395616]

Checked both points. The new chapter uses -//OASIS//DTD DocBook XML 5.0//EN and http://docbook.org/xml/5.0/dtd/docbook.dtd, which are the public and system identifiers listed in the official OASIS DocBook 5.0 catalog and match the other chapters. I also validated entitylinker.xml against the OASIS DocBook 5.0 DTD. The successful CI build generated opennlp.html, opennlp.pdf, and opennlp.fo; all six OS/JDK matrix builds passed.

[krickert]

This is a useful addition, thank you for documenting an API that has been hard to discover.

One small request before merge: could you add a focused test that exercises the Java example in this chapter? The docs build renders programlisting blocks but does not compile them, so a small EntityLinkerManualExamplesTest would keep the example aligned with the API over time. It does not need a real gazetteer, just a tiny in-memory linker and assertions that the name-span token indexes become document character offsets correctly.

Separately, while reading the CLI implementation I noticed it only processes a document when it sees a blank line, so the final document is skipped if input ends at EOF. That behavior predates this PR, so I do not want to expand your documentation change unnecessarily. If you would like to take it on, the shape is simply:

if (!document.isEmpty()) {
  processDocument(entityLinker, document, perfMon);
}

after the input loop, with the existing blank-line processing moved into processDocument(...). Otherwise, a small follow-up issue or PR is fine.

If you need any help with this, let me know! I'll be glad to guide you through it.

[jerry317395616]

Thanks for the focused suggestion. I added EntityLinkerManualExamplesTest in the API module. It runs the chapter's conversion flow over two sentences with an in-memory linker and verifies that sentence-local name token indexes produce the document offsets for Paris (6-11) and New York (17-25), along with the sentence IDs, search terms, and linked record IDs. The focused test passes, and mvn -pl opennlp-api verify passes all 287 tests plus Checkstyle and RAT. I kept the pre-existing CLI EOF behavior outside this documentation PR and added the trailing blank line to the CLI sample.

[krickert]

Thank you for turning this around so quickly. The focused example test is exactly what we needed, and keeping the CLI behavior note scoped to the documentation was a good judgment call.

This is a solid contribution and I appreciate how constructively you engaged with the review. Please keep contributing, and always feel free to ask questions if anything about the codebase, tests, or review feedback is unclear.