Squeak code now browsable and bookmarkable on the Web

Dear Squeakers,

Latest debate about documentation, accessing of source from the web and
Google indexing warmed me to the point that I made a first glimpse of a
web interface to code in Squeak image:

        http://squeak.aidaweb.si:8000

This is a newest Damien's squeak-web image and if, for instance, you'd
like to see the code of that web app, here is its bookmarkable Url:

        http://squeak.aidaweb.si:8000/category/aidabrowser.html

Everything is bookmarkable: class categories, classes, methods. That way
it is very easy to email someone a link to some code in your image. Yes,
your own image can soon be accessible from the web that way!

Best regards
Janko

--
Janko Mivšek
AIDA/Web
Smalltalk Web Application Server
http://www.aidaweb.si

On Jan 4, 2008 8:24 PM, Janko Mivšek <[hidden email]> wrote:
> Dear Squeakers,
>
> Latest debate about documentation, accessing of source from the web and
> Google indexing warmed me to the point that I made a first glimpse of a
> web interface to code in Squeak image:
>
>         http://squeak.aidaweb.si:8000
>

This looks very nice - I have found a small bug though: it looks as
though you need to encode the urls e.g. for '+' when it appears in
method names. Currently the following pages give 404 errors, but load
okay when %2B is used in place of the '+':
http://squeak.aidaweb.si:8000/class/AidaBrowserMethod/method/+*.html
http://squeak.aidaweb.si:8000/class/AidaBrowserMethod/method/+.html

Cheers,
Michael

