Smalltalk › Amber Smalltalk

A new repository for Amber documentation

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

10 messages Options

Nicolas Petton

A new repository for Amber documentation

Hi guys,

As the wiki needs some work and documentation is missing, I just created
a new repository for a brand new documentation for Amber at
https://github.com/amber-smalltalk/amber-documentation

The repo is still empty, and the first step is to cherry-pick and
improve pages from the wiki.

The contents of this repo (markdown pages) will later be integrated into
the website.

Pull Requests are greatly appreciated ;)

Cheers,
Nico

--
You received this message because you are subscribed to the Google Groups "amber-lang" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
For more options, visit https://groups.google.com/groups/opt_out.

Jeremy Shute-2

Re: A new repository for Amber documentation

Excellent.

I think a "getting started" guide would really be helpful. It took me a while to figure out the example repo I put together:

https://github.com/shutej/amber-example

...which has a single-file deployment story (sort of).

In practice I find that I most frequently refer to these pages:

https://github.com/amber-smalltalk/amber/wiki/From-smalltalk-to-javascript-and-back

...and...

https://github.com/amber-smalltalk/amber/wiki/How-to-load-amber

On this last page, it's not really clear that the expected mode of operation is to pull in Amber via Bower. (The word "bower" never appears. Yes, I know that Bower isn't necessary.)

It would also be helpful to have references to external resources which may not be required, but may be advisable for beginners:

http://requirejs.org/docs/start.html

http://gruntjs.com/getting-started

(I can't find what I consider a good tutorial for the npm install --save workflow, but the following explains some of that minutae: https://npmjs.org/doc/cli/npm-install.html)

Similar links to references for each of these tools might be helpful.

The AMD stuff is great, but I think it's probably still a struggle for people to understand how to get from point A to point B. Coming from Smalltalk you expect there to be "turtles all the way down," but here I think you really need some knowledge of the Javascript ecosystem in order to be effective with Amber.

Similarly, I still can't figure out how to express from within Smalltalk that some code depends on a require.js package. It may be worthwhile to have tools available from the IDE for importing Javascript packages...

Jeremy

On Fri, Jan 3, 2014 at 3:22 PM, Nicolas Petton <[hidden email]> wrote:

Hi guys,

As the wiki needs some work and documentation is missing, I just created
a new repository for a brand new documentation for Amber at
https://github.com/amber-smalltalk/amber-documentation

The repo is still empty, and the first step is to cherry-pick and
improve pages from the wiki.

The contents of this repo (markdown pages) will later be integrated into
the website.

Pull Requests are greatly appreciated ;)

Cheers,
Nico

--
You received this message because you are subscribed to the Google Groups "amber-lang" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
For more options, visit https://groups.google.com/groups/opt_out.

--
You received this message because you are subscribed to the Google Groups "amber-lang" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
For more options, visit https://groups.google.com/groups/opt_out.

Charles A. Monteiro

Re: A new repository for Amber documentation

I keep coming back to this project :) I guess I long to do some stuff in Smalltalk again. Anyhow, main issue with taking on Amber as opposed to efforts that I have done in DART is indeed documentation since the language is just great.

My main issue is that I will most always start from some already built rendered html template page generated by most probably a Ruby server. Point being I need to manipulate a DOM. DART , gives me nice api so that for example if I need to re-populate the contents of a table I can do that easily. All I see by scanning the browser is HtmlCanvas which seems to assist in building. I need something where I can by getting the ID of a table , do DOM for example:

http://www.w3schools.com/jsref/met_table_insertrow.asp

DART wraps all of this and of course more and there's docs / cookbook recipes etc for it.

It seems to be that Amber just assumes too much JQuery knowledge on the part of the prospective new member and perhaps that's Amber's target audience i.e the "doc" answer is go study JQuery.

The impatient run a way :), and may come back hoping things have changed.

Enough with the partial rant.

If somebody could just show me how to do the basic generic task of getting a dom element by id and manipulating it as illustrated in the link above and in an Amber Smalltalk idiomatic way , I would highly appreciated it.

