[4.1] Porting need: HelpSystem

Hello

On 1/5/13, Germán Arduino <[hidden email]> wrote:
> This is always a challenge, I mean collect all the knowledge disperse on
> the mailing lists.

Yes.

> Don't think you that more than tons of workspaces we should port the Help
> System? Someone looked into it to understand if is a big job?
>

Yes, I think as well that mid term we need the help system from Squeak ported.
It is included in Squeak and was done by Torsten Bergmann. It is on
www.squeaksource.com but as it is now part of the Squeak image I
suggest to take that version.

As for now having a few workspaces more (see the current help menu in
the screen shot) is not an issue, I think.

     5 entries so far

Maybe we can have a dividing bar after them so separate the five
entries from 'VM statistics' and 'Space left'.

Let's focus on more tests, useful expressions, code snippets to adapt and notes.
(see the other mails of mine today)

Another area to give some example code is "File operations".

However it is probably not a big effort to port the HelpSystem (I did
not check, maybe between 1....10 hours :-)   ),

It might be a good starting point for somebody who wants to get into
porting packages to Cuis. So if anybody wants to take this one, that
is very fine.

Kind regards

--Hannes

_______________________________________________
Cuis mailing list
[hidden email]
http://jvuletich.org/mailman/listinfo/cuis_jvuletich.org

Hi Angel, and sorry about the late reply. Inline, and I've cut it short to the points I've responded to.

On Sat, Jan 5, 2013 at 4:44 AM, Angel Java Lopez <[hidden email]> wrote:

Hi people!

I'm the "non-smalltalk dev" in this list ;-)  And I want to say something.

Heh;) My resume mostly says "Ruby" these days. It said "Perl" before that. I'm hoping to make it say "Smalltalk" or something more directly related than "Ruby."

 

Yes, I know there is the "Smalltalk way" of doing many things...

Makes me think of: http://www.drdobbs.com/architecture-and-design/interview-with-alan-kay/240003442#

"The most disastrous thing about programming — to pick one of the 10 most disastrous things about programming — there's a very popular movement based on pattern languages. WhenChristopher Alexander first did that in architecture, he was looking at 2,000 years of ways that humans have made themselves comfortable. So there was actually something to it, because he was dealing with a genome that hasn't changed that much. I think he got a few hundred valuable patterns out of it. But the bug in trying to do that in computing is the assumption that we know anything at all about programming. So extracting patterns from today's programming practices ennobles them in a way they don't deserve. It actually gives them more cachet."

What he said.

 

but... in other technologies, no help system is practically used (since last decade? more?). The flow is:

- Google search

- Giving post resulst, or stack overflow question, answers

You left a piece out. Most of what you're searching for on Google after your first tutorial or two in most of these systems is API documentation. This is usually automatically extracted from the code (method/function signatures) and the comments in the code (so-called "documentation comments.") Most of the time this stuff can be rendered directly in several formats, e.g., text, html, markdown, etc, and more often than not, the documentation is generated and updated constantly by a continuous integration server.

Regardless, an advantage of doing it this way is that the code and the docs are related not by release version, but by *checkin,* which is nice -- even if most of the time no one documents anything, you want to make it painless when they do, so you just change the doc comment when you change what the code does and check it in.

 

I wish I could find the email in question, but after talking about HelpSystem with Andreas for a bit and suggesting that we use it to capture our docs in the MC update stream, he sent me what amounted to a five-ish line patch which allowed you to change the content of the help and then accept (cmd/alt/ctrl-s, depending on OS) and it would dirty the Monticello package by storing the text of the help content in a method, thus causing the change to be easy to commit just like anything else. Unfortunately, I don't think it got integrated in the trunk, and I don't know why. Might just have found the cutting room floor.

http://en.wikipedia.org/wiki/Cutting_room_floor

For samples, if the project is hosted in GitHub, usually there is a samples folder in the project. (well, I'm very proud of my samples in CobolScript

https://github.com/ajlopez/CobolScript/tree/master/samples

;-)

One of the things I wanted to do with HelpSystem was give it export formats, most importantly text and html. Text is trivial and html isn't hard to do. I've had other priorities though, so I haven't gotten it done. I'd much rather see docs.cuis.org than just a text file on GitHub.

Oh! And I forgot to mention: HelpSystem automatically extracts method signatures, and treats the first comment in every method as a doc comment (which actually works out pretty well, as it's a common stylistic affectation to document a method at the top.) So in most respects, other than the missing export feature, it's really a lot *more* like the way other systems do it. Also, it's only a couple of years old; if there's a "Smalltalk Way" it's got to be at least some ten to twenty years older than HelpSystem!

:D

<snip />

--
Casey Ransberger
_______________________________________________
Cuis mailing list
[hidden email]
http://jvuletich.org/mailman/listinfo/cuis_jvuletich.org