On Jan 4, 2008 8:39 PM, Michael Davies <[hidden email]> wrote: Hmm, no class methods visible at the moment either :-(

Michael, be patient, this is still a prototype, a first glimpse to see
if squeakers like the idea. I'll then go on. But first I need to add a
nice ajaxified autocomplete field for a class search ...

Thanks for the comments, please go on!

Janko

Michael Davies wrote:
--
Janko Mivšek
AIDA/Web
Smalltalk Web Application Server
http://www.aidaweb.si

On Jan 4, 2008 8:53 PM, Janko Mivšek <[hidden email]> wrote:
> Michael, be patient, this is still a prototype, a first glimpse to see
> if squeakers like the idea. I'll then go on. But first I need to add a
> nice ajaxified autocomplete field for a class search ...
>
> Thanks for the comments, please go on!
>
> Janko
>

No problem, it's enthusiasm rather than impatience!

Hi Janko,

nice work, and you will find something similiar on the result page of

-  
http://www.google.com/search?q=OrderedCollection+addAllFirstUnlessAlreadyPresent:

May I add 2-3 things:

o fileIn hyperlinks which answer, with content-type: text/plain,
   the corresponding fileOut (at all the levels) as .st suffixed file,
   same as local fileOut would do.
o show the annotation info.
o make available what's inside *each* MC package of the local directory
   in a similiar fashion, top-entry-point: MCZ package+version file name.

Then we could begin making *each*published*version* of every class+method  
*searchable* on the web (and perhaps link from the SqueakSource project  
pages to a server which has some bandwidth for crawlers).

Thanks for your effort!

/Klaus

On Fri, 04 Jan 2008 21:24:13 +0100, Janko wrote:

Beautiful! Way to go, Janko!

As Michael said, tons of enthusiasm from here as well.

Some suggestions:
- use tree-like views by default, ideally with interactive collapse/expand
e.g. grouping categories by common pre-fixes

- somehow css-highlight elements that have/do not have any documentation at
their level (package, category, class, method).

Btw, do MCpackages or Squeak categories exist as objects in the images? do
they have docs? I think docs at this level are invaluable to newcomers to
that package.

Any chance you might add an entry field so anyone can contribute to the
documentation of categories, classes, or methods? Not sure how it would feed
back into the release images, but it would be an easy and accessible input
channel.

And lastly, if the docs contain their own explicit or implicit hyperlinks
(e.g. I seem to recall a doc-related project from Stephane Ducasse that
converted class names into links), how might those (eventually) translate
into links in this browser view?

- Sophie

"Janko Mivsek" <[hidden email]> wrote in message
news:[hidden email]...

Very nice.

Could source code have links too ?

Methods could link to a page with allImplementors, possibly allSenders
too from there.
instVar and classVar could link to a page with allReferences, which
could also link to allWrites...

Nicolas

"nicolas cellier" <[hidden email]> wrote in message
> Very nice.
>
> Could source code have links too ?
>
> Methods could link to a page with allImplementors, possibly allSenders too
> from there.

That would be nice, but might want to check on server load as some of those
take quite a bit of search time.

On 05/01/2008, itsme213 <[hidden email]> wrote:
>
> "nicolas cellier" <[hidden email]> wrote in message
> > Very nice.
> >

+1

Just one thing:
why you suffixing URL's with '.html' ?

As for me, this URL:
http://squeak.aidaweb.si:8000/class/AidaBrowserMethod/method/loop:

looks much better than this:

http://squeak.aidaweb.si:8000/class/AidaBrowserMethod/method/loop:.html

and for class-side methods something like:

http://squeak.aidaweb.si:8000/class/<class name>/class/<method selector>

--
Best regards,
Igor Stasenko AKA sig.

Hi Klaus,

Klaus D. Witzel wrote:

> nice work, and you will find something similiar on the result page of
> http://www.google.com/search?q=OrderedCollection+addAllFirstUnlessAlreadyPresent: 

Site with a generated Squeak docs done by Bernd Oldenbuettel looks very
interesting: http://www.oldenbuettel.de/squeak-doku/, both from
organization and design perspective. Maybe is this a way to go?

>
> May I add 2-3 things:
>
> o fileIn hyperlinks which answer, with content-type: text/plain,
>   the corresponding fileOut (at all the levels) as .st suffixed file,
>   same as local fileOut would do.

Thats interesting idea, probably quite useful too. So every
package/category/class/method would have a FileOut link where you got a
raw Smalltalk code in fileout format. And with a little JavaScript a
browser's Save as dialog is opened to simply saving it.

> o show the annotation info.

What kind of annotation info have you in mind?

> o make available what's inside *each* MC package of the local directory
>   in a similiar fashion, top-entry-point: MCZ package+version file name.

Yes, I'll add packages so that full Url would be
/package/category/class/method.html.

More package info, hmm, where and how to find it? Is it in image?

> Then we could begin making *each*published*version* of every
> class+method *searchable* on the web (and perhaps link from the
> SqueakSource project pages to a server which has some bandwidth for
> crawlers).

Question is where to put version in an Url. I won't put it base Url but
in a query part, but only if we are looking the
non-blessed/current/stable version of a package. Namely, most people
will like to see a current version of a package and very rarely older
ore newer/dev ones. This will also help crawlers to know better, what is
most important.

Example:

for current version 2.1:
        /Swazoo/Swazoo-Core/Site.html
for older beta:
        /Swazoo/Swazoo-Core/Site.html&version=2.1beta1

I would simply extract a version from SqueakSource's .mcz file names,
for example 2.1beta1 from Swazoo-2.1beta1.mcz


Best regards
JAnko

--
Janko Mivšek
AIDA/Web
Smalltalk Web Application Server
http://www.aidaweb.si

Hi Sophie,

itsme213 wrote:

> Some suggestions:
> - use tree-like views by default, ideally with interactive collapse/expand
> e.g. grouping categories by common pre-fixes

Tree views are good when you have few choices but when you have so many
categories and so many classes it think it is not so usable. Here search
comes to help and I'll add a nice autocomplete search field for classes
for start. And there is already an ajaxified filter for categories. Just
type few characters and categories will be filtered accordingly. And you
can use * at the start to filter in the middle of category names...

> - somehow css-highlight elements that have/do not have any documentation at
> their level (package, category, class, method).

Good idea, and by the way, that's also a good idea for Squeak tools.
Here an ugly ! indicator that a comment is missing will help more than
anything else to comment a class or package. Proven from newest VW tools!

> Btw, do MCpackages or Squeak categories exist as objects in the images? do
> they have docs? I think docs at this level are invaluable to newcomers to
> that package.

Yep, I agree and will look at to see, what is in image. Or maybe to
extract it directly from SqueakSource over web and cache locally?

> Any chance you might add an entry field so anyone can contribute to the
> documentation of categories, classes, or methods? Not sure how it would feed
> back into the release images, but it would be an easy and accessible input
> channel.

Technically no problem, but this must be well thought out before.
Security, access rights, authentication, also tracking who is author of
what, etc. But I definitively see a potential to improve documentation
that way.

> And lastly, if the docs contain their own explicit or implicit hyperlinks
> (e.g. I seem to recall a doc-related project from Stephane Ducasse that
> converted class names into links), how might those (eventually) translate
> into links in this browser view?

If there will  be some clear rule for such links (to local classes) then
we can simply convert it to appropriate one. That is, it will be shown
as originally written but Url link will be adjusted to point correctly.

JAnko



--
Janko Mivšek
AIDA/Web
Smalltalk Web Application Server
http://www.aidaweb.si

Hi Nicolas,

nicolas cellier wrote:
> Very nice.
>
> Could source code have links too ?

Do you mean such links as Sophie mentioned in his post?

> Methods could link to a page with allImplementors, possibly allSenders
> too from there.
> instVar and classVar could link to a page with allReferences, which
> could also link to allWrites...

Not links but buttons, so that crawlers won't crawl into such resource
intensive requests as Sophie pointed out. Also we can lower a priority
of such requests so that others won't need to wait. That's possible
because Swazoo opens a new Smalltalk process for every request (more
precisely: for every connection).

JAnko


--
Janko Mivšek
AIDA/Web
Smalltalk Web Application Server
http://www.aidaweb.si

Hi Igor,

Igor Stasenko wrote:

> why you suffixing URL's with '.html' ?
>
> As for me, this URL:
>    http://squeak.aidaweb.si:8000/class/AidaBrowserMethod/method/loop:
> looks much better than this:
>    http://squeak.aidaweb.si:8000/class/AidaBrowserMethod/method/loop:.html
> and for class-side methods something like:
>    http://squeak.aidaweb.si:8000/class/<class name>/class/<method selector>

Because .html shows that this resource is presented in a HTML format and
not PDF or .st (which can actually be useful for fileouts in our case).

I know that current fashion coming from RoR and REST camp is to have
urls without extension but I'm don't like that, because it is against
the original spirit of the web. I could understand that this is kind of
rebellion against "marketing" extensions like .asp. .jsp and .php but
then, why they just don't go back to good old .html?

Best regards
JAnko


--
Janko Mivšek
AIDA/Web
Smalltalk Web Application Server
http://www.aidaweb.si

Hi Janko,

on Sat, 05 Jan 2008 15:52:57 +0100, you wrote:

Precisely. This BTW is the only format that I know of Smalltalk sourcecode  
(with content-type: text/plain) which is indexed on the web. Can't wait to  
see that in action :)