thanks

Charles

On Friday, January 3, 2014 3:41:46 PM UTC-5, Jeremy Shute wrote:

Excellent.

I think a "getting started" guide would really be helpful. It took me a while to figure out the example repo I put together:

<a href="https://github.com/shutej/amber-example" target="_blank" onmousedown="this.href='https://www.google.com/url?q\75https%3A%2F%2Fgithub.com%2Fshutej%2Famber-example\46sa\75D\46sntz\0751\46usg\75AFQjCNGaEc0nXcN1GB1F7A-2P27go4g8LQ';return true;" onclick="this.href='https://www.google.com/url?q\75https%3A%2F%2Fgithub.com%2Fshutej%2Famber-example\46sa\75D\46sntz\0751\46usg\75AFQjCNGaEc0nXcN1GB1F7A-2P27go4g8LQ';return true;">https://github.com/shutej/amber-example

...which has a single-file deployment story (sort of).

In practice I find that I most frequently refer to these pages:

<a href="https://github.com/amber-smalltalk/amber/wiki/From-smalltalk-to-javascript-and-back" target="_blank" onmousedown="this.href='https://www.google.com/url?q\75https%3A%2F%2Fgithub.com%2Famber-smalltalk%2Famber%2Fwiki%2FFrom-smalltalk-to-javascript-and-back\46sa\75D\46sntz\0751\46usg\75AFQjCNFEoAvzKjJ20Ozb5129ypzW2j5ZSw';return true;" onclick="this.href='https://www.google.com/url?q\75https%3A%2F%2Fgithub.com%2Famber-smalltalk%2Famber%2Fwiki%2FFrom-smalltalk-to-javascript-and-back\46sa\75D\46sntz\0751\46usg\75AFQjCNFEoAvzKjJ20Ozb5129ypzW2j5ZSw';return true;">https://github.com/amber-smalltalk/amber/wiki/From-smalltalk-to-javascript-and-back

...and...

<a href="https://github.com/amber-smalltalk/amber/wiki/How-to-load-amber" target="_blank" onmousedown="this.href='https://www.google.com/url?q\75https%3A%2F%2Fgithub.com%2Famber-smalltalk%2Famber%2Fwiki%2FHow-to-load-amber\46sa\75D\46sntz\0751\46usg\75AFQjCNFTqEoNKXKaKc3r3I97gUKKrCAFZw';return true;" onclick="this.href='https://www.google.com/url?q\75https%3A%2F%2Fgithub.com%2Famber-smalltalk%2Famber%2Fwiki%2FHow-to-load-amber\46sa\75D\46sntz\0751\46usg\75AFQjCNFTqEoNKXKaKc3r3I97gUKKrCAFZw';return true;">https://github.com/amber-smalltalk/amber/wiki/How-to-load-amber

On this last page, it's not really clear that the expected mode of operation is to pull in Amber via Bower. (The word "bower" never appears. Yes, I know that Bower isn't necessary.)

It would also be helpful to have references to external resources which may not be required, but may be advisable for beginners:

<a href="http://requirejs.org/docs/start.html" target="_blank" onmousedown="this.href='http://www.google.com/url?q\75http%3A%2F%2Frequirejs.org%2Fdocs%2Fstart.html\46sa\75D\46sntz\0751\46usg\75AFQjCNHDWAnzW9t_sURxSnvRcGX-V6jfxQ';return true;" onclick="this.href='http://www.google.com/url?q\75http%3A%2F%2Frequirejs.org%2Fdocs%2Fstart.html\46sa\75D\46sntz\0751\46usg\75AFQjCNHDWAnzW9t_sURxSnvRcGX-V6jfxQ';return true;">http://requirejs.org/docs/start.html

