# Implementieren einer Help-Seite



## dzim (1. Apr 2009)

Ein Projekt von mir soll demnächst auch von Nicht-Entwicklern verwendet werden. Problem: Es war ursprünglich für mich geschrieben, ich finde es recht simpel, aber da ich es entwickelt hab, ist das wohl verständlich.
Mittlerweile ist mir auch klar geworden, dass andere - nicht-Entwickler insbesondere - damit ein paar Startschwierigkeiten haben könnten.
Ich dachte da an eine Online Hilfe wie unter Eclipse "Help" -> "Help Contents", was genau muss ich beachten? Soweit ich weiß, gibt es ein Frameowork dazu... Aber wie wird es verwendet? Gibt es irgendwo gute Tutorials?


----------



## noisebreath (1. Apr 2009)

Grundsätzlich würde ich mir angewöhnen die Kommentare gleich so zu schreiben, dass du Javadocs erstellen kannst, aber ansonsten würde ich einfach eine Readme schreiben. Geh einfach alle funktionalitäten deines Programms durch und überleg dir was man ausser der Bedienungsanleitung für die spezifische funktionalität noch beachten muss. Gibt es Vorraussetzungen unter denen der Menüpunkt nicht auswählbar ist (zb Internetconnection falsch konfiguriert [vpn] oder sonstwas) etc


----------



## Wolfgang Lenhard (1. Apr 2009)

JavaHelp ist eigentlich recht einfach zu verwenden und nicht schwer zu entwickeln.  Wenn man keine durchsuchbare Hilfe braucht, dann ist es geradezu ein Kinderspiel (siehe z. B. Elie Levy's Blog: Help? Yes, you can use JavaHelp! ). Man braucht neben den Hilfedateien (HTML) einfach nur drei Dateien und muss das Helpset schließlich einbinden. Man kann auch kontextsensitiv direkt zu einer bestimmten Stelle springen und somit auch Tooltips aus der Hilfe in die Anwendung einbauen etc.
Hübscher ist natürlich EclipseHelp, das ich persönlich aber nicht zum Laufen gebracht habe, da ich keine Tutorials gefunden haben. Vielleicht bin ich auch einfach zu blind ...


----------



## dzim (1. Apr 2009)

Naja, es soll ja schon etwas "anspruchsvoller" als eine Readme-Datei sein. Javadocs sind imo auch nur für andere Entwickler interessant, denn die Nicht-Entwickler haben damit nichts zu tun und müssen das ja nicht sehen.
Ich dachte halt nur, das es direkt in der Eclipse-API was gibt, was man für eine solche Online Hilfe verwenden kann.
Letzten Endes sind die einzelnen Seiten html, aber die Verlinkung ist ja doch etwas anders...

edit:
Ich würde EclipseHelp oder wie auch immer deswegen vorziehen, weil ich jetzt in einer SWT-GUI nicht mit Swing anfangen möchte... Auch wen das ginge...


----------



## Wildcard (1. Apr 2009)

Eclipse Help ist Java Help deutlich überlegen und solltest du unbedingt auch verwenden.
Einfach das org.eclipse.help Bundle als Dependency angeben, dann kannst du diverse Extension Points verwenden um zB TOC, index,... anzugeben. Danach kannst du dich um die anderen Dinge wie Context Sensitive Hilfe kümmern. Ist eigentlich alles Straight Forward, bei Problemen, frag nach.


----------



## Wolfgang Lenhard (2. Apr 2009)

Hi Wildcard,
welche jars benötigt man genau dafür? Ich habe in der Eclipse-Installation einige, die in Frage kommen:
org.eclipse.help.appserver_3.1.300.v20080507.jar
org.eclipse.help.base_3.3.100.v20080617.jar
org.eclipse.help.ui_3.3.100.v20080521.jar
org.eclipse.help.webapp_3.3.100.v20080528.jar
org.eclipse.help_3.3.100.v20080610.jar

Ciao,
  Wolfgang


----------



## Wildcard (2. Apr 2009)

jars? Ist das kein PlugIn Projekt? Wenn es ein PlugIn Projekt ist, dann einfach im Manifest bei required bundles org.eclipse.help eintragen.
Wenn es kein PlugIn Projekt ist, musst du standalone help verwenden. Das ist etwas komplizierter, aber in der Eclipse Hilfe beschrieben.


----------



## Wolfgang Lenhard (3. Apr 2009)

Danke. Ja, standalone zum Einbetten in eine eigenständige Applikation. Hier gibt es Infos: Help - Eclipse SDK. Ich glaube aber nicht, dass die zusätzliche Funktionalität die enorme (Mehr-)Größe im Vergleich zu JavaHelp rechtfertigt, auch wenn ich nicht herausgekommen habe, wie groß die Standalone-Version konkret ist.


----------



## Wildcard (3. Apr 2009)

Ok, dann hatte ich dich falsch verstanden und du bist im falschen Forum. Ich verschiebe das mal.


----------



## dzim (6. Apr 2009)

Hi folks,

Danke für den Hinweis mit dem Bundle org.eclipse.help.
Eigentlich gehört dieses Thema definitiv in die Plattformprogrammierung, das es bei mir um eine mittels Eclipse-API (was jetzt mal den kompletten Rahmen bezeichnen soll) programmierte Anwendung handelt. Eindeutig Eclipse-RCP und damit in die Platformprogrammierung gehörend...

So oder so werde ich bei Fragen mich an dich wenden @Wildcard.
Danke im voraus schon mal!

VG


----------



## dzim (6. Apr 2009)

Zwei Fragen hab ich da mal:
1) welche der vielen Extension Points sind für mich sinnvoll, wenn ich in meine RCP eine Help-Menü hinzufügen will?
2) welche Plugins muss ich für den build im product file angeben? - Wahrscheinlich die ganzen Webapp-Plugins nicht...


