[Cuis] HelpSystem in core vs. external package

[H. Hirzel]

Hello Casey

On 1/25/13, Casey Ransberger <casey.obrien.r at gmail.com> wrote:
> Inline.
>
> On Jan 25, 2013, at 2:04 PM, Germán Arduino <garduino at gmail.com> wrote:
>
>> Hi Casey:
>>
>> I tend to think in external packages to not bloat Cuis itself, but
>> .... currently we have several text editor windows with help opened at
>> start (that I close as my first operation in a new image).
>
> Indeed. Code ought to give a big bang for the buck to go in. That said,
> after reviewing Torsten's code, I'm pleased. It's pretty clean, and small.

Yes, it is. But it is only plain text. And no hyperlinks between
pages. And no executable code, i.e no right-click menu with 'do it'.
One of the major advantages of Smalltalk is that you can build a "GUI"
just by presenting executable text is lost.

Anyhow the text for WebClient is good but it can be presented just in
a regular README.md with subtitles without problems.



 I
> wonder how many source lines of code e.g. Windows Help is, given it does the
> same thing + hyperlinks, - the auto API docs (surely Windows/Visual Studio
> has some other thing which does that.)
>
> I bet there's at least an order of magnitude less code text to read, though
> that isn't saying much about complexity (we can move mountains in one line
> of Smalltalk code. Try doing that in C++!)

You can do that as well if you call the right method.  :-)

>> Additionally, in my job of port WebClient, I had not ported the
>> detailed help of the package because we have not the help system, and
>> I think that this sort of help (as the included in the current text
>> windows) is very useful and not only for newbies.
>
> Yeah and Andreas really did a fantastic job of documenting WebClient using
> HelpSystem. I think part of why I glommed onto WebClient/Server had to do
> with his docs. They aren't long, but they're well written and make use of
> the library very easy.

Yes.

>> The same could apply to the Keyboard Shortcuts, Useful Expressions,
>> and packages specific help.

We already have this in Cuis. And as written above, the code in
'useful expressions' is executable. In Squeak BTW the 'Useful
Expressions' entry is not in Torsten's help system either, though it
is in the help menu.


> Not to mention that we could do a Terse Guide to Cuis (the Squeak terse
> guide is already in the help system, so we'd just have to curate it.)



>> Then, my vote is to have an integrated Help System on the image (of
>> course unloadable to permit a good shrink via #reduceCuis).
>
> Oh yes! Documentation should always be unloadable when one wants a small
> image.
>
> +1

I'd say put it into a github repository as of now. If Juan integrates
it then you later can delete that repository again, no problem.

Pharo uses it a bit more than Squeak, see attached screen shot. But
still the fact that code is not executable is a clear regression.

Regards
Hannes
-------------- next part --------------
A non-text attachment was scrubbed...
Name: HelpSystemInPharo2.0.png
Type: image/png
Size: 41639 bytes
Desc: not available
URL: <http://jvuletich.org/pipermail/cuis_jvuletich.org/attachments/20130126/75839575/attachment-0004.png>