[
https://issues.apache.org/jira/browse/CAMEL-25714?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Claus Ibsen updated CAMEL-25714:
--------------------------------
Description:
CAMEL-25541 gave the component answer of {{camel_catalog_doc}} the titles of
the page sections ({{sections}}), and {{docPage=<section title>}} returns one
section. An agent has to pick a section from its title alone, and many titles
say little about what the section holds: the doc pages under {{components/}}
(590) have about 5,000 {{==}} to {{====}} headings, and the most common titles
are *Usage* (311 pages) and *Examples* (244). Usage is often the catch-all that
holds what decides correctness, such as the mail {{useHeader*}} options.
h3. Proposal
* Let an AI go over every section of the doc pages and write a one-line summary
of what the section holds, stored in the .adoc as a named attribute on the line
above the heading:
{code}
[summary="TLS for imaps, pop3s and smtps: sslContextParameters, or JavaMail
properties for STARTTLS"]
=== SSL support
{code}
** Asciidoctor keeps an unknown named attribute on the section and renders
nothing, so the website does not change.
** It sets no id, so the generated id ({{_ssl_support}}) and the xrefs to it
keep working, unlike an explicit anchor before the heading.
** It moves with the heading when a section is renamed or moved, and it reaches
the catalog copy of the page that {{camel_catalog_doc}} reads.
** One line, in double quotes (summaries have commas); a quote inside is
written as backslash and quote.
* {{camel_catalog_doc}} returns the summary with each section title. When a
section has no summary, the first sentence of its text is the fallback.
* Keep the summaries true: store a short hash of the section text with the
summary (for example {{summary-hash=...}}), so a changed section can be told
from an unchanged one and only the changed ones are summarized again.
* A report, from a script or a goal of the camel-package-maven-plugin: per page
and in total, how many sections have no summary and how many summaries are
stale (the section text no longer matches the hash). It tells how far the AI
pass has got and which sections it should do next. It reports and does not fail
the build, so a doc fix does not break it.
h3. Also
* Return the parent of each section (the list is flat today: _Using the JSSE
Configuration Utility_ does not say it is part of _SSL support_) and its size,
so an agent knows what a {{docPage}} call will cost.
* Fit the 16,000 character cap of the answer: 40 sections with a 100 character
summary are 4,000 characters, so the summaries may go only with the sections
that rank first, or come from a table of contents call.
* Rank the sections by the agent's question, not only by a substring of
{{optionsFilter}}.
* Small fixes: 28 headings use the closing form ({{=== Legacy ===}}) and the
title keeps the trailing equal signs; 13 titles keep the doctitle attribute
unresolved ("doctitle components").
* Measure the effect with the agent benchmark: does the agent pick the section
with the xslt header parameters, the mail {{useHeader*}} options, or
{{camel.server.*}} for platform-http.
Start with the component pages; the EIP, language, data format and user manual
pages can follow.
_Claude Code on behalf of davsclaus_
was:
CAMEL-25541 gave the component answer of {{camel_catalog_doc}} the titles of
the page sections ({{sections}}), and {{docPage=<section title>}} returns one
section. An agent has to pick a section from its title alone, and many titles
say little about what the section holds: the doc pages under {{components/}}
(590) have about 5,000 {{==}} to {{====}} headings, and the most common titles
are *Usage* (311 pages) and *Examples* (244). Usage is often the catch-all that
holds what decides correctness, such as the mail {{useHeader*}} options.
h3. Proposal
* Let an AI go over every section of the doc pages and write a one-line summary
of what the section holds, stored in the .adoc as a named attribute on the line
above the heading:
{code}
[summary="TLS for imaps, pop3s and smtps: sslContextParameters, or JavaMail
properties for STARTTLS"]
=== SSL support
{code}
** Asciidoctor keeps an unknown named attribute on the section and renders
nothing, so the website does not change.
** It sets no id, so the generated id ({{_ssl_support}}) and the xrefs to it
keep working, unlike an explicit anchor before the heading.
** It moves with the heading when a section is renamed or moved, and it reaches
the catalog copy of the page that {{camel_catalog_doc}} reads.
** One line, in double quotes (summaries have commas); a quote inside is
written as backslash and quote.
* {{camel_catalog_doc}} returns the summary with each section title. When a
section has no summary, the first sentence of its text is the fallback.
* Keep the summaries true: store a short hash of the section text with the
summary (for example {{summary-hash=...}}), and let a build check report the
sections whose text changed since, so only those are summarized again. The
check reports and does not fail, so a doc fix does not break the build.
h3. Also
* Return the parent of each section (the list is flat today: _Using the JSSE
Configuration Utility_ does not say it is part of _SSL support_) and its size,
so an agent knows what a {{docPage}} call will cost.
* Fit the 16,000 character cap of the answer: 40 sections with a 100 character
summary are 4,000 characters, so the summaries may go only with the sections
that rank first, or come from a table of contents call.
* Rank the sections by the agent's question, not only by a substring of
{{optionsFilter}}.
* Small fixes: 28 headings use the closing form ({{=== Legacy ===}}) and the
title keeps the trailing equal signs; 13 titles keep the doctitle attribute
unresolved ("doctitle components").
* Measure the effect with the agent benchmark: does the agent pick the section
with the xslt header parameters, the mail {{useHeader*}} options, or
{{camel.server.*}} for platform-http.
Start with the component pages; the EIP, language, data format and user manual
pages can follow.
_Claude Code on behalf of davsclaus_
> camel-jbang-mcp - camel_catalog_doc: a summary for each doc section, so an
> agent can tell which section to read
> ---------------------------------------------------------------------------------------------------------------
>
> Key: CAMEL-25714
> URL: https://issues.apache.org/jira/browse/CAMEL-25714
> Project: Camel
> Issue Type: Improvement
> Components: camel-jbang-mcp
> Reporter: Claus Ibsen
> Priority: Major
> Fix For: 4.24.0
>
>
> CAMEL-25541 gave the component answer of {{camel_catalog_doc}} the titles of
> the page sections ({{sections}}), and {{docPage=<section title>}} returns one
> section. An agent has to pick a section from its title alone, and many titles
> say little about what the section holds: the doc pages under {{components/}}
> (590) have about 5,000 {{==}} to {{====}} headings, and the most common
> titles are *Usage* (311 pages) and *Examples* (244). Usage is often the
> catch-all that holds what decides correctness, such as the mail
> {{useHeader*}} options.
> h3. Proposal
> * Let an AI go over every section of the doc pages and write a one-line
> summary of what the section holds, stored in the .adoc as a named attribute
> on the line above the heading:
> {code}
> [summary="TLS for imaps, pop3s and smtps: sslContextParameters, or JavaMail
> properties for STARTTLS"]
> === SSL support
> {code}
> ** Asciidoctor keeps an unknown named attribute on the section and renders
> nothing, so the website does not change.
> ** It sets no id, so the generated id ({{_ssl_support}}) and the xrefs to it
> keep working, unlike an explicit anchor before the heading.
> ** It moves with the heading when a section is renamed or moved, and it
> reaches the catalog copy of the page that {{camel_catalog_doc}} reads.
> ** One line, in double quotes (summaries have commas); a quote inside is
> written as backslash and quote.
> * {{camel_catalog_doc}} returns the summary with each section title. When a
> section has no summary, the first sentence of its text is the fallback.
> * Keep the summaries true: store a short hash of the section text with the
> summary (for example {{summary-hash=...}}), so a changed section can be told
> from an unchanged one and only the changed ones are summarized again.
> * A report, from a script or a goal of the camel-package-maven-plugin: per
> page and in total, how many sections have no summary and how many summaries
> are stale (the section text no longer matches the hash). It tells how far the
> AI pass has got and which sections it should do next. It reports and does not
> fail the build, so a doc fix does not break it.
> h3. Also
> * Return the parent of each section (the list is flat today: _Using the JSSE
> Configuration Utility_ does not say it is part of _SSL support_) and its
> size, so an agent knows what a {{docPage}} call will cost.
> * Fit the 16,000 character cap of the answer: 40 sections with a 100
> character summary are 4,000 characters, so the summaries may go only with the
> sections that rank first, or come from a table of contents call.
> * Rank the sections by the agent's question, not only by a substring of
> {{optionsFilter}}.
> * Small fixes: 28 headings use the closing form ({{=== Legacy ===}}) and the
> title keeps the trailing equal signs; 13 titles keep the doctitle attribute
> unresolved ("doctitle components").
> * Measure the effect with the agent benchmark: does the agent pick the
> section with the xslt header parameters, the mail {{useHeader*}} options, or
> {{camel.server.*}} for platform-http.
> Start with the component pages; the EIP, language, data format and user
> manual pages can follow.
> _Claude Code on behalf of davsclaus_
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