----------



## Wildcard (6. Apr 2009)

*sigh*, also doch ein PlugIn Projekt? Dann schieb ich das zurück.


> 1) welche der vielen Extension Points sind für mich sinnvoll, wenn ich in meine RCP eine Help-Menü hinzufügen will?


TOC für nen TOC
contexts für contexts
index für index
...


> 2) welche Plugins muss ich für den build im product file angeben? - Wahrscheinlich die ganzen Webapp-Plugins nicht...


org.eclipse.help und dann add required


----------



## dzim (17. Apr 2009)

Ich bin mir durchaus bewusst, das ich hier ein wenig penetrant bin, aber irgendwie versuche ich gerade das ganze zu checken...
Wenn man nur ab und an mal ein wenig nachließt, ist das allerdings recht schwierig.

An die Idee der TOC und Indexe habe ich mich gewöhnt, mit den Contexts, die ja anscheinend irgendwie für die Kontextsensitive Hilfe zuständig sind will ich mich erst einmal noch nicht beschäftigen, weil ich mich sonst sicher nur noch mehr verwirre.

Ich würde gern die Hilfe in ein separates Plugin tun - mach ja sicher auch aus wartungsgründen am meisten Sinn.
Mir stellt sich die Frage: Was ist Sinnvoll? Plugin oder Fragment? Wo ist der Unterschied?

Darüber hinaus hab ich nur alte Tutorials (2007 und älter) gefunden, die beschreiben, wie man das Help-Menü selbst in die App bekommt, indem man im ApplicationActionBarAdvisor dieses einträgt
Eclipse Corner Article: Adding Help Support to a Rich Client Application
allerdings passiert beim anwählen von Help Contents/Search/... nichts - liegt das daran, das ich noch keine TOC u.s.w. hatte?

Danke für eure Geduld schon mal


----------



## Vayu (17. Apr 2009)

die toc ist zwingend notwendig. dort steht ja auch der pfad zur den hilfe dateien drin.


----------



## dzim (20. Apr 2009)

Ich habe eine prmitive TOC (die, die durch die Templates generiert wird) eingebunden.
Zusätzlich habe ich in meiner plugin.xml noch org.eclipse.help und org.eclipse.help.ui eingebunden, in mein product die beiden + org.eclipse.help.base, das selbe gilt auch für die Run-Config.