<a href="http://gruntjs.com/getting-started" target="_blank" onmousedown="this.href='http://www.google.com/url?q\75http%3A%2F%2Fgruntjs.com%2Fgetting-started\46sa\75D\46sntz\0751\46usg\75AFQjCNE1SuvnafQU_ChrvF_w0wwW_qfoeQ';return true;" onclick="this.href='http://www.google.com/url?q\75http%3A%2F%2Fgruntjs.com%2Fgetting-started\46sa\75D\46sntz\0751\46usg\75AFQjCNE1SuvnafQU_ChrvF_w0wwW_qfoeQ';return true;">http://gruntjs.com/getting-started

(I can't find what I consider a good tutorial for the npm install --save workflow, but the following explains some of that minutae: <a href="https://npmjs.org/doc/cli/npm-install.html" target="_blank" onmousedown="this.href='https://www.google.com/url?q\75https%3A%2F%2Fnpmjs.org%2Fdoc%2Fcli%2Fnpm-install.html\46sa\75D\46sntz\0751\46usg\75AFQjCNEx66YogvlF9UMLaavkmXKVfXVBeA';return true;" onclick="this.href='https://www.google.com/url?q\75https%3A%2F%2Fnpmjs.org%2Fdoc%2Fcli%2Fnpm-install.html\46sa\75D\46sntz\0751\46usg\75AFQjCNEx66YogvlF9UMLaavkmXKVfXVBeA';return true;">https://npmjs.org/doc/cli/npm-install.html)

Similar links to references for each of these tools might be helpful.

The AMD stuff is great, but I think it's probably still a struggle for people to understand how to get from point A to point B. Coming from Smalltalk you expect there to be "turtles all the way down," but here I think you really need some knowledge of the Javascript ecosystem in order to be effective with Amber.

Similarly, I still can't figure out how to express from within Smalltalk that some code depends on a require.js package. It may be worthwhile to have tools available from the IDE for importing Javascript packages...

Jeremy

On Fri, Jan 3, 2014 at 3:22 PM, Nicolas Petton <<a href="javascript:" target="_blank" gdf-obfuscated-mailto="nO6iFTyAIrMJ" onmousedown="this.href='javascript:';return true;" onclick="this.href='javascript:';return true;">petton....@...> wrote:

Hi guys,

As the wiki needs some work and documentation is missing, I just created
a new repository for a brand new documentation for Amber at
<a href="https://github.com/amber-smalltalk/amber-documentation" target="_blank" onmousedown="this.href='https://www.google.com/url?q\75https%3A%2F%2Fgithub.com%2Famber-smalltalk%2Famber-documentation\46sa\75D\46sntz\0751\46usg\75AFQjCNFvAmgS1VrPFJOO87qvn1_b07V0YA';return true;" onclick="this.href='https://www.google.com/url?q\75https%3A%2F%2Fgithub.com%2Famber-smalltalk%2Famber-documentation\46sa\75D\46sntz\0751\46usg\75AFQjCNFvAmgS1VrPFJOO87qvn1_b07V0YA';return true;">https://github.com/amber-smalltalk/amber-documentation

The repo is still empty, and the first step is to cherry-pick and
improve pages from the wiki.

The contents of this repo (markdown pages) will later be integrated into
the website.

Pull Requests are greatly appreciated ;)

Cheers,
Nico

--
You received this message because you are subscribed to the Google Groups "amber-lang" group.
To unsubscribe from this group and stop receiving emails from it, send an email to <a href="javascript:" target="_blank" gdf-obfuscated-mailto="nO6iFTyAIrMJ" onmousedown="this.href='javascript:';return true;" onclick="this.href='javascript:';return true;">amber-lang+...@googlegroups.com.
For more options, visit <a href="https://groups.google.com/groups/opt_out" target="_blank" onmousedown="this.href='https://groups.google.com/groups/opt_out';return true;" onclick="this.href='https://groups.google.com/groups/opt_out';return true;">https://groups.google.com/groups/opt_out.

Siemen Baader

Re: A new repository for Amber documentation

Hi Charles,

On 04 Jan 2014, at 13:15, Charles A. Monteiro <[hidden email]> wrote:

I keep coming back to this project :) I guess I long to do some stuff in Smalltalk again. Anyhow, main issue with taking on Amber as opposed to efforts that I have done in DART is indeed documentation since the language is just great.

You are right. I found it not difficult to get started, but it requires asking around on the IRC channel for the right places to look and going through the somewhat unstructured github wiki [1] to find the right places to start. At one point, there also was nice documentation on amber-lang.net, but it seems to be gone again.

Reading the sources in the st/ folder of the amber installation also helped me to get a feel of idiomatic patterns.

My main issue is that I will most always start from some already built rendered html template page generated by most probably a Ruby server. Point being I need to manipulate a DOM. DART , gives me nice api so that for example if I need to re-populate the contents of a table I can do that easily. All I see by scanning the browser is HtmlCanvas which seems to assist in building. I need something where I can by getting the ID of a table , do DOM for example:

http://www.w3schools.com/jsref/met_table_insertrow.asp

DART wraps all of this and of course more and there's docs / cookbook recipes etc for it.

It seems to be that Amber just assumes too much JQuery knowledge on the part of the prospective new member and perhaps that's Amber's target audience i.e the "doc" answer is go study JQuery.

Indeed. Amber gives you a Smalltalk IDE inside the browser if you want to build to rich web applications on the HTML(5) platform. The relevant Smalltalk documentation, including the HTML canvas, is the free online book 'Pharo by Example', and the relevant DOM and jQuery documentation are jQuery's excellent docs. The wiki [2] shows how JS is used from Smalltalk. In my opinion we should be more clear about this in the docs, and then point to these sources, instead of trying to teach anyone jQuery ourselves.

The impatient run a way :), and may come back hoping things have changed.

Enough with the partial rant.

If somebody could just show me how to do the basic generic task of getting a dom element by id and manipulating it as illustrated in the link above and in an Amber Smalltalk idiomatic way , I would highly appreciated it.

You can use plain JS from smalltalk, use jQuery, or use the HTMLCanvas. HTMLCanvas with a little jQuery is the idiomatic way.

JS DOM methods from within smalltalk:

table := document getElementById: 'myTable' .

row := table insertRow: 0.

jQuery:

'#myTable' asJQuery append: '<tr><td>hello</td></tr>'

HTMLCanvas:

|canvas|

'#myTable' asJQuery empty.

canvas := HTMLCanvas onJQuery: '#myTable' asJQuery.

canvas tr with: [html td: 'hello' ].

Hope this gets you started, and good luck!

-- Siemen

1: https://github.com/amber-smalltalk/amber/wiki

2: https://github.com/amber-smalltalk/amber/wiki/From-smalltalk-to-javascript-and-back

thanks

Charles

On Friday, January 3, 2014 3:41:46 PM UTC-5, Jeremy Shute wrote:
Excellent.

I think a "getting started" guide would really be helpful. It took me a while to figure out the example repo I put together:

https://github.com/shutej/amber-example

...which has a single-file deployment story (sort of).

In practice I find that I most frequently refer to these pages:

https://github.com/amber-smalltalk/amber/wiki/From-smalltalk-to-javascript-and-back

...and...

https://github.com/amber-smalltalk/amber/wiki/How-to-load-amber

On this last page, it's not really clear that the expected mode of operation is to pull in Amber via Bower. (The word "bower" never appears. Yes, I know that Bower isn't necessary.)

It would also be helpful to have references to external resources which may not be required, but may be advisable for beginners:

http://requirejs.org/docs/start.html
http://gruntjs.com/getting-started

