[Preview] Help System with new model

Michael Roberts wrote:
> I think it should be possible for help to appear in the global help
> browser without having to define a subclass of CustomHelp. This would
> make the entry barrier really low for people to be able to document
> parts of the system using this help system.

Yes, I had a pragma solution using <helpTopic: 'Title goes here'>
in one of the first versions - but it gets complicated if you
want to define structured help contents with nested books and
with pages in a specific order. The implementation is easy ...
I mean with pragmas it would be complicated for the "help writer"
to define these nested book structures and to remember the correct
pragmas.

And you have to solve the following scenario: you may have a class
A defining a help book using pragmas and a class B defining another
help book which should be displayed under the book defined by A.
Since you do not rely on a "help class hierarchy" and are decoupled
using pragmas both classes can live under Object. Good. Everything
works fine when A and B are in the image. But you can get a problem
when class A is not loaded - since the parent book of B is not there.


I would not see a problem in having the help hierarchy clearly
defined as a subclass hierarchy of a predefined "CustomHelp" class.
Providing CustomHelp subclasses is easy to understand for the
"content writer" and system help is not spread around in the image.
You can see the structure in the class hierarchy browser and in the
help browser. Thats wonderfull.
For all these reasons I would prefer a CustomHelp for the standard
help. (Independent from that the help browser itself is still
capable to use anything with an #asHelpTopic interface).


Providing the CustomHelp class is the same as with TestCase - you know
that when you subclass you will later find it in the UI tool
(TestRunner/help browser) and you can peek in other TestCase subclasses
to see what is possible.

And yes, that means that minimal help support (in minimum 2 classes
HelpTopic and CustomHelp) is already in the image similar to SUnit.

Dont know if the name CustomHelp is good (maybe HelpBook/SystemHelpBook?).


Stef wrote:
>do you have a new version that we could integrate to 1.1?

see http://www.squeaksource.com/HelpSystem

The baseline works fine in 1.1.#11309, but I would remove
a few methods after integration (for Squeak and Pharo 1.0
compatibility, see #initWindowInSqueak #isSqueak #isPharo11
and senders). That's easy.

However, it is already working in 1.1. and integration
would just mean to load it:

 - the minimum support is in the Core package HelpSystem-Core-tbn.35
 - the according tests (HelpSystem-Tests-tbn.9) are green in 1.1 too.

Thats anything you need to have help support, the browser ("Tools"->"Help Browser") and the full  API help stuff
(just run "HelpBrowser openOn: SystemReference" or any other sample I
provided).

One thing: if you just have the "HelpSystem-Core" loaded the standard
help browser for the system would only display the help for
the help system itself.


If you want to additionally provide infos/content on the Pharo project
you need other packages like "Pharo-Project-Help".

We can enhance "Pharo-Project-Help" and use it either for the
dev image or core image. We can also keep "Pharo-Project-Help"
minimal for the pharo core image with basic infos on the project and
create a "Pharo-Project-Dev-Help" or others for the pharo developer image.


I see three options:
 (1) integrate it in 1.1. core as you wrote
 (2) no help in pharo core to keep it minimal and have
     the help system as one of the first packages loaded in the
     pharo dev image
 (3) wait until we can enhance it with Scamper code, markup, ...
    (which takes more time than I have now)

Another option (4) which I dislike:
If you find the help-core package (which currently includes
the UI browser) to much for a pharo-core image we can also
split the package so that:

 - the core model is in the image (only classes HelpTopic and CustomHelp
   are really necessary) so one can define and write help content
 - the help browser and builders are loadable/exchangable
   afterwards

I would keep them together since you need minimal support to
visually control what you wrote and why have help contents
in the image when you cant browse it ;)

If you would follow that path I can argue that we have to keep
the settings framework but provide the settings browser only
in the dev-image. Same issue.

Thats why I would either follow (1) or (2), but that is just MHO.

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

> Yes, I had a pragma solution using <helpTopic: 'Title goes here'>
> in one of the first versions - but it gets complicated if you
> want to define structured help contents with nested books and
> with pages in a specific order. The implementation is easy ...
> I mean with pragmas it would be complicated for the "help writer"
> to define these nested book structures and to remember the correct
> pragmas.


The point is to avoid duplicating code between a class and its help
or between a testcase and the help.

> Providing CustomHelp subclasses is easy to understand for the
> "content writer" and system help is not spread around in the image.

Yes but it can also be out of sync. I like literate programming just because
the comments are in the code.

I'm not worried by having two classes extra in the system or core since
help will not been referenced from everywhere. This kind of packages are easy
to unload. I was more concerned about the idea that we can use the system
to annotate what should be promoted as help.
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...).

Stef






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

Torsten, i appreciate the thought you are putting in. I just wonder if
the definition of the help (the raw content) should also be bound up
with the definition of the overall structure?  I also wonder if I want
to bend the help system in a way that it is not intended.

For me i want something that is like python doc strings, and the great
python package documentation available, ... but in a more smalltalk
in-image manner.  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. I don't really like heavy
class-side programming; the class doesn't really offer any behaviour
or scale across the image.  I guess i want to see docs spread across
the system. you want them central?  to me the classes are really just
annotations, apart from as you say needing to provide the role of
structure for the nested content.

my use case is that the documentation must be next to the code it is
documenting. the network package is a good example. Since the API is
in a state of flux, and no one knew how the 'new' api was supposed to
work,  it could really benefit detailed documentation for each version
of pharo. it will change likely for each major version.  the docs need
to be in the package. fine, we can have the requisite 2 classes
already in the image. that is ok. but it would be better to have the
doc content on the actual system classes themselves. Like
NetNameResolver. and Socket, etc. so i either have to have my custom
class reference them, in some imperative manner, or i need to build a
builder.. or something.  I had imagined it would be possible to have
standard places/hooks for packages and classes, where annotations
would go. for example like stef says we could pull out the class
comment.

also, i imagine if documenting the system, in a system wide manner,
was successful we would have lots of doit expressions. some mashup
between workspaces, profstef, and hypertext.  in that case it would be
nice to somehow link doc expressions that are really little test
assertions together, so we can actually test the docs to make sure
that they validate against the system code. I think the SBE/PBE latex
sources had this idea in them. And Adrian K has posted examples of
these nice extensions to sunit that read very well.  I would like that
feeling somehow integrated, otherwise we won't be able to maintain the
sanity of our docs either.  so i guess i'm kinda with stef's comments
later in this thread.

but anyway, we start with zero in-image documentation.  for me we must
just have a doc system that scales. i really want to see the docs in
the packages, not in a single central package.  we'll just have to see
how it plays out.  i don't want to take away from building a 'help
system' that would let you provide F1 style help for an actual
application - we just desperately need system level documentation to
take Pharo to the next level.   I guess I see no need for defining
inter-help structure because I think for system level docs it can be
entirely derived. each package, class, method can all be annotated in
a consistent manner.  programming examples could be attached to
classes in a standard manner. you could then provide a browser giving
A-Z, hierarchy, package, classes, search, index, etc views on these
annotations.  This is not what you are trying to do with your help
system, but i see this as a subset of the intent and a lot of the
logic already there. i'm not sure if i'm making any sense...

cheers,
Mike

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

yes this was my gut feeling too.
What I like with method annotation is that we can get people writing executable examples.
Once I discussed with lukas about tests and to me there is a difference between
writing tests for coverage and for public consumption.
For public consumption you write meaningful api sequence, mini scenario.

Stef

On Apr 8, 2010, at 11:49 PM, Michael Roberts wrote:


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