[4.1] Porting need: HelpSystem

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

[4.1] Porting need: HelpSystem

Hannes Hirzel
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
Reply | Threaded
Open this post in threaded view
|

Re: [4.1] Porting need: HelpSystem

Angel Java Lopez
Hi people!

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

Yes, I know there is the "Smalltalk way" of doing many things... 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

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
;-)

The main use cases are usually described in .md pages at GitHub project site. You can add images too (see the raw version of https://github.com/ajlopez/CobolScript/tree/master/samples/templateweb to see how to link to a image hosted in the same GitHub project site). 

You have the option of having a site, the branch gh-page, with an static site. And there are static sites generators, like Octopress. 

I put simple online demo of my AjTalkJs (Smalltalk in JavaScript) in the gh-page branch of:
it was published as

As another branches, it can received pull request for improvements.

There is an administration option to create that branch with an initial style, and there are third--parties GitHub styles.

My 2 cents

Angel "Java" Lopez
@ajlopez
github:ajlopez

On Sat, Jan 5, 2013 at 9:20 AM, H. Hirzel <[hidden email]> wrote:
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


_______________________________________________
Cuis mailing list
[hidden email]
http://jvuletich.org/mailman/listinfo/cuis_jvuletich.org
Reply | Threaded
Open this post in threaded view
|

Re: [4.1] Porting need: HelpSystem

garduino
Make sense to me.....Never considered this option because I don't know a lot of GitHub. Only use it to store code.

But if we have here a possiblity of have complete documentation, images, etc, look good, because is searchable (it is?)

Doing a google search for CobolScript Hello World don't seems to find exactly the doc page....

But not having tons of text help in the image, look good....specially if we think that not all the dev/contributors write the doc in the help format.

-- 
Sincerely,
Germán Arduino
about.me/garduino


2013/1/5 Angel Java Lopez <[hidden email]>
Hi people!

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

Yes, I know there is the "Smalltalk way" of doing many things... 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

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
;-)

The main use cases are usually described in .md pages at GitHub project site. You can add images too (see the raw version of https://github.com/ajlopez/CobolScript/tree/master/samples/templateweb to see how to link to a image hosted in the same GitHub project site). 

You have the option of having a site, the branch gh-page, with an static site. And there are static sites generators, like Octopress. 

I put simple online demo of my AjTalkJs (Smalltalk in JavaScript) in the gh-page branch of:
it was published as

As another branches, it can received pull request for improvements.

There is an administration option to create that branch with an initial style, and there are third--parties GitHub styles.

My 2 cents

Angel "Java" Lopez
@ajlopez
github:ajlopez

On Sat, Jan 5, 2013 at 9:20 AM, H. Hirzel <[hidden email]> wrote:
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


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






_______________________________________________
Cuis mailing list
[hidden email]
http://jvuletich.org/mailman/listinfo/cuis_jvuletich.org
Reply | Threaded
Open this post in threaded view
|

Re: [4.1] Porting need: HelpSystem

Hannes Hirzel
Hi,

Yes and a narrower Google searchs

    CobolScript Hello World Angel Lopez

    CobolScript Hello World Angel Lopez github

Neither does it in the www.github.com

search box.

We must be missing something here.


--Hannes


On 1/5/13, Germán Arduino <[hidden email]> wrote:

> Make sense to me.....Never considered this option because I don't know a
> lot of GitHub. Only use it to store code.
>
> But if we have here a possiblity of have complete documentation, images,
> etc, look good, because is searchable (it is?)
>
> Doing a google search for CobolScript Hello World don't seems to find
> exactly the doc page....
>
> But not having tons of text help in the image, look good....specially if we
> think that not all the dev/contributors write the doc in the help format.
>
> --
> Sincerely,
> Germán Arduino
> about.me/garduino
>
>
> 2013/1/5 Angel Java Lopez <[hidden email]>
>
>> Hi people!
>>
>> I'm the "non-smalltalk dev" in this list ;-)  And I want to say
>> something..
>>
>> Yes, I know there is the "Smalltalk way" of doing many things... 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
>>
>> 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
>> ;-)
>>
>> The main use cases are usually described in .md pages at GitHub project
>> site. You can add images too (see the raw version of
>> https://github.com/ajlopez/CobolScript/tree/master/samples/templateweb to
>> see how to link to a image hosted in the same GitHub project site).
>>
>> You have the option of having a site, the branch gh-page, with an static
>> site. And there are static sites generators, like Octopress.
>>
>> I put simple online demo of my AjTalkJs (Smalltalk in JavaScript) in the
>> gh-page branch of:
>> https://github.com/ajlopez/AjTalkJs
>> it was published as
>> http://ajlopez.github.com/AjTalkJs/
>>
>> As another branches, it can received pull request for improvements.
>>
>> There is an administration option to create that branch with an initial
>> style, and there are third--parties GitHub styles.
>>
>> My 2 cents
>>
>> Angel "Java" Lopez
>> @ajlopez
>> github:ajlopez
>>
>> On Sat, Jan 5, 2013 at 9:20 AM, H. Hirzel <[hidden email]>
>> wrote:
>>
>>> 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
>>>
>>
>>
>> _______________________________________________
>> Cuis mailing list
>> [hidden email]
>> http://jvuletich.org/mailman/listinfo/cuis_jvuletich.org
>>
>>
>

