[Preview] Help System with new model

Hi Stef and Michael,

your responses have shown me that I may have not clearly communicated
what is possible and what my goals are. It has also shown me that
you mainly talk about the help system as to provide "API help" or
reference documentation, which is possible but was not my main goal.
So lets explain it in more detail:

We have two separate cases/kind of help:

A. Help for the system in front of you ("SystemHelp")
   Documentation of a tool or a process (General Tool Help/Tutorials/F1 Help/Written Book)

B. Help on how the system in front of you is implemented ("SystemReference")
   Documentation of classes and methods, examples as in any other Smalltalk/Dev system ("API Help"/Class comments/Method comments)

Regading A - Help for the system in front of you ("SystemHelp"):
================================================================
Just evaluate

   HelpBrowser openOn: SystemHelp  

or just  

   HelpBrowser open

My initial goal was to do have "F1 Help" as in most other IDE's so a
help browser opens to display a complete help book with a full
written Tutorial on how the Monticello Browser works.

Or how one is able to work with Metacello or what object oriented
 programming is all about, or how one is able to create a project on
Squeaksource. We could even have an ASCII version of "Pharo by Example", ...

This kind of help doesnt even have to be related to stuff that is
in the image. You could provide books on gardening and read them in
the image if you like. ;)

This kind of help could have been external in files or on a webpage,
- but I since my goal was that one can read/display it also within the
image I JUST (AB)USE classes and class hierarchies to store the help
book contents.

This also allows to manage the books and contents with usual
Smalltalk tools and (if required) also to provide dynamic content.
But typically these classes just provide the help contents and
it is intended that they have no behavior!

I dont want this to be limited to tutorials or tool help.
Think of a case where one writes a card playing game with
Pharo and want to provide a help book to the commercial end user
explaining the game.

I know it is much more effort to write such documentation - but
for the dev-image/pharo tools we may provide at least simple books
to explain basic things like the project itself, license, how
to get started with the tools, ...

Since this kind of help is typically structured like a real book
there is the "CustomHelp" class allowing you to map your
books structure directly to subclasses.

If you write such a "class mapped" book you want to keep the
book/subbooks/pages together and not spread around the
image.

And I call this "System help" since it shows you help
to explain the system that is in front of you (either Pharo
or the commercial card game). When you run

   HelpBrowser open

this "SystemHelp" (see the according class SystemHelp) just
collects all direct subclasses of CustomHelp as root books.
Nothing more.

So if you want to have your book appear in this "system wide
help" you:

 1. either store your book contents in the CustomHelp hierarchy
    (this is the typical case where you map the book to
     subclasses, see class "HelpOnHelp" or "PharoHelp" for example)

 2. or provide a direct/indirect CustomHelp subclass to just
    define the book to appear in the system help but get the contents
     from other sources (see class "PharoAPIHelp" which allows us
     to provide the whole class API in the Pharo book)

Especially the second option allows you to mix dynamic content
like API Help into these "system help books". Just open the
chapter "API Reference" in the "Pharo" book when you have
the package "Pharo-Project-Help" loaded. More on this later.

Dont get me wrong, it is alway possible to open the Help browser
on any object that is able to convert itself into a HelpTopic
instance using #asHelpTopic

    HelpBrowser openOn: myObjectWhoCanBeConverted
 
but it is necessary to have a subclass of CustomHelp it
appears in the default "system wide help" (SystemHelp)
when you open the browser using the menu or by "HelpBrowser open".

So CustomHelp is the entry point here, nothing more!

To summarize:
   - A. is intended for whole books and a system wide help system
   - A. requires the class "CustomHelp"
      - to define at least the "root books" appearing in this "System help"
      - to allow mapping a book structure directly to a class hierarchy
        (and keep this book with its subbooks together)

Providing such a help was the original goal of the help system
which is now fully possible. Still plain ASCII and without
support for markup, images, ... yet - but usable.

Regarding B - Help on how the system in front of you is implemented ("SystemReference"):
======================================================================================
Just evaluate

  HelpBrowser openOn: SystemReference

Beside A. there is also "Documentation of classes and methods"
as we have in any other programming languages or Smalltalk systems.
Maybe also enhanced with provided examples.

I think this is what you both want.

But this is "help" oriented towards developers since you wont need
that for the end user if you ship your commercial card playing
game ;)

