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