HelpSystem & Class comments

Crosspost squeak-dev/pharo-dev

Andreas Raab wrote:
>a) Currently a book depends on the presence of HelpSystem (i.e., via
>subclassing).

No, you are not forced to be in the "CustomHelp" hierarchy.
You can define an own hierarchy, directly as subclass of Object, whatever
(athough I would recommond CustomHelp as common superclass similar to
 TestCase in SUnit)

The standard builder ("HelpBuilder") is able to use a different root.
See HelpBuilder class>>buildFromRoot: and HelpBuilder>>defaultRoot.

With HelpSystem-Core-tbn.16 I even allow to provide own builders.
To get the latest you can just load the baseline:

  (ConfigurationOfHelpSystem project version: '1.0-baseline') load


b) Typing in '' quotes is pretty insane when you quote text.

  I know, but this is annoying since you currently write it manually
  using the browser and by adding methods yourself. Storing the
  contents in method is just the vehicle - additional authoring
  capabilities would help here in the future (an additional HelpEditor
  beside the HelpViewer). Again you judged too early.

  I would also like to see some reactivation of Scamper code for
  a more capable viewer/editor - since with a basic support for
  simple markup we could catch two flies by providing in-image and
  web-help with the same contents/source.

>I'm not saying that comments are the only way by which HelpBooks should
>be created but I think that this should be one of the ways that
>HelpSystem directly supports.

That's already there - Danny already added this for the help classes.
Just open the book "Help on Help" -> "HelpSystem API Documentation"
and subnodes after loading the latest baseline.
If you click on a class node you will see the class comment displayed
in the help (currently as ASCII).

We may add a book "Reference" where you open two subbooks:
"By categories" and "By hierarchy" - displaying the classes
using categories or in their usual class hierarchy for browsing.


However: the main question to me is the kind of format we should
         use:

  a) Wiki Style or similar
      + easy to write
      + easy to transform
      - mostly non-standard

     With Maven the APT format is often used [1], Eclipse for instance
     provides even editors, see [2] for screenshots)
     But we also have Tiny wiki syntax somewhere on SqueakSource which
     may be similar.

  b) real markup like HTML
      + easy to put onto the web without tranformation
      - we need to have more markup support
      -/+ embedding of Smalltalk has to be done the W3C way, similar
        to javascript  <a href="smalltalk:..."

  c) specific format like Squeaks Text representation with textDoits, ...
      - very Squeak specific and may not work in Pharo
      - hard to put on the web

I would like to see b) with a cleaned up Scamper code since
a general markup editor/viewer would be helpfull anyway and it would
be easy to publish stuff on the web. But looks like more work.

There is also another HTML browser with markup and CSS now available
open source as MIT (WithStyle), see [3] and [4] for more info.
Maybe someone has a minute ;)

Bye
T.

[1] http://maven.apache.org/doxia/references/apt-format.html
[2] http://sourceforge.net/project/screenshots.php?group_id=193560
[3] http://n4.nabble.com/ANN-HelpSystem-was-ProfStef-td1554685.html
[4] http://www.cincomsmalltalk.com/userblogs/rowanb/blogView?showComments=true&printTitle=Im_back..._but_SWS_isnt&entry=3364012145






     



--
Sicherer, schneller und einfacher. Die aktuellen Internet-Browser -
jetzt kostenlos herunterladen! http://portal.gmx.net/de/go/chbrowser

On 2/24/10 6:55 AM, "Torsten Bergmann" <[hidden email]> wrote:

>
>   I would also like to see some reactivation of Scamper

>From far away bat cave I add logic to trunk.
Update image and do

|loader |
    loader _ CodeLoader new.
    loader baseURL: 'http://www.squeaksource.com/Ladrillos/'.
    loader loadSourceFiles: #('Scamper-edc.13.mcz' );installSourceFiles.

Now you have Scamper as in earlier Squeak, from here some take it and made
new version.

Edgar

Torsten Bergmann wrote:
> Andreas Raab wrote:
>> a) Currently a book depends on the presence of HelpSystem (i.e., via
>> subclassing).
>
> No, you are not forced to be in the "CustomHelp" hierarchy.
> You can define an own hierarchy, directly as subclass of Object, whatever

What I'm looking for is a mechanism by which the documentation can
remain in the image even when HelpSystem is absent. So when HelpSystem
is loaded it needs to discover available books. Is there some tag/marker
mechanism by which one can flag those pre-existing books?

> The standard builder ("HelpBuilder") is able to use a different root.
> See HelpBuilder class>>buildFromRoot: and HelpBuilder>>defaultRoot.
>
> With HelpSystem-Core-tbn.16 I even allow to provide own builders.

