| contributing help [message #65641] |
Fri, 06 June 2003 11:16  |
Eclipse User |
|
|
|
We have written a plugin for our programming language. Now we would
like to include documentation for it. We have hit a few problems.
We would like to rely on Eclipse documentation for providing help on
core plugins like the debug view. It is a waste of effort for us to
duplicate the documentation of generic components, and it is
impossible to guarantee that our docs would be for the correct version
of Eclipse as someone can run different versions of our plugin with
different versions of Eclipse.
The strange thing is that the debug view is documented by
org.eclipse.jdt.doc.user. Why are generic components part of the JDT
docs? This is unfortunate because it means that our users will have to
read JDT documentation in addition to the documentation for our
language. This JDT documentation talks about generic issues (e.g. step
into) and JDT specific issues (e.g. step with filters). So to a new
user who is trying to learn about the debug view, it is not even clear
what is JDT-specific and what is generic to the view.
Does anybody have ideas or experiences on how to go about integrating
documentation in a workable way? Are there any planned enhancements to
the documentation infrastructure? Are there any plan to refactor the
documentation so that the generic views will have their own docs?
In an post to this news group called 'Scope of Actions' (May 5, 2003),
I discussed what really amounts to the same issues, but for action
contributions instead of documentation contributions. I think the same
approach would work for documentation. The idea is that on a per
perspective basis, the user would have the ability to customise which
doc contributions to show or hide (as can be currently done like with
action sets). Then we could create custom debug and editing
perspectives and initialize them to show the generic docs and our
docs. The JDT docs would not show up by default (but users, of course,
are free to customise any perpspective any way the see fit). This is a
long term solution since is requires enhancements to how perspectives
work, and it requires a refactoring of the docs which are currently
part of a JDT plugin.
It is straight forward to get a plugin up and going. But when it comes
down to trying to prepare a polished release, co-exisitance issues
block the way. I think that better use of perspectives is the key to
providing proper co-existance of plugins.
- Patrick
|
|
|
| Re: contributing help [message #66008 is a reply to message #65641] |
Fri, 06 June 2003 17:40  |
| Eclipse User |
|
|
|
Originally posted by: birsan.nospam.ca.ibm.com
Patrick, you raise a number of very valid points.
The eclipse help system supports pluggable documentation and the ability to
link up various sections. However, as you noticed, the current docs were
done in a fairly monolithical fashion.
There is a deferred plan item in 3.0 to fix this, so feel free to cc:
yourself to the bug and maybe contribute to it:
https://bugs.eclipse.org/bugs/show_bug.cgi?id=36964
-Dorian
"Patrick Baker" <pbaker@ca.stilo.com> wrote in message
news:bbqb95$b5m$1@rogue.oti.com...
> We have written a plugin for our programming language. Now we would
> like to include documentation for it. We have hit a few problems.
>
> We would like to rely on Eclipse documentation for providing help on
> core plugins like the debug view. It is a waste of effort for us to
> duplicate the documentation of generic components, and it is
> impossible to guarantee that our docs would be for the correct version
> of Eclipse as someone can run different versions of our plugin with
> different versions of Eclipse.
>
> The strange thing is that the debug view is documented by
> org.eclipse.jdt.doc.user. Why are generic components part of the JDT
> docs? This is unfortunate because it means that our users will have to
> read JDT documentation in addition to the documentation for our
> language. This JDT documentation talks about generic issues (e.g. step
> into) and JDT specific issues (e.g. step with filters). So to a new
> user who is trying to learn about the debug view, it is not even clear
> what is JDT-specific and what is generic to the view.
>
> Does anybody have ideas or experiences on how to go about integrating
> documentation in a workable way? Are there any planned enhancements to
> the documentation infrastructure? Are there any plan to refactor the
> documentation so that the generic views will have their own docs?
>
> In an post to this news group called 'Scope of Actions' (May 5, 2003),
> I discussed what really amounts to the same issues, but for action
> contributions instead of documentation contributions. I think the same
> approach would work for documentation. The idea is that on a per
> perspective basis, the user would have the ability to customise which
> doc contributions to show or hide (as can be currently done like with
> action sets). Then we could create custom debug and editing
> perspectives and initialize them to show the generic docs and our
> docs. The JDT docs would not show up by default (but users, of course,
> are free to customise any perpspective any way the see fit). This is a
> long term solution since is requires enhancements to how perspectives
> work, and it requires a refactoring of the docs which are currently
> part of a JDT plugin.
>
> It is straight forward to get a plugin up and going. But when it comes
> down to trying to prepare a polished release, co-exisitance issues
> block the way. I think that better use of perspectives is the key to
> providing proper co-existance of plugins.
>
> - Patrick
>
>
|
|
|
Powered by
FUDForum. Page generated in 0.03000 seconds
Home