Description David J. Orme 2002-02-11 12:33:44 EST

The following thread occurred on the e.tools newsgroup:
--------------
Observations about the online help system:

- It's just HTML
- It uses a real instance of Tomcat to serve the pages
- However, the extension points only provide a way to add static help content.

But why not let me:

- Contribute help as JSP pages or Servlets that are executed by Tomcat just like
other J2EE JSPs or Servlets?


This would provide an easy way to create dynamic help plugins that analyze
source code or analyze databases in real-time without having to run JavaDoc or
something similar to generate more static HTML that could potentially take up a
huge amount of space on my hard disk (depending on the thing being analyzed).

What do you all think?

Dave Orme
Advanced Systems Concepts
http://www.asc-iseries.com

--------------

That's certainly an idea that deserves some investigation.
BTW, we used the term "active help" to refer to the ability of launching
eclipse actions from a help document. That feature has just been implemented
in recent drivers, but not documented yet.
Your notion of "active help" is something new and it looks like it cannot be
done with the current state of the help system, as is. There is hope
though... (see below)
We have the ability to launch any webapp defined in a plugin, and the JSP's
and servlets in that webapp can have access to the eclipse environment
(using the plugin's class loader).
There are two (complementary) ways to make help "active":
1. the toc.xml files containing <topic href="some_servlet_or_some_jsp">
2. dynamically contribute a toc.xml (i.e. the in-memory structure
representing a toc.xml file)
I think you are talking about the first option.

A *partial* solution to what you want would be to define a web app rooted at
the eclipse/plugins level, and basically be able to point help topics to
files (JSP's) in plugins. There is still the question of what those JSP's
could do (i.e. what is the classpath they run with, etc.).

Anyway, this is just a quick thought, but we'll investigate this further.
BTW, have we misunderstood your suggestion?

-Dorian

--------------


Dorian Birsan wrote:
> BTW, we used the term "active help" to refer to the ability of launching
> eclipse actions from a help document. That feature has just been implemented
> in recent drivers, but not documented yet.

Okay, then it seems we need a new term for this.  Hmmmmmmm...  How about "Web
Help" or "HTTP Help" or "Just-in-time help"?

I think I like the last one best.

> We have the ability to launch any webapp defined in a plugin, and the JSP's
> and servlets in that webapp can have access to the eclipse environment
> (using the plugin's class loader).

Cool, this definitely helps.

> There are two (complementary) ways to make help "active":
> 1. the toc.xml files containing <topic href="some_servlet_or_some_jsp">
> 2. dynamically contribute a toc.xml (i.e. the in-memory structure
> representing a toc.xml file)
> I think you are talking about the first option.

Actually, I think both options are important for documentation-tool writers.

(2) is important if you are dynamically generating documentation rather than
using a tool that generates static HTML pages.  If your documentation is
dynamic, your TOC should be too.

(1) is the the form of the entries that you generate in your dynamic "toc.xml"
file enabling individual documentation pages be dynamic.

In other words, some documentation subsystems need to be entirely dynamic--based
upon what project artifacts exist at any instant in time.

> A *partial* solution to what you want would be to define a web app rooted at
> the eclipse/plugins level, and basically be able to point help topics to
> files (JSP's) in plugins. There is still the question of what those JSP's
> could do (i.e. what is the classpath they run with, etc.).

Yes.  It would be very nice for these web apps to have access to anything any
other plugin has access to, including the full Java parse tree, etc...... :-))

> Anyway, this is just a quick thought, but we'll investigate this further.

Cool!

> BTW, have we misunderstood your suggestion?

No, you're exactly on target here.  Since it seems we're on the same page here,
I think I'll put these messages into Bugzilla and we can proceed with the
discussion there.


Best regards,

Dave Orme
Advanced Systems Concepts
http://www.asc-iseries.com