> And with a little JavaScript a browser's Save as dialog is opened to  
> simply saving it.

Nooo :) Not b**lsh*t JS, just real hyperlinks (html anchor tag) for  
crawlers (and Smalltalkers :) I can help you with http's  
content-disposition header so that the file name returned is pretty  
<element>.st (or <element>.cs) and pops up the platform browser's "save as  
..." dialog.

>> o show the annotation info.
>
> What kind of annotation info have you in mind?

When you turn on annotations in preferences you see author initials and  
timestamp in Squeak's browser for the methods. These two items are public  
(see #methodsFor*) and should be shown, no?

You can judge that programmatically?

I'll wait until I can access examples. Perhaps I didn't understand  
something in the above.

/Klaus

"Janko Mivsek" <[hidden email]> wrote in message
> Tree views are good when you have few choices but when you have so many
> categories and so many classes it think it is not so usable. Here search
> comes to help and I'll add a nice autocomplete search field for classes
> for start.

These may be different use cases, browse (tree view) vs. search
(autocomplete)?

>> Any chance you might add an entry field so anyone can contribute to the
>> documentation of categories, classes, or methods? Not sure how it would
>> feed back into the release images, but it would be an easy and accessible
>> input channel.
>
> Technically no problem, but this must be well thought out before.
> Security, access rights, authentication, also tracking who is author of
> what, etc. But I definitively see a potential to improve documentation
> that way.

I have heard of a project DeltaStreams that helps this, but don't know much
about it.

- Sophie

On 05/01/2008, Janko Mivšek <[hidden email]> wrote: In my view, when URL terminates with .html extension it's shows that
current page are plain file (with .html extension), and .php, .jsp are
content generated by corresponding engine. Also there is '.htm'
extension used by M$ people..
In spirit of HTTP you may use any extension in URL, you just need to
specify correct content type in HTTP header, the rest is not relevant.


--
Best regards,
Igor Stasenko AKA sig.

Hi Igor,

on Mon, 07 Jan 2008 14:11:17 +0100, you wrote:

Except when you ask your platform browser "Save as..." or "Open with ..."  
then it becomes convenient and relevant ;-)

