Hi,
OK, just read the IRC meeting notes and the last posts/threads on the help
discussions.
Unfortunately the discussion is scattered and I try to catch up/summarize here
even for people who are new to the topic. Excuse the length of this post in
advance.
If the pragma help is interesting to you only then jump to section "D":
A. Pharo once lacked a "help system", so I wrote one. It was and still is more
oriented
towards "end user help" or "browsable manuals" with written text content in
form of
nestable books. I had no need for the next JavaDoc in Smalltalk with just
an API reference
- I wanted real help text which gives a big picture overview to people on
various topics.
The design of HelpSystem is simple and should be easy to understand, we
have a
HelpBrowser that displays (nestable) HelpTopics. To display something you
have to
convert it into such a help topic instance.
Click on "Help" -> "HelpBrowser" in your Pharo image and have a look at the
book
"Help on Help" to get more details or try a few examples.
B. I think you all agree that a "help system" without content is not very
useful.
Different people have different ideas and what could be used as "help
contents"
should be up to you.
The HelpSystem itself is not and should not be bound to where and how
(format, etc.)
the content is stored. You can convert from any source and format into
nested HelpTopics.
To demonstrate this I once provided an example [1] to query and display the
IRC archive.
You will also find this example with IRC as one possible external source in
the "Help on help"
book.
So the content could be defined in any format you like and the contents
source could be
internal or external to the image. You should declare the help contents the
way you like.
C. When you want to provide help to a user you may find it nice to include and
manage
the contents directly within the image. Nice - since you can deploy it with
your app or
unload if it is not needed.
There are many solutions here - on squeak-dev it was discussed to use a
specific class
comment format or store the contents in methods returning an XML string,
etc.
I expected this discussion since I thought long enough about formats,
storage and I
didnt want to limit anyone.
Therefore HelpSystem is open to any of these solutions - one can implement
a custom
help builder (see class HelpBuilder) that does the necessary conversion
into help topic
instances.
One of the many possible solution is to use "pragma annotated" classes that
hold the
contents. Looks like this is getting more attention now again since pragmas
are used
in various places now (like the settings framework).
And yes, I followed the pragma path already. But after initial experiments
with pragmas
I found it much more convenient to map a tutorial/the help book structure
directly to
the class hierarchy.
This "class to book" mapping is more natural, one can use the usual class
browsers and
tools to manage the contents (including references, implementors, senders,
...)
and you can easily have extensible books/tutorials (which is complicated
with pragmas)
If you want to follow this "class to book" approach then HelpSystem
provides a class
called "CustomHelp" that you can subclass and that has all the necessary
support
(even for editing and saving by using a workspace) - so you can easily
implement your
help books. Some projects use this already and there is even a Pharocast on
how to
to this.
Through the class CustomHelp in the HelpSystem we have a commonality with
SUnit -
where you have TestCase as a superclass and implement hook methods.
This class "CustomHelp" is the one "under fire" that leads to scathing
criticism from
Lukas.
Maybe it is exactly this commonality with SUnit that makes some of you
think HelpSystem
forces you to subclass "CustomHelp" or forces you to have a dependency on
the help system
if you want to declare your help content.
=> But yet again: nobody has to use the provided "class to book" mapping
or subclass
"CustomHelp" if you want to define your help contents!
Maybe I should not ship HelpSystem with this support class "CustomHelp" as
the (currently sole)
default but I wanted to at least provide a way to get you started. Still it
is an utility class
and also categorized as such.
I for myself have no problem with this additional class since when
subclassed I know that
I have a dependency on it's package and I treat the help packages similar
to test
in SUnit (only loaded when HelpSystem is there, etc.)
However the "CustomHelp" approach has pros and cons and you have to decide
if it is the
right for you:
Maybe you like: - easy mapping of classes to books
- easy browsing/managing in standard code tools
- familarity with SUnit (common superclass)
- no "copy/paste" methods as in Metacellos
ConfigurationOfXXX
Maybe you dislike: - the dependency on the superclass CustomHelp and
- therefore the dependency on the help package
Typical use case is that you display the help contents in the browser
anyway and
therefore this dependency may not hurt you.
Looks like Lukas has a use-case where he requires his help contents only -
but
not the help system itself. Similar to a loaded test without any SUnit
support in the image...
D. As I already said I designed HelpSystem to stay independent from the way
the contents is
defined. So I'm definitely open to a pragma based solution too. In the long
term I would like to see
support for different "content definition styles" anyway.
Lukas can store his blog posts/help texts the way he likes and without any
dependency on HelpSystem.
After the discussion in May we all agreed [2] that it is a good direction
to check out the
pragma/builder approach too and see how far we can go here. I provided an
example how one
can easily add this "pragma approach" to to the HelpSystem ([3] and [4] for
the code) but I left
out the builder part since I dont know what Lukas expects here.
So no real feedback/adoption so far ... at least it would help if I get an
example
on how the contents should be defined in an annotated #buildHelpOn: method.
However, the pragma approach has pros and cons:
Maybe you like: - no dependency on a common superclass or package
dependency on a class in HelpSystem
- may therefore seem "cleaner" depending on POV
Maybe you dislike: - even with pragmas one has an implicit dependency on
the builders interface
which also has to be stable very early
- by using pragmas (loose coupling) you have to deal
with the problem that
your parent topic may not be there/not be loaded
since it can be defined
somewhere else in the class hierarchy.
E. After the initial release people asked on how to integrate typical
"Smalltalk documentation"
to include browsable reference documentation (API doc) like class and
method comments in the
HelpSystem too. This was easy to add since again I just had to write a
custom help builder that does the
necessary conversion.
If you load the "Pharo-Project-Help" you can browse the complete reference
on anything that
is already documented:
Gofer new
squeaksource: 'HelpSystem';
package: 'Pharo-Project-Help';
load.
HelpBrowser open.
In the help browser click on "Pharo" and "API Reference". This is more
"reference documentation" and
only a "poor" way to easily fill up the help system ;)
I would like to see people writing more tutorials/manuals about parts of
the system so one could get the big
picture, but the idea of Stef [5] to get fully documented classes and
methods is also nice. For the
reference docu:
Maybe you like: - no dependency on anything, just comment your
classes and methods
as you may know from any other smalltalk system
Maybe you dislike: - you dont need the help system, you can look at it
in the standard browser
- its only a basic API documentation system (compared
to JavaDoc and others)
-----------------------------------------------------------------------------------------------------------------
And now some comments on IRC/posts I've seen:
Lukas on IRC see [6]:
>[3:14pm] renggli: HelpSystem is not useable for me and obviously not for
>anybody else (otherwise
>it wouldn't be empty)
Lukas, nobody forces you to follow the "define help contents via class to book
mapping" approach.
If you want a "define help content via pragmas" approach then help moving this
issue forward or define
your help contents the way you like and implement a custom help builder.
For the other point: HelpSystem is not empty - look at an updated core 1.2 and
it is already
used in many external packages as Laurent already pointed out. [7]
Lukas wrote on [8]:
>> Couldn't you just add another loop to your script to "unload all help" just
>> like unload all tests
>Sure, but that means I have to package help text separately. This is
>the contrary to what Java, Ruby, Python, Javascript, ... are doing;
>keeping code and documention as close together as possible.
No - you dont have to package documentation seperately. A class/method comment
is still a
class/method comment and its packaged with the code. There is no dependency on
HelpSystem
here - although the HelpBrowser can display it too.
You still keep code and documentation close as in any other language.
But if you write a "big picture" help manual or tutorial on how things interact
it would
be good to package it seperately. Either using CustomHelp, pragmas, or ...
Lukas wrote on [8]:
>I think, the fact that there is no single external package with help
>system documentation proves this, no?
There are quite a few. Maybe you should look more often on Squeaksource. Again
I point to [7]
Stef wrote on [9]
>Now I was thinking that torsten would reply to this mail but in 1.3 will take
>a decision because I want a really better help
>and documentation inside the right class and package.
I still think that we should in minimum have the "code" - "tests" - "help"
package triade, where the code package
includes the class and method documentation as any Smalltalker is used to. The
test package should include unit tests
covering the code. And the help package should give a high level overview on
how to use the code or tests.
If the dependency from "help" packages to "help system" due to the class
CustomHelp is a problem then
we can easily convert them once we have a good "pragma based" approach in place.
Removing packages or classes that are not documented is too hard ... but we
should use Lint rules to check the
"completeness/basic quality" of package.
Similar to checkstyle for Java in Eclipse - if there are problems in a package
then you have a different icon for
the package and you work until it's clean because it hurts your eyes (see [10]
for a screenshot)
Hope I could at least bring some light into the whole discussion and I would
really like
the see if also the pragma approach would move forward.
Bye
Torsten
[1]
http://forum.world.st/Preview-Help-System-with-new-model-now-also-for-Squeak-td1695386.html
[2] http://forum.world.st/Help-System-td2131748.html
[3] http://lists.gforge.inria.fr/pipermail/pharo-project/2010-May/026148.html
[4]
http://lists.gforge.inria.fr/pipermail/pharo-project/attachments/20100505/cc589ac2/attachment-0001.obj
[5]
http://lists.gforge.inria.fr/pipermail/pharo-project/2010-December/036952.html
[6] http://pastebin.com/Y7MFaddK
[7]
http://lists.gforge.inria.fr/pipermail/pharo-project/2010-December/037507.html
[8]
http://lists.gforge.inria.fr/pipermail/pharo-project/2010-December/037485.html
[9]
http://lists.gforge.inria.fr/pipermail/pharo-project/2010-December/037499.html
[10]
http://www.ibm.com/developerworks/java/library/j-ap01117/checkstyle-eclipse.jpg
--
Neu: GMX De-Mail - Einfach wie E-Mail, sicher wie ein Brief!
Jetzt De-Mail-Adresse reservieren: http://portal.gmx.net/de/go/demail
