Help System recommendation

[Novice]

I'm dusting off some old code with the intention of adding decent Help
systems to them. Before I start writing though, I'm wondering what the
preferred tools are for generating Help screens for Java programs these
days.

I've dabbled with Java Help back in the 2.01 days and it worked reasonably
well but it looks like it's not very active in terms of development and
improvements. In fact, when I tried to check out the current version number
just now on the download page, http://java.net/projects/javahelp/downloads,
it says there is no current version to download. I'm guessing that JavaHelp
is no longer available.

So, what are people using these days?

I'm seeing more and more cases where clicking on Help in an application
menu brings the user to a website rather than windows on their desktops. Is
it fair to say that's the preferred approach these days? If so, can anyone
point me to information about how people are invoking those web-based help
systems, preferably with examples that illustrate the technique?

I'm already very familiar with web design, HTML, CSS, etc. I'm just unsure
about what code goes into the application to direct the user of a desktop
application to the website. Basically, I just need the code that gets
executed in the application once the mouse click is detected and it is
determined that it was Help which was clicked. I can build the website
easily enough myself.

I'm also curious to know about preferred tools for building help systems
that don't need an internet connection. In those cases, the application
itself needs to display help screens without recourse to the web.

 

[John B. Matthews]

[...]
So, what are people using these days?

I'm seeing more and more cases where clicking on Help in an
application menu brings the user to a website rather than windows on
their desktops. Is it fair to say that's the preferred approach these
days? If so, can anyone point me to information about how people are
invoking those web-based help systems, preferably with examples that
illustrate the technique?

I'm already very familiar with web design, HTML, CSS, etc. I'm just
unsure about what code goes into the application to direct the user
of a desktop application to the website. Basically, I just need the
code that gets executed in the application once the mouse click is
detected and it is determined that it was Help which was clicked. I
can build the website easily enough myself.

I'm also curious to know about preferred tools for building help
systems that don't need an internet connection. In those cases, the
application itself needs to display help screens without recourse to
the web.

java.awt.Desktop, new in 1.6, is useful in both cases: browse() can
accept a URI that references either a local or remote resource.
Conveniently, it also leverages the user's chosen desktop browser.

The older javax.swing.JEditorPane is convenient, but it's limited to
HTML 3.2 with a few extensions. There's an example here:

<http://robotchase.sourceforge.net/>

 

[Novice]

[...]
So, what are people using these days?

I'm seeing more and more cases where clicking on Help in an
application menu brings the user to a website rather than windows on
their desktops. Is it fair to say that's the preferred approach these
days? If so, can anyone point me to information about how people are
invoking those web-based help systems, preferably with examples that
illustrate the technique?

I'm already very familiar with web design, HTML, CSS, etc. I'm just
unsure about what code goes into the application to direct the user
of a desktop application to the website. Basically, I just need the
code that gets executed in the application once the mouse click is
detected and it is determined that it was Help which was clicked. I
can build the website easily enough myself.

I'm also curious to know about preferred tools for building help
systems that don't need an internet connection. In those cases, the
application itself needs to display help screens without recourse to
the web.

java.awt.Desktop, new in 1.6, is useful in both cases: browse() can
accept a URI that references either a local or remote resource.
Conveniently, it also leverages the user's chosen desktop browser.

The older javax.swing.JEditorPane is convenient, but it's limited to
HTML 3.2 with a few extensions. There's an example here:

<http://robotchase.sourceforge.net/>

java.awt.Desktop sounds like it may be just what I want. I could deal with
JEditorPane too but Desktop sounds like it is a better fit for what I want
without the limitations of HTML 3.2. Is it just me or is it odd that they
aren't gradually updating JEditorPane to accomodate newer versions of HTML?

Thanks John!

 

[Roedy Green]

I'm dusting off some old code with the intention of adding decent Help
systems to them. Before I start writing though, I'm wondering what the
preferred tools are for generating Help screens for Java programs these
days.

Most people are just linking to an ordinary web page. This lets you
compose it with your usual tools, not needing to learn new skills.

The HTML validator people used one. I complained there was no inpage
search which I would have with any browser. They could not supply it
because such support did not come with the help engine.

Another advantage of HTML is the help is likely to say more up to
date.

Another advantage is if your vendor goes belly up, your code still
works without having to write a translator.

See http://mindprod.com/jgloss/javahelp.html

Another possibility is an ebook. There are ebook preparation tools to
create the index. Creating an index is not hard using a custom regex
extracting program.
--
Roedy Green Canadian Mind Products
http://mindprod.com
For me, the appeal of computer programming is that
even though I am quite a klutz,
I can still produce something, in a sense
perfect, because the computer gives me as many
chances as I please to get it right.

 