That's useful, but I'd still need a way of denoting to HelpSystem, "hey,
here, over here, (*hand waiving*) me, yes, me, I'm a HelpBook!" :-)

> b) Typing in '' quotes is pretty insane when you quote text.
>
>   I know, but this is annoying since you currently write it manually
>   using the browser and by adding methods yourself. Storing the
>   contents in method is just the vehicle - additional authoring
>   capabilities would help here in the future (an additional HelpEditor
>   beside the HelpViewer). Again you judged too early.

It's simply extremely annoying. That's why I was saying, why not derive
help books from class comments? That's is a place for documentation
already, it has all those properties. And for many types of
documentation this is just the right place.

>> I'm not saying that comments are the only way by which HelpBooks should
>> be created but I think that this should be one of the ways that
>> HelpSystem directly supports.
>
> That's already there - Danny already added this for the help classes.
> Just open the book "Help on Help" -> "HelpSystem API Documentation"
> and subnodes after loading the latest baseline.
> If you click on a class node you will see the class comment displayed
> in the help (currently as ASCII).

Right I've seen that. This is pretty good already, the only thing I'm
asking for is just a tiny bit of additional structure in a class comment
so that one can have sections etc.

> However: the main question to me is the kind of format we should
>          use:
>
>   a) Wiki Style or similar
>   b) real markup like HTML
>   c) specific format like Squeaks Text representation with textDoits, ...

I'd say: All of them! :-) This is a matter of builders, no? I don't
think there's a need to decide upfront that only one format will be
supported. We could start with simple Wiki syntax which can be used in
class comments and other simple places. If people feel unsatisfied or
need more or want to use HelpSystem for other purposes, extend it as
desired.

Cheers,
   - Andreas

2010/2/24 Torsten Bergmann <[hidden email]>:
I would be in favour of an internal representation, whereas we could
use an UI editor with edition tools. The idea is to be able to use
different backends. The system could be used within Squeak environment
but also to generate online documentation.

Ian.
--
http://mecenia.blogspot.com/

Andreas wrote:
>What I'm looking for is a mechanism by which the documentation can
>remain in the image even when HelpSystem is absent

Why? Do you have test cases subclasses in the image when SUnit
is absent? No.

I think you want to have support or UI stuff removed/separated
(like the viewer) - but a basic model should remain.
The costs for the basic help system model support is minimal.

Similar to SUnit. If you have the core model (TestCase) you
are able to load/process tests done in subclasses.
But with a separated UI you have the freedom for an exchangable
TestRunner.

Same should apply here.

>What I'm looking for is a mechanism by which the documentation can
>remain in the image even when HelpSystem is absent. So when HelpSystem
>is loaded it needs to discover available books. Is there some tag/marker
>mechanism by which one can flag those pre-existing books?
>
>(*hand waiving*)

Maybe we should return to a pragma based solution. I originally
had something like this. Just load "HelpSystem-Core-tbn.4" and have a look
at class HelpHowTo methods. They have a "help" pragram.

The pragma processing mechanism is in HelpBuilder>>createBookFrom:

Danny removed this to introduce a HelpContent class (to support
different content) - which I merged into HelpPage later.

>That's why I was saying, why not derive
>help books from class comments?

How? Would you create a class for each page and use their
class comment for the contents?

>the only thing I'm asking for is just a tiny bit of additional structure >in a class comment so that one can have sections etc.

As I said - maybe we should reactivate some Scamper code and use a markup
 language. The Parser from "Network-HTML" package on SqS.com/Scamper
seems to work. Although it still uses _ instead of :=.
We "just" have to rebuld a clean viewer.

>We could start with simple Wiki syntax which can be used in
>class comments and other simple places. If people feel unsatisfied or
>need more or want to use HelpSystem for other purposes, extend it as
>desired.

We already discussed this and decided to first start with plain text
and later add different content types (markup, active bookmorphs, ...)
after getting the tool integration and other capabilities done.
(I already pointed to the original discussion on pharo-dev)

Bye
T.












   
--
Sicherer, schneller und einfacher. Die aktuellen Internet-Browser -
jetzt kostenlos herunterladen! http://portal.gmx.net/de/go/atbrowser

Torsten Bergmann wrote:
> Andreas wrote:
>> What I'm looking for is a mechanism by which the documentation can
>> remain in the image even when HelpSystem is absent
>
> Why? Do you have test cases subclasses in the image when SUnit
> is absent? No.

Don't confuse cause and effect. The reason why you don't have test cases
in the image when SUnit is absent is because you *can't* not because you
don't want to. Documentation, in particular when it is simple text, can
be consumed in a variety of ways.

> I think you want to have support or UI stuff removed/separated
> (like the viewer) - but a basic model should remain.
> The costs for the basic help system model support is minimal.

Is it? Can we push it into the trunk? I'd love to have enough support in
the trunk so that we can start providing documentation for the upcoming
release. I've been wanting to rewrite the "What's New" section into a
proper format, i.e., as reference for people downloading the next
release so that we can point out the changes in the various areas,
Compiler, Collection, Morphic, etc.
That's fine too. I honestly don't care, I just need *some* mechanism.

>> That's why I was saying, why not derive
>> help books from class comments?
>
> How? Would you create a class for each page and use their
> class comment for the contents?

No. I've been wanting to write an entire book in a class comment with
markup to denote sections in simple Wiki style. So the comment is the
entire book.

Since I'm obviously I'm not making myself clear here I've attached an
example. See what this does? All I'm asking for is to automate the
process a little. This way I wouldn't even have to make a separate class
I could just fetch the class comment straight from WebServer.

>> the only thing I'm asking for is just a tiny bit of additional structure >in a class comment so that one can have sections etc.
>
> As I said - maybe we should reactivate some Scamper code and use a markup
>  language. The Parser from "Network-HTML" package on SqS.com/Scamper
> seems to work. Although it still uses _ instead of :=.
> We "just" have to rebuld a clean viewer.

Or we just use TSTTCPW. I.e., some completely trivial markup syntax. For
class comments documentation this is advantageous because class comments
are text already, they can contain formatting, doIts, links etc. The
only thing they don't have at this point is structure.

>> We could start with simple Wiki syntax which can be used in
>> class comments and other simple places. If people feel unsatisfied or
>> need more or want to use HelpSystem for other purposes, extend it as
>> desired.
>
> We already discussed this and decided to first start with plain text
> and later add different content types (markup, active bookmorphs, ...)
> after getting the tool integration and other capabilities done.
> (I already pointed to the original discussion on pharo-dev)

Like I said earlier, I'm offering my help. I think that class comments
as books could be a major enabler for getting some documentation in.

Cheers,
   - Andreas

Andreas, a big +1 to your direction here.

The example looks markdown-ish, and I think that's one decent option.
None of the "simple" markups are perfect, and this one is suitably
lightweight, popular, and makes code blocks and HTML easy.

And I would vote for Markdown

Andreas Raab skrev 2010-02-24 14:16:
> Torsten Bergmann wrote:
>> Andreas Raab wrote:

> That's useful, but I'd still need a way of denoting to HelpSystem,
> "hey, here, over here, (*hand waiving*) me, yes, me, I'm a HelpBook!" :-


We have something similar to add objects to ObjectsTool :
 >>descriptionForPartsBin
This keep track of those morphs . Maybe something similar can be used
for for HelpSystem

Karl

> > With HelpSystem-Core-tbn.16 I even allow to provide own builders.
>
> That's useful, but I'd still need a way of denoting to HelpSystem, "hey,
> here, over here, (*hand waiving*) me, yes, me, I'm a HelpBook!" :-)

Load HelpSystem-Core-DannyChan.17 and the attached file. Then do

HelpSystem builder: MyBuilder.
HelpSystem reset.
HelpBrowser open.

You will see a class help on Object. Now you can customize MyBuilder to return
every collection of books you want. If you want to create the list by some
special tag, then you can override rootTopics to do what you want. I guess all
of this can be still streamlined, but it already possible to customize the
lookup process to your liking.
I want to do this, but I don't have much time currently. Its probably quite
simple, have a look at ClassAPIHelp and customize the two class side methods.

>
> > However: the main question to me is the kind of format we should
> >          use:
> >
> >   a) Wiki Style or similar
> >   b) real markup like HTML
> >   c) specific format like Squeaks Text representation with textDoits, ...
>

> I'd say: All of them! :-) This is a matter of builders, no? I don't
> think there's a need to decide upfront that only one format will be
> supported. We could start with simple Wiki syntax which can be used in
> class comments and other simple places. If people feel unsatisfied or
> need more or want to use HelpSystem for other purposes, extend it as
> desired.

That's why I added a class for the content of a page. Right now it takes a
string, but why not have classes for showing screencasts from URLs, HTML,
whatever. The page itself should decide how it should be presented. Actually
right now I don't know why we need builders, a page has the content, it knows
how it wants its content to be presented to be most helpful to users, and it
probably also knows where to get other content dynamically if it needs to
(like API documentation, which should be always up to date).

Danny