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

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

On Feb 24, 2010, at 9:55 AM, Torsten Bergmann wrote:

why not using the same seaside html canvas api?






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

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

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