_______________________________________________
Cuis mailing list
[hidden email]
http://jvuletich.org/mailman/listinfo/cuis_jvuletich.org
Reply | Threaded
Open this post in threaded view
|

Re: [4.1] Porting need: HelpSystem

Juan Vuletich-4
In reply to this post by garduino
Maybe we could use GitHub as the primary repository for all this, to
ease contributions. And from time to time, we can make them available
from inside Cuis, either by loading them in the image, or building an
optional package. This would mean that just having Cuis is enough, and
web access would not be absolutely required.

If any of you wishes to start, just start adding stuff to your GitHub
repositories, or send pull requests to the main Cuis repository.

Cheers,
Juan Vuletich

Germán Arduino wrote:

> Make sense to me.....Never considered this option because I don't know
> a lot of GitHub. Only use it to store code.
>
> But if we have here a possiblity of have complete documentation,
> images, etc, look good, because is searchable (it is?)
>
> Doing a google search for CobolScript Hello World don't seems to find
> exactly the doc page....
>
> But not having tons of text help in the image, look good....specially
> if we think that not all the dev/contributors write the doc in the
> help format.
>
> --
> Sincerely,
> Germán Arduino
> about.me/garduino <http://about.me/garduino>
>
>
> 2013/1/5 Angel Java Lopez <[hidden email]
> <mailto:[hidden email]>>
>
>     Hi people!
>
>     I'm the "non-smalltalk dev" in this list ;-)  And I want to say
>     something.
>
>     Yes, I know there is the "Smalltalk way" of doing many things...
>     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
>
>     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
>     ;-)
>
>     The main use cases are usually described in .md pages at GitHub
>     project site. You can add images too (see the raw version of
>     https://github.com/ajlopez/CobolScript/tree/master/samples/templateweb
>     to see how to link to a image hosted in the same GitHub project
>     site).
>
>     You have the option of having a site, the branch gh-page, with an
>     static site. And there are static sites generators, like Octopress.
>
>     I put simple online demo of my AjTalkJs (Smalltalk in JavaScript)
>     in the gh-page branch of:
>     https://github.com/ajlopez/AjTalkJs
>     it was published as
>     http://ajlopez.github.com/AjTalkJs/
>
>     As another branches, it can received pull request for improvements.
>
>     There is an administration option to create that branch with an
>     initial style, and there are third--parties GitHub styles.
>
>     My 2 cents
>
>     Angel "Java" Lopez
>     @ajlopez
>     github:ajlopez
>
>     On Sat, Jan 5, 2013 at 9:20 AM, H. Hirzel <[hidden email]
>     <mailto:[hidden email]>> wrote:
>
>         Hello
>
>         On 1/5/13, Germán Arduino <[hidden email]
>         <mailto:[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 <http://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] <mailto:[hidden email]>
>         http://jvuletich.org/mailman/listinfo/cuis_jvuletich.org
>
>
>
>     _______________________________________________
>     Cuis mailing list
>     [hidden email] <mailto:[hidden email]>
>     http://jvuletich.org/mailman/listinfo/cuis_jvuletich.org
>
>
>
>
>
> ------------------------------------------------------------------------
>
> _______________________________________________
> Cuis mailing list
> [hidden email]
> http://jvuletich.org/mailman/listinfo/cuis_jvuletich.org
>  


_______________________________________________
Cuis mailing list
[hidden email]
http://jvuletich.org/mailman/listinfo/cuis_jvuletich.org
Reply | Threaded
Open this post in threaded view
|

Re: [4.1] Porting need: HelpSystem

Casey Ransberger-2
In reply to this post by Angel Java Lopez
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...


"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.


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
;-)

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
Reply | Threaded
Open this post in threaded view
|

Re: [4.1] Porting need: HelpSystem

Chris Hogan-2
Hi, 

I am a bit of a lurker.  The comment earlier about most people going to google or stack overflow reminded me of the old hypertextclasscomments.

Does anyone still use those?




On Fri, Jan 25, 2013 at 1:42 AM, Casey Ransberger <[hidden email]> wrote:
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...


"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.


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
;-)

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



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