Mein ApplicationActionBarAdvisor sieht wie folgt aus:

```
import org.eclipse.jface.action.GroupMarker;
import org.eclipse.jface.action.IMenuManager;
import org.eclipse.jface.action.MenuManager;
import org.eclipse.jface.action.Separator;
import org.eclipse.ui.IWorkbenchActionConstants;
import org.eclipse.ui.IWorkbenchWindow;
import org.eclipse.ui.actions.ActionFactory;
import org.eclipse.ui.actions.ActionFactory.IWorkbenchAction;
import org.eclipse.ui.application.ActionBarAdvisor;
import org.eclipse.ui.application.IActionBarConfigurer;

/**
 * An action bar advisor is responsible for creating, adding, and disposing of
 * the actions added to a workbench window. Each window will be populated with
 * new actions.
 */
public class ApplicationActionBarAdvisor extends ActionBarAdvisor {

	// Actions - important to allocate these only in makeActions, and then use
	// them
	// in the fill methods. This ensures that the actions aren't recreated
	// when fillActionBars is called with FILL_PROXY.
	private IWorkbenchAction exitAction;
	private IWorkbenchAction aboutAction;
	private IWorkbenchAction showHelpAction;
	private IWorkbenchAction searchHelpAction;
	private IWorkbenchAction dynamicHelpAction;

	public ApplicationActionBarAdvisor(IActionBarConfigurer configurer) {
		super(configurer);
	}

	@Override
	protected void makeActions(final IWorkbenchWindow window) {
		// Creates the actions and registers them.
		// Registering is needed to ensure that key bindings work.
		// The corresponding commands keybindings are defined in the plugin.xml
		// file.
		// Registering also provides automatic disposal of the actions when
		// the window is closed.

		// Resets the Window from the last run
		// (also see ApplicationWorbenchAdvisor@initialize(...)
		// ActionFactory.RESET_PERSPECTIVE.create(window);

		exitAction = ActionFactory.QUIT.create(window);
		register(exitAction);

		aboutAction = ActionFactory.ABOUT.create(window);
		register(aboutAction);

		showHelpAction = ActionFactory.HELP_CONTENTS.create(window);
		register(showHelpAction);

		searchHelpAction = ActionFactory.HELP_SEARCH.create(window);
		register(searchHelpAction);

		dynamicHelpAction = ActionFactory.DYNAMIC_HELP.create(window);
		register(dynamicHelpAction);
	}

	@Override
	protected void fillMenuBar(IMenuManager menuBar) {
		MenuManager fileMenu = new MenuManager("&File",
				IWorkbenchActionConstants.M_FILE);
		MenuManager helpMenu = new MenuManager("&Help",
				IWorkbenchActionConstants.M_HELP);

		menuBar.add(fileMenu);
		menuBar.add(new GroupMarker(IWorkbenchActionConstants.MB_ADDITIONS));
		menuBar.add(helpMenu);

		// file
		fileMenu.add(exitAction);

		// help
		helpMenu.add(aboutAction);
		helpMenu.add(new Separator());
		helpMenu.add(new GroupMarker(IWorkbenchActionConstants.HELP_START));
		helpMenu.add(showHelpAction);
		helpMenu.add(searchHelpAction);
		helpMenu.add(dynamicHelpAction);
		helpMenu.add(new GroupMarker(IWorkbenchActionConstants.HELP_END));
	}
}
```

Es wird auch das Help-Menü mit den Einträgen angezeigt, allerdings passiert beim Versuch "Help Contents" zu öffnen nichts.
Dagegen kann man den "Search"- / "Dynamic Help"-View problemlos öffnen, auch wenn ich nix explizit dafür angelegt habe. Nutzt man dort allerdings "Go to:"->"All Topics" wird mein TOC angezeigt. Aber warum öffnet sich dann "Help Contents" nicht? muss dort explizit noch was eingebunden werden?

[edit]
Das ging schnell... Ich habe noch die Dependency org.eclipse.help.webapp eingetragen, überall verlingt - und siehe da: Es geht! Man glaubt es nicht!
[/edit]


----------