Of course no web server can know such situations on a per-request basis  
and provide Content-Disposition response header.

/Klaus

> Never heard that putting '.html' is for a good spirit.
> In my view, when URL terminates with .html extension it's shows that
> current page are plain file (with .html extension), and .php, .jsp are
> content generated by corresponding engine.

Your view is a webserver's view, not a user's view.

Most sites in existence have a dynamic part (for example the navigation)
in the URL; but a site that is 99% static and yet shows what engine is
used for that 1%, is a bad site IMNSHO.  A user couldn't care less about
what engine is used.  Though I must say that most users are probably
ambivalent about having .html or not having it.

Maybe you would both agree on

http://squeak.aidaweb.si:8000/class/AidaBrowserMethod/method/loop:/
http://squeak.aidaweb.si:8000/class/AidaBrowserMethod/method/loop:/fileout.st

The former for the doc, the second for the source?

Paolo

Paolo Bonzini wrote:
>
>> Never heard that putting '.html' is for a good spirit.
>> In my view, when URL terminates with .html extension it's shows that
>> current page are plain file (with .html extension), and .php, .jsp are
>> content generated by corresponding engine.
>
> Your view is a webserver's view, not a user's view.

Also look at the history of the web and especially MIME content types
like 'text/html' etc. At the beginning there was only static web serving
and (as is usual on our computers even now), a file extension determined
  a format of the file's content. Here lays the origin of the .html
extension.

It is true that with MIME content types it seems that there is no more
need for URL extensions, but that's true for web browser and not for
users, as Paolo pointed out.

> Most sites in existence have a dynamic part (for example the navigation)
> in the URL; but a site that is 99% static and yet shows what engine is
> used for that 1%, is a bad site IMNSHO.  A user couldn't care less about
> what engine is used.  Though I must say that most users are probably
> ambivalent about having .html or not having it.

Well, we were forced to become ambivalent .. But now this habbit goes
just too far. Not having an extension at all is not nice to me because I
don't know what to expect behind that link. There is no user feedback
and such feedback is one of postulates of good, friendly user interface.

But what user really don't care is if a page is static or dynamic.
That's why I'm calling such URLs as with "marketing" extensions.

> Maybe you would both agree on
>
> http://squeak.aidaweb.si:8000/class/AidaBrowserMethod/method/loop:/
> http://squeak.aidaweb.si:8000/class/AidaBrowserMethod/method/loop:/fileout.st 
>
> The former for the doc, the second for the source?

Well, first could be used for returning a collection of resources (in
REST spirit) but if a HTML page is returned, it should better stay
.html, because it is a HTML representation of a "collection" of methods.

Janko


--
Janko Mivšek
AIDA/Web
Smalltalk Web Application Server
http://www.aidaweb.si