[John B. Matthews]

Is it just me or is it odd that they aren't gradually updating
JEditorPane to accomodate newer versions of HTML?

Pure speculation: I'm guessing the developers see diminishing returns on
trying to support a browser-in-a-box, when the component level support
is good enough:

<http://docs.oracle.com/javase/tutorial/uiswing/components/html.html>

 

[Roedy Green]

Pure speculation: I'm guessing the developers see diminishing returns on
trying to support a browser-in-a-box, when the component level support
is good enough:

I first took your post to mean the claim JEditorPane was stalled was
speculation. However, now I think you meant "diminishing returns" was
speculation.

The HTML that JEDitorPane supports is pretty primtive and fragile and
it has not changed in years.

It is also very slow. I think for any volume, you want ot fire up a
browser to render.
--
Roedy Green Canadian Mind Products
http://mindprod.com
For me, the appeal of computer programming is that
even though I am quite a klutz,
I can still produce something, in a sense
perfect, because the computer gives me as many
chances as I please to get it right.

 

[John B. Matthews]

I first took your post to mean the claim JEditorPane was stalled was
speculation. However, now I think you meant "diminishing returns" was
speculation.

Exactly. I originally wrote, "Pure speculation on my part," but
shortened it as too wordy. Concise became elliptical. The colon was
meant to introduce an appositive independent clause, but an "—" (em
dash) might have been more clear.

The HTML that JEDitorPane supports is pretty primtive and fragile and
it has not changed in years.

It is also very slow. I think for any volume, you want ot fire up a
browser to render.

Yes. Primitive, fragile and slow; but perfect for enriching the odd
explanatory dialog.

 

[Fredrik Jonson]

Most people are just linking to an ordinary web page. This lets you
compose it with your usual tools, not needing to learn new skills.

Yes, this must be the preferred alternative today when every user has
a browser they know better than any other tool on the system and
a favourite search engine.

I like how orac^Wsun as an option also offer you to download the entire
html documentation in a ordinary zip file. Very cross platform and
ideal when the supplier is bought by another company and the documentation
vanishes from the internet.

And please spare your users from the ajax experience. When publishing
documentation quick-loading cacheable static plain old html rules.

 

[Roedy Green]

I like how orac^Wsun as an option also offer you to download the entire
html documentation in a ordinary zip file. Very cross platform and
ideal when the supplier is bought by another company and the documentation
vanishes from the internet.

If the set of documents is large, or changes frequently, you might use
the Replicator to efficiently maintain a local mirror.

See http://mindprod.com/products1.html#REPLICATOR

Another reason to use online HTML is that you can use google with a
site: qualifier to help you find stuff you can't find in the index.
--
Roedy Green Canadian Mind Products
http://mindprod.com
For me, the appeal of computer programming is that
even though I am quite a klutz,
I can still produce something, in a sense
perfect, because the computer gives me as many
chances as I please to get it right.

 

[Jim Janney]

I'm dusting off some old code with the intention of adding decent Help
systems to them. Before I start writing though, I'm wondering what the
preferred tools are for generating Help screens for Java programs these
days.

I've dabbled with Java Help back in the 2.01 days and it worked reasonably
well but it looks like it's not very active in terms of development and
improvements. In fact, when I tried to check out the current version number
just now on the download page, http://java.net/projects/javahelp/downloads,
it says there is no current version to download. I'm guessing that JavaHelp
is no longer available.

So, what are people using these days?

I'm seeing more and more cases where clicking on Help in an application
menu brings the user to a website rather than windows on their desktops. Is
it fair to say that's the preferred approach these days? If so, can anyone
point me to information about how people are invoking those web-based help
systems, preferably with examples that illustrate the technique?

I'm already very familiar with web design, HTML, CSS, etc. I'm just unsure
about what code goes into the application to direct the user of a desktop
application to the website. Basically, I just need the code that gets
executed in the application once the mouse click is detected and it is
determined that it was Help which was clicked. I can build the website
easily enough myself.

I'm also curious to know about preferred tools for building help systems
that don't need an internet connection. In those cases, the application
itself needs to display help screens without recourse to the web.

Displaying HTML in a browser is probably the best option, and it doesn't
limit you to using an external web site. Other options are:

1) distribute static HTML files with your application, and point the
browser at them using the file:// protocol. Javahelp supports this
method.

2) generate HTML files in a temporary directory when help is requested,
and point the browser at them.

3) embed a little HTTP server in your application (I believe this is how
Eclipse provides its online help).

1) is the simplest method if static help is good enough. 3) is probably
the best if you need more control at run time. I don't particularly
recommend 2) even though I'm doing it -- I can only say that the project
was already very late and learning how to embed a server would have
delayed it even further.