(I can't find what I consider a good tutorial for the npm install --save workflow, but the following explains some of that minutae: https://npmjs.org/doc/cli/npm-install.html)

Similar links to references for each of these tools might be helpful.

The AMD stuff is great, but I think it's probably still a struggle for people to understand how to get from point A to point B. Coming from Smalltalk you expect there to be "turtles all the way down," but here I think you really need some knowledge of the Javascript ecosystem in order to be effective with Amber.

Similarly, I still can't figure out how to express from within Smalltalk that some code depends on a require.js package. It may be worthwhile to have tools available from the IDE for importing Javascript packages...

Jeremy

On Fri, Jan 3, 2014 at 3:22 PM, Nicolas Petton <petton....@gmail.com> wrote:
Hi guys,

As the wiki needs some work and documentation is missing, I just created
a new repository for a brand new documentation for Amber at
https://github.com/amber-smalltalk/amber-documentation

The repo is still empty, and the first step is to cherry-pick and
improve pages from the wiki.

The contents of this repo (markdown pages) will later be integrated into
the website.

Pull Requests are greatly appreciated ;)

Cheers,
Nico

--
You received this message because you are subscribed to the Google Groups "amber-lang" group.
To unsubscribe from this group and stop receiving emails from it, send an email to amber-lang+...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

--
You received this message because you are subscribed to the Google Groups "amber-lang" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
For more options, visit https://groups.google.com/groups/opt_out.

Herby Vojčík

Re: A new repository for Amber documentation

Siemen Baader wrote:

> JS DOM methods from within smalltalk:
>
> table := document getElementById: 'myTable' .
> row := table insertRow: 0.
>
> jQuery:
>
> '#myTable' asJQuery append: '<tr><td>hello</td></tr>'
>
>
> HTMLCanvas:
>
> |canvas|
>
> '#myTable' asJQuery empty.
> canvas := HTMLCanvas onJQuery: '#myTable' asJQuery.
> canvas tr with: [html td: 'hello' ].

Idiomatic for this case is (IMO) appendToJQuery:; so:

[ :html | html tr with: [ html td: 'hello' ] ]
appendToJQuery: '#myTable' asJQuery

No need to create HTMLCanvas onJQuery.

> Hope this gets you started, and good luck!
>
> -- Siemen

Herby

--
You received this message because you are subscribed to the Google Groups "amber-lang" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
For more options, visit https://groups.google.com/groups/opt_out.

Siemen Baader

Re: A new repository for Amber documentation

Sent from my iPhone

On 04/01/2014, at 15.59, Herby Vojčík <[hidden email]> wrote:

>
>
> Siemen Baader wrote:
>> JS DOM methods from within smalltalk:
>>
>> table := document getElementById: 'myTable' .
>> row := table insertRow: 0.
>>
>> jQuery:
>>
>> '#myTable' asJQuery append: '<tr><td>hello</td></tr>'
>>
>>
>> HTMLCanvas:
>>
>> |canvas|
>>
>> '#myTable' asJQuery empty.
>> canvas := HTMLCanvas onJQuery: '#myTable' asJQuery.
>> canvas tr with: [html td: 'hello' ].
>
> Idiomatic for this case is (IMO) appendToJQuery:; so:
>
> [ :html | html tr with: [ html td: 'hello' ] ]
> appendToJQuery: '#myTable' asJQuery

Interesting. I didn't know that blocks respond to #appendToJQuery: Thanks!

-- Siemen

>
> No need to create HTMLCanvas onJQuery.
>
>> Hope this gets you started, and good luck!
>>
>> -- Siemen
>
> Herby
>
> --
> You received this message because you are subscribed to the Google Groups "amber-lang" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
> For more options, visit https://groups.google.com/groups/opt_out.

Manfred Kröhnert

Re: A new repository for Amber documentation

In reply to this post by Nicolas Petton

Hi,

On Fri, Jan 3, 2014 at 9:22 PM, Nicolas Petton <[hidden email]> wrote:

Hi guys,

As the wiki needs some work and documentation is missing, I just created
a new repository for a brand new documentation for Amber at
https://github.com/amber-smalltalk/amber-documentation

The repo is still empty, and the first step is to cherry-pick and
improve pages from the wiki.

Did you know that you can access the Wiki via Git, too?

The URL to access it is:

git://github.com/amber-smalltalk/amber.wiki.git