This kind of "browsable developer help" is what you both seem to
understand when you speak about the "Help system". To me this is
nothing more than documentation on how the system is implemented.
It is a reference of the system - we already have it in the
image with class comments, method comments.

I call this "API-Help" or "System reference" (see the class SystemReference) and is only a subpart of a help system that I want.

Anyway - the general help system is able to work with it too since
you can build books from any source. Dont be afraid:
the developer typically uses the Smalltalk browser to define
and look at the comments as before. There is no dependency on the
help system here.

But if the help system is loaded he is able to get a better summary
using the help tools:

    HelpBrowser openOn: SystemReference

or

    HelpBrowser openOn: Integer

or

    HelpBrowser openOn: (SystemReference hierarchyFor: Integer)

since the info is just extracted by a builder or an object
that converts the contents into help topics with structure.

So the place where the help contents for B. is defined
(class comments, method comments, ...) is not bound to the help
system and the builder decides what is extracted and from what
source. See HelpBuilder subclasses for example.


So when Stef wrote: "The point is to avoid duplicating code
between a class and its help or between a testcase and the help".

I can just answer: there is no duplication, nothing has changed here,
you document your classes and methods as before and you dont need a
 subclass of CustomHelp or the help system to do that!!!

But if me may want to enhance the informations that can be extracted
by the builder here or spice up the "API help" browsing experience
we can define pragmas that can later be used by the help builders
(like the current ClassAPIHelpBuilder).

If we want to drive this forward then we should discuss
about having not only Pragmas for methods but also for classes.
For instance in Java I'm able to add annotations to a class comment:

   @author:  Tut Ench Amun
   @version: 1333-1324 BC

that is later used by the JavaDoc system. AFAIK Pragmas in Pharo
are currently limited to method level.

If we would have this

   HelpBrowser openOn: Integer

could show the author, version, whatever you like.

You just have to define what you need and enhance the builder
to extract it.

To summarize:
  - the more general help system (A) is able to display contents
    from any source including help contents extracted from usual
    Smalltalk classes/methods (B)
  - there is no dependency between the documented classes/methods
    and the help system itself in any case
  - if we want to enhance this part we can define pragmas that
    can be used by a help builder to provider a better "system reference"
    experience

Long story, but in general: please dont see the help system
as a better "documentation" browser to document your classes.
It's more.

Michael wrote:
>I just wonder if the definition of the help (the raw content) should also >be bound up with the definition of the overall structure?

For A. if you write a full book as described in A. I would answer YES
       since it helps to see the books structure also in the class
       hierarchy browser
 
For B. the structure is already separated since it is defined
       by the builder depending on your needs, compare:

  HelpBrowser openOn: (SystemReference forClass: Integer)
  HelpBrowser openOn: (SystemReference hierarchyFor: Integer)
  HelpBrowser openOn: (SystemReference hierarchyWithMethodsFor: Integer)


>So that's why i think of it in terms of annotations.
>Having the help be in its own help class, on the class side, without
>any real behavior is a design smell to me.

You didnt understand why I provide "CustomHelp". Having a subclass
is only necessary when you map a book structure to a class hierarchy.

It is intended that these books typically have no behavior since they
are just used to store book contents. You can see it as a vehicle
to bring text content into the image (similar to WAFileLibrary
subclasses in Seaside to bring in resources like images, stylesheets).

This has nothing to do with a design smell. You seem to be too much
focused on API like help. And I always said that we can use
annotations for B. here to keep it independent from the help system.

If you want to reference documentation for your classes you dont
need to use CustomHelp!

If you read you will see that I said it is harder to describe
the structure of a full book using pragmas when you want A.
I would prefer the CustomHelp subclassing here since you find
your books structure also in the class hierarchy.

Stef wrote:
>Yes but it can also be out of sync.

This is more related to us all beeing lazy writing and maintaining docu ;)

>I like literate programming just because the comments are in the code.

You can continue to have that, I see no conflict here

>Writing separate and maintaining doc is costly and I was thinking that
>I wanted to reuse as much as possible as the existing information (class >comments, unit tests...).

Yes, but there is little value in this since you can already access
this using the usual Smalltalk tools. Its just a simple way to fill
the help browser with contents, but we have it now. ;)

Convinced for inclusion?

Bye
T.


--
GRATIS für alle GMX-Mitglieder: Die maxdome Movie-FLAT!
Jetzt freischalten unter http://portal.gmx.net/de/go/maxdome01

_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project