## dzim (27. Apr 2009)

Hi,

zum Glück hab ich meine ersten (Blödheits-)Fehler mit der Hilfe überwunden. Ich hätte einige male mir nur mal die Fehler anschauen müssen, um zu erfahren, was fehlt und nicht geht. Aber sei's drum.
Ich hab weiterhin versucht doch noch Kontextsensitive Hilfe einzubauen, auch wenn ich das ursprünglich nicht so geplant habe.

Eigentlich ist es ja ganz einfach - mein Hilfe-Kontent-plugin enthält nun auch nocht den Extension point zu contexts und ich habe die entsprechende xml angelegt.

Was jetzt allerdings nicht geht, das das wichtigste: Das Verlinken.
Ich habe einige About-Infos über das Programm auf die Perspektive gelegt - da allerdings immer bei Start des Progrmms gleich der Haupt-View aufgeht, wird dieser eigentlich nie angezeigt. Der Haupt-View hat auch seinen Context, ebenso wie die Editoren.
Seltsam allerdings ist folgendes:
Verlinke ich etwas mittels 

```
IWorkbenchHelpSystem helpSystem = getSite().getWorkbenchWindow()
		.getWorkbench().getHelpSystem();
helpSystem.setHelp(getSite().getShell(), Activator.PLUGIN_ID
                + ".ssd_selection_view");
```
beim anlegen der Klasse, wird es nur beim ersten Start angezeigt (das hier ist aus einem View).
Lade ich dann einen Editor mit einem eigenen Eintrag in die Help (wird auch nur beim anlegen des Editors verlinkt) wird dieser angezeigt, aber wenn ich nun zurück auf den View klicke, bleibt der Eintrag des Editors stehen?
Muss ich da noch irgendwo was in die setFocus()-Methode schreiben?

Ach so: In dem View ist auch ein Viewer - passenderweise. Wenn ich diesen als Basis für den Link nehmen 

```
IWorkbenchHelpSystem helpSystem = getSite().getWorkbenchWindow()
		.getWorkbench().getHelpSystem();
helpSystem.setHelp(viewer.getControl(), Activator.PLUGIN_ID
		+ ".ssd_selection_view");
```
passiert dann einfach gar nichts mehr und die Hilfe bleibst selbst beim laden des Editors auf dem Viewer stehen?

Any hints? Any tips and tricks?

Danke schon mal (wieder) vorab.


----------



## Wildcard (27. Apr 2009)

Wenn du in der dynamic help einen Link anklickst, ist sie nicht mehr dynamic (also context sensitiv). Um sie wieder dynamisch zu schalten entweder den 'back' button verwenden, oder schließen und neu öffnen mit F1


----------



## dzim (28. Apr 2009)

ich habe es tatsächlich in die jeweilige setFocus Methode verlinkt und es geht jetzt - sowohl der obere (About...) als auch der untere (Dynamic Content) Teil.
Ich bin aber ehrlich, das ich es mir nicht hundertprozentig erklären kann, weil zwar bisher der obere, aber nicht der untere Teil ging - ich weiß nicht, was ich verändert habe, ausser eine index.xml hinzugefügt zu haben. Wegen der Schlagwortsuche.
Das man nach klick auf einen Link die jeweile (html) Seite oder was man dahinter hat angezeigt bekommt ist ok, das war mir bereits aus Eclipse her so bekannt.
Mein Problem war wirklich nur, das es (auch ohne angewählten link) nicht hin und her geschaltet hat.

Da ich jetzt eigentlich alle Fragen bezüglich der Help geklärt und auch weitestgehend verstanden habe, würde ich das Thema gern schließen. Wie das in der neuen Forensoftware jetzt geht, weiß ich allerdings noch nicht.


----------



## Wildcard (28. Apr 2009)

dzim hat gesagt.:


> Da ich jetzt eigentlich alle Fragen bezüglich der Help geklärt und auch weitestgehend verstanden habe, würde ich das Thema gern schließen. Wie das in der neuen Forensoftware jetzt geht, weiß ich allerdings noch nicht.


Funktioniert derzeit noch nicht.


----------