The contents of this repo (markdown pages) will later be integrated into
the website.

Is a collection of markdown pages enough?

The reason why I am asking is that markdown doesn't seem like a good choice if we want to build a comprehensive all-in-one guide (book) as documentation.

Pull Requests are greatly appreciated ;)

Cheers,
Nico

laci

Re: Re: A new repository for Amber documentation

In reply to this post by Herby Vojčík

or something like that

    [ :html | html table at: 'border' put: 2; yourself
        ; with: [ html tr
            with: [ html th append: 'egy ' ]
            ;with: [ html th append: 'egy-a ' ]
            ]
        ; with: [ html tr
            with: [ html td append: 'ketto' ]
            ;with: [ html td append: 'ketto-a' ]
            ]
    ] appendToJQuery: '#identifier' asJQuery

----Original Message----
From : [hidden email]
Date : 04/01/2014 16:00
To : [hidden email]
Subject : Re: A new repository for Amber documentation

Siemen Baader wrote:

> JS DOM methods from within smalltalk:
>
> table := document getElementById: 'myTable' .
> row := table insertRow: 0.
>
> jQuery:
>
> '#myTable' asJQuery append: '<tr><td>hello</td></tr>'
>
>
> HTMLCanvas:
>
> |canvas|
>
> '#myTable' asJQuery empty.
> canvas := HTMLCanvas onJQuery: '#myTable' asJQuery.
> canvas tr with: [html td: 'hello' ].
Idiomatic for this case is (IMO) appendToJQuery:; so:

[ :html | html tr with: [ html td: 'hello' ] ]
appendToJQuery: '#myTable' asJQuery

No need to create HTMLCanvas onJQuery.

> Hope this gets you started, and good luck!
>
> -- Siemen

Herby

--
You received this message because you are subscribed to the Google Groups "amber-lang" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
For more options, visit https://groups.google.com/groups/opt_out.

If you reply to this email, your message will be added to the discussion below:
http://forum.world.st/A-new-repository-for-Amber-documentation-tp4733978p4734140.html

To start a new topic under Amber Smalltalk, email [hidden email]
To unsubscribe from Amber Smalltalk, click here.
NAML

Nicolas Petton

Re: A new repository for Amber documentation

In reply to this post by Manfred Kröhnert

Manfred Kröhnert writes:
>
> Did you know that you can access the Wiki via Git, too?
> The URL to access it is:
>
> git://github.com/amber-smalltalk/amber.wiki.git

Yes, I know, but I also want to keep the wiki, probably for contributors
and maintainers.

> Is a collection of markdown pages enough?
> The reason why I am asking is that markdown doesn't seem like a good choice
> if we want to build a comprehensive all-in-one guide (book) as
> documentation.

My thought was to have markdown pages and include them in the website
and use jekyll. Do you have something else in mind?

Cheers,
Nico

--
You received this message because you are subscribed to the Google Groups "amber-lang" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
For more options, visit https://groups.google.com/groups/opt_out.

Manfred Kröhnert

Re: A new repository for Amber documentation

On Sun, Jan 5, 2014 at 11:24 PM, Nicolas Petton <[hidden email]> wrote:

Manfred Kröhnert writes:
>
> Did you know that you can access the Wiki via Git, too?
> The URL to access it is:
>
> git://github.com/amber-smalltalk/amber.wiki.git

Yes, I know, but I also want to keep the wiki, probably for contributors
and maintainers.

> Is a collection of markdown pages enough?
> The reason why I am asking is that markdown doesn't seem like a good choice
> if we want to build a comprehensive all-in-one guide (book) as
> documentation.

My thought was to have markdown pages and include them in the website
and use jekyll. Do you have something else in mind?

So far I didn't look for alternatives.

It also depends on the usecase.

If you don't plan to create an Amber book or something similar it should be enough to embed the markdown files on the website.

Maybe we could have an interactive documentation built with Amber in the long run?

Cheers,
Nico

Best,

Manfred