Having solved a number of these problems in my youth, I tried to solve this one "by hand". But with 6 attributes of 5 properties each, the "bookkeeping" task was too difficult to deal with while trying to find a consistent solution. It turns out that it's very easy to make an inconsistent conclusion, and it's also difficult to 'unwind' a mistake (if you can figure out where you made your mistake.) After I failed and restarted the puzzle several times in a row, I thought about one of my mantras: "Let humans do the things that humans are good at, and computers do the things that computers are good at." After all, computers are designed to good at processing large amounts of data without confusion or mistakes (assuming the software developers are competent -- and use good tools).  So why not a computer program that can solve this puzzle? -- Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html

Back on the 'Intermediate Tutorials' question... I would love to see intermediate tutorials on Spec2 and Seaside.... and perhaps how to best adapt an (Sp)Application to serve both 'presenters' with guidelines on what responsibility goes where on the presenter/component, application, and model(s). What I found most useful in tutorials is specific examples. To me, generic examples can be too easily misunderstood - making them difficult to (re)apply. A specific example, even if silly, can really make a difference... i.e. I'm never going to create a GUI based on the Class/method hierarchy and I find it very difficult to apply those examples (although they are slick) to my application needs. I love looking at how other people approach problems, identify solutions (I can't wait to dig into the logic-puzzle code). This mailing list is great, but more - and more advanced - tutorials would be very much appreciated! Thanks! Russ On Mon, Jul 27, 2020 at 11:45 PM tbrunz <wild.ideas@gmail.com> wrote:

So I decided to write an application to solve the Zebra Puzzle, by solving this type of problem in general. In Pharo, of course.

I worked out a few basic algorithms for making deductions and inferences, and coded them, along with tests, in Pharo 8. Now I've reached the point of having a working "proof of concept" or prototype. It can't (yet) solve the Zebra Puzzle without some "human assistance", but it does keep track of the solution state as it progresses, it handles the bookkeeping, makes the basic deductions/inferences, and produces reports.

And I've used it to quickly solve the Zebra Puzzle. I coded the solution as a separate class/method, with extra rules inserted that I was able to infer by iterating to partial solutions, so that it solves the entire thing. It will interesting to develop the remaining algorithms, and it would be nice to eventually create a nice, interactive user interface for it as well.

Since I want to fashion this into an intermediate-level tutorial, I need feedback on what I have so far. I don't want my inexperience to lead to me teaching the wrong techniques, etc. to other developers who are learning Pharo. What I have can no doubt be improved, but I need to hear from the master craftsman in this community what parts are compromised and how (and why) it can be made a better example of "how to program in Pharo" properly.

If anyone has the time and is willing to help, the code (complete with class & method comments, test classes/methods, and the Zebra Puzzle example) is here: https://github.com/tbrunz/logic-puzzle and I'm available to answer questions about it, of course.

-- Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html

-- Russ Whaley whaley.russ@gmail.com

Hi Russ, I added an "Examples" package tag, with several methods that lead through the Zebra Puzzle solution, step by step. It still doesn't do the entire solution by itself, but each example method displays the solution state up to that point, allowing you to examine the results and infer additional rules to add. The last example method combines the puzzle rules + the additional rules you infer, and displays the complete solution. I plan to make the code "smarter" over time, so that it can eventually solve the whole thing by itself. Let me know what you think... -Ted -- Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html

EXACTLY!, Stéphane, thank you! I will go through this tutorial today. Has anyone written any documentation or maybe a tool that would help understand what each ‘widget’ is capable of? I review all example code, read all class comments and peruse the class hierarchy, but when a widget capability doesn’t work for me, I don’t know whether I’m using it incorrectly, in the wrong place, or if it’s a bug.. I.e filter/sort, TransmitTo:, drag and drop, double-click, right-click, presenter management (modal, etc), and how to force the display to refresh, etc. Your thoughts? I appreciate (and admire) all the work you and everyone put into the documentation and tutorials - and I am voracious in consuming them. I hope to build my skills to be able to contribute for the community. Thanks! Russ On Sun, Aug 2, 2020 at 5:07 AM Stéphane Ducasse <stephane.ducasse@inria.fr> wrote:

On 29 Jul 2020, at 05:06, Russ Whaley <whaley.russ@gmail.com> wrote:

Back on the 'Intermediate Tutorials' question...

I would love to see intermediate tutorials on Spec2 and Seaside.... and perhaps how to best adapt an (Sp)Application to serve both 'presenters' with guidelines on what responsibility goes where on the presenter/component, application, and model(s).

Agreed. Now for the seaside tutorials please ask seasiders because what is killing me is to have to deeply learning something before writing may be one person can write some blog posts.

For Spec2 we will but I’m waiting for esteban to write and I do a pass after.

What I found most useful in tutorials is specific examples. To me, generic examples can be too easily misunderstood - making them difficult to (re)apply. A specific example, even if silly, can really make a difference…

Yes! Did you see

https://github.com/Ducasse/smalltodo-example/blob/master/SmallTODO-Tutorial-...

i.e. I'm never going to create a GUI based on the Class/method hierarchy and I find it very difficult to apply those examples (although they are slick) to my application needs.

I love looking at how other people approach problems, identify solutions (I can't wait to dig into the logic-puzzle code). This mailing list is great, but more - and more advanced - tutorials would be very much appreciated!

Thanks! Russ

On Mon, Jul 27, 2020 at 11:45 PM tbrunz <wild.ideas@gmail.com> wrote:

...

So I decided to write an application to solve the Zebra Puzzle, by solving this type of problem in general. In Pharo, of course.

I worked out a few basic algorithms for making deductions and inferences, and coded them, along with tests, in Pharo 8. Now I've reached the point of having a working "proof of concept" or prototype. It can't (yet) solve the Zebra Puzzle without some "human assistance", but it does keep track of the solution state as it progresses, it handles the bookkeeping, makes the basic deductions/inferences, and produces reports.

And I've used it to quickly solve the Zebra Puzzle. I coded the solution as a separate class/method, with extra rules inserted that I was able to infer by iterating to partial solutions, so that it solves the entire thing. It will interesting to develop the remaining algorithms, and it would be nice to eventually create a nice, interactive user interface for it as well.

Since I want to fashion this into an intermediate-level tutorial, I need feedback on what I have so far. I don't want my inexperience to lead to me teaching the wrong techniques, etc. to other developers who are learning Pharo. What I have can no doubt be improved, but I need to hear from the master craftsman in this community what parts are compromised and how (and why) it can be made a better example of "how to program in Pharo" properly.

If anyone has the time and is willing to help, the code (complete with class & method comments, test classes/methods, and the Zebra Puzzle example) is here: https://github.com/tbrunz/logic-puzzle and I'm available to answer questions about it, of course.

-- Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html

-- Russ Whaley whaley.russ@gmail.com

-------------------------------------------- Stéphane Ducasse http://stephane.ducasse.free.fr / http://www.pharo.org 03 59 35 87 52 Assistant: Aurore Dalle FAX 03 59 57 78 50 TEL 03 59 35 86 16 S. Ducasse - Inria 40, avenue Halley <https://www.google.com/maps/search/40,+avenue+Halley?entry=gmail&source=g> , Parc Scientifique de la Haute Borne, Bât.A, Park Plaza Villeneuve d'Ascq 59650 France

--

Russ Whaley whaley.russ@gmail.com

On 2 Aug 2020, at 19:51, tbrunz <wild.ideas@gmail.com> wrote:

...

...

I've been thinking lately that it would be nice to expand the number of Pharo tutorials we have available. But rather than (or along with) creating more "beginner" level tutorials, I'd like to see some good "intermediate" level Pharo tutorials.

Me too :)

Let's do it, then. I'll volunteer to do most of the work. :^)

I will review anything you write :)

My hope is that participating in this will make me capable of creating advanced tutorials all by myself.

I usually like to write to learn and dump what I learned.

...

...

I think that programmers who already know the Pharo syntax and messaging semantics could benefit from more advanced tutorials that demonstrate how to develop "real world" Pharo code for "real world" processing needs.

Yes yes I would love that.

That was part of my motivation for creating a Pharo app to solve the Zebra Puzzle. First, of course, I wanted to solve it. ;^)

I will send you some feeedback and PR.

...

...

What I'm talking about is something that assumes you know the language, the basics of the IDE (but not necessarily how to leverage its capabilities to aid development), and the basics of the foundation classes (but not its details). I'd like a tutorial for intermediate Pharo programmers who want to become experts with Pharo. Something that can show you how to apply the tools of the IDE and the features of the language and base classes to create solutions that solve complex problems.

do you have ideas?

I do!

As I started building the Logic Puzzle app, it occurred to me that I could probably find several different, common structures in OOP (specifically, Pharo) to add to the solution. And then each would be its own example of "what real Pharo code looks like". I.e., be good examples.

But first, I needed to explore "how to do it in Pharo" for myself, which naturally would have me working the IDE strongly.

Then I thought, the entire application can/should be an example, so it should be a tutorial.

That means that I need more than just a completed application (that's "just an example"). To be a *tutorial*, it means starting from scratch, showing how to approach the solution, how to start a Pharo app, how to use the IDE, how to write tests, how to refactor code, etc.

Then I thought, this needs a GUI. Either a Spec2 UI or a web app UI (with Seaside or Teapot). But I would need help with that! So I'll start by creating a message-based solution, and maybe get help to add a UI later.

I did some prototyping, then got what I think might be a good code structure (by version 4; it took a while to "think pure OOP"; old habits are hard to fight against). It runs, it works.

But.. Is it "good Pharo code"? I'm not experienced enough to answer that question. I need a code review, criticism, guidance. Point me in the right direction and I'll keep working on it, and start thinking about how to express the "meta" elements (how to use the IDE to make/test the code, etc.).

...

...

What does the community think of this idea?

I love it. I did Pharo by example so that I can get of rid of the beginner parts. After I did learning OOP and Pharo with style so that I do not have to talk about it again.

So definitively.

Okay, great. I'll do most of the work. But I need help...

I don't want to go any further without someone much more experienced than I am to review what I have and let me know what I'm doing right & what I'm doing "no quite so right". Yes, it runs, it works -- but that's *not* good enough. The goal here isn't to "hack out a solution and move on", the goal is to "create an example and tutorial that's high enough quality to use to teach Pharo to other people". I don't want to be teaching *my* bad habits!

Also, I know next to nothing about Spec2 or Seaside/Teapot. I just know that I need to learn it, and I need to use it to give my tutorial a UI (or two). Newcomers will show up wanting to learn Pharo, and they need to be reassured that they can create nice (enough) UIs without a huge effort. (Not everyone is a command line hacker, and end-users certainly don't want to be.)

The more I learn (from you), the more I can be independent, and the more tutorials I could produce -- without a lot of help. I'm willing to do the work, because that will help make me a Pharo "master programmer". (I don't want to be a hack, and I can't really be a trainer if I'm just a hack myself.)

I'll pay back the community by helping to attract and advance more developers' skills. I just have to have the more advanced knowledge & skills myself. So, train the (future) trainer, anyone??

-Ted

-- Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html

-------------------------------------------- Stéphane Ducasse http://stephane.ducasse.free.fr / http://www.pharo.org 03 59 35 87 52 Assistant: Aurore Dalle FAX 03 59 57 78 50 TEL 03 59 35 86 16 S. Ducasse - Inria 40, avenue Halley, Parc Scientifique de la Haute Borne, Bât.A, Park Plaza Villeneuve d'Ascq 59650 France

Here are a couple of items with my first 5 minutes with the TODO tutorial... TODOListPresenter >> initializePresenters todoListPresenter := self newTable addColumn: ((SpCheckBoxTableColumn evaluated: [:task | task isDone]) width: 20); addColumn: (SpStringTableColumn title: 'Title' evaluated: [:task | task title]); yourself. self layout: (SpBoxLayout newVertical add: todoListPresenter; yourself) In this portion (Showing Tasks) - it does not define todoListPresenter.... is it a local or a missed instVar. I tried it first as a local to enable save, but then... TODOListPresenter >> updatePresenter todoListPresenter items: TODOTask selectAll asOrderedCollection todoListPresenter isn't available for updatePresenter... so I'm assuming it must be an instvar? I created accessors, then changed all the todoListPresenter references to use the accessors (below). TODOListPresenter >> initializePresenters self todoListPresenter: (self newTable addColumn: ((SpCheckBoxTableColumn evaluated: [:task | task isDone]) width: 20); addColumn: (SpStringTableColumn title: 'Title' evaluated: [:task | task title]); yourself). self layout: (SpBoxLayout newVertical add: self todoListPresenter; yourself) and... TODOListPresenter >> updatePresenter self todoListPresenter items: TODOTask selectAll asOrderedCollection Also, in the first example - task isDone needs to be defined (and might be defined later in the tutorial) - I'm assuming SpCheckBoxTableColumn>>evaluated: is expecting a boolean, or do I need to convert this somehow? I can check all these things out - but just curious if I'm missing something? TODOTask >> done ^ done TODOTask >> isDone ^ self done I'll go through a bit more and update you on my progress. Ted, I also hope to get to take a look at Zebra today :) On Sun, Aug 2, 2020 at 2:07 PM Stéphane Ducasse <stephane.ducasse@inria.fr> wrote:

On 2 Aug 2020, at 19:51, tbrunz <wild.ideas@gmail.com> wrote:

I've been thinking lately that it would be nice to expand the number of Pharo tutorials we have available. But rather than (or along with) creating more "beginner" level tutorials, I'd like to see some good "intermediate" level Pharo tutorials.

Me too :)

Let's do it, then. I'll volunteer to do most of the work. :^)

I will review anything you write :)

My hope is that participating in this will make me capable of creating advanced tutorials all by myself.

I usually like to write to learn and dump what I learned.

I think that programmers who already know the Pharo syntax and messaging semantics could benefit from more advanced tutorials that demonstrate how to develop "real world" Pharo code for "real world" processing needs.

Yes yes I would love that.

That was part of my motivation for creating a Pharo app to solve the Zebra Puzzle. First, of course, I wanted to solve it. ;^)

I will send you some feeedback and PR.

What I'm talking about is something that assumes you know the language, the basics of the IDE (but not necessarily how to leverage its capabilities to aid development), and the basics of the foundation classes (but not its details). I'd like a tutorial for intermediate Pharo programmers who want to become experts with Pharo. Something that can show you how to apply the tools of the IDE and the features of the language and base classes to create solutions that solve complex problems.

do you have ideas?

I do!

As I started building the Logic Puzzle app, it occurred to me that I could probably find several different, common structures in OOP (specifically, Pharo) to add to the solution. And then each would be its own example of "what real Pharo code looks like". I.e., be good examples.

But first, I needed to explore "how to do it in Pharo" for myself, which naturally would have me working the IDE strongly.

Then I thought, the entire application can/should be an example, so it should be a tutorial.

That means that I need more than just a completed application (that's "just an example"). To be a *tutorial*, it means starting from scratch, showing how to approach the solution, how to start a Pharo app, how to use the IDE, how to write tests, how to refactor code, etc.

Then I thought, this needs a GUI. Either a Spec2 UI or a web app UI (with Seaside or Teapot). But I would need help with that! So I'll start by creating a message-based solution, and maybe get help to add a UI later.

I did some prototyping, then got what I think might be a good code structure (by version 4; it took a while to "think pure OOP"; old habits are hard to fight against). It runs, it works.

But.. Is it "good Pharo code"? I'm not experienced enough to answer that question. I need a code review, criticism, guidance. Point me in the right direction and I'll keep working on it, and start thinking about how to express the "meta" elements (how to use the IDE to make/test the code, etc.).

What does the community think of this idea?

I love it. I did Pharo by example so that I can get of rid of the beginner

parts.

After I did learning OOP and Pharo with style so that I do not have to talk

about it

again.

So definitively.

Okay, great. I'll do most of the work. But I need help...

I don't want to go any further without someone much more experienced than I am to review what I have and let me know what I'm doing right & what I'm doing "no quite so right". Yes, it runs, it works -- but that's *not* good enough. The goal here isn't to "hack out a solution and move on", the goal is to "create an example and tutorial that's high enough quality to use to teach Pharo to other people". I don't want to be teaching *my* bad habits!

Also, I know next to nothing about Spec2 or Seaside/Teapot. I just know that I need to learn it, and I need to use it to give my tutorial a UI (or two). Newcomers will show up wanting to learn Pharo, and they need to be reassured that they can create nice (enough) UIs without a huge effort. (Not everyone is a command line hacker, and end-users certainly don't want to be.)

The more I learn (from you), the more I can be independent, and the more tutorials I could produce -- without a lot of help. I'm willing to do the work, because that will help make me a Pharo "master programmer". (I don't want to be a hack, and I can't really be a trainer if I'm just a hack myself.)

I'll pay back the community by helping to attract and advance more developers' skills. I just have to have the more advanced knowledge & skills myself. So, train the (future) trainer, anyone??

-Ted

-- Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html

-------------------------------------------- Stéphane Ducasse http://stephane.ducasse.free.fr / http://www.pharo.org 03 59 35 87 52 Assistant: Aurore Dalle FAX 03 59 57 78 50 TEL 03 59 35 86 16 S. Ducasse - Inria 40, avenue Halley, Parc Scientifique de la Haute Borne, Bât.A, Park Plaza Villeneuve d'Ascq 59650 France

-- Russ Whaley whaley.russ@gmail.com

Hi Thanks I was planning to implement it. I asked Esteban to take the time to integrate my PR. Now can you send some PRs to the version of esteban like that we will get a better version. And you can open issues on his repo We will fix them. S

On 2 Aug 2020, at 20:22, Russ Whaley <whaley.russ@gmail.com> wrote:

Here are a couple of items with my first 5 minutes with the TODO tutorial... TODOListPresenter >> initializePresenters

todoListPresenter := self newTable addColumn: ((SpCheckBoxTableColumn evaluated: [:task | task isDone]) width: 20); addColumn: (SpStringTableColumn title: 'Title' evaluated: [:task | task title]); yourself.

self layout: (SpBoxLayout newVertical add: todoListPresenter; yourself)

In this portion (Showing Tasks) - it does not define todoListPresenter.... is it a local or a missed instVar. I tried it first as a local to enable save, but then... TODOListPresenter >> updatePresenter

todoListPresenter items: TODOTask selectAll asOrderedCollection

todoListPresenter isn't available for updatePresenter... so I'm assuming it must be an instvar? I created accessors, then changed all the todoListPresenter references to use the accessors (below). TODOListPresenter >> initializePresenters

self todoListPresenter: (self newTable addColumn: ((SpCheckBoxTableColumn evaluated: [:task | task isDone]) width: 20); addColumn: (SpStringTableColumn title: 'Title' evaluated: [:task | task title]); yourself).

self layout: (SpBoxLayout newVertical add: self todoListPresenter; yourself) and... TODOListPresenter >> updatePresenter

self todoListPresenter items: TODOTask selectAll asOrderedCollection

Also, in the first example - task isDone needs to be defined (and might be defined later in the tutorial) - I'm assuming SpCheckBoxTableColumn>>evaluated: is expecting a boolean, or do I need to convert this somehow? I can check all these things out - but just curious if I'm missing something? TODOTask >> done

^ done TODOTask >> isDone

^ self done

I'll go through a bit more and update you on my progress. Ted, I also hope to get to take a look at Zebra today :)

On Sun, Aug 2, 2020 at 2:07 PM Stéphane Ducasse <stephane.ducasse@inria.fr <mailto:stephane.ducasse@inria.fr>> wrote:

...

On 2 Aug 2020, at 19:51, tbrunz <wild.ideas@gmail.com <mailto:wild.ideas@gmail.com>> wrote:

...

...

I've been thinking lately that it would be nice to expand the number of Pharo tutorials we have available. But rather than (or along with) creating more "beginner" level tutorials, I'd like to see some good "intermediate" level Pharo tutorials.

Me too :)

Let's do it, then. I'll volunteer to do most of the work. :^)

I will review anything you write :)

...

My hope is that participating in this will make me capable of creating advanced tutorials all by myself.

I usually like to write to learn and dump what I learned.

...

...

...

I think that programmers who already know the Pharo syntax and messaging semantics could benefit from more advanced tutorials that demonstrate how to develop "real world" Pharo code for "real world" processing needs.

Yes yes I would love that.

That was part of my motivation for creating a Pharo app to solve the Zebra Puzzle. First, of course, I wanted to solve it. ;^)

I will send you some feeedback and PR.

...

...

...

What I'm talking about is something that assumes you know the language, the basics of the IDE (but not necessarily how to leverage its capabilities to aid development), and the basics of the foundation classes (but not its details). I'd like a tutorial for intermediate Pharo programmers who want to become experts with Pharo. Something that can show you how to apply the tools of the IDE and the features of the language and base classes to create solutions that solve complex problems.

do you have ideas?

I do!

As I started building the Logic Puzzle app, it occurred to me that I could probably find several different, common structures in OOP (specifically, Pharo) to add to the solution. And then each would be its own example of "what real Pharo code looks like". I.e., be good examples.

But first, I needed to explore "how to do it in Pharo" for myself, which naturally would have me working the IDE strongly.

Then I thought, the entire application can/should be an example, so it should be a tutorial.

That means that I need more than just a completed application (that's "just an example"). To be a *tutorial*, it means starting from scratch, showing how to approach the solution, how to start a Pharo app, how to use the IDE, how to write tests, how to refactor code, etc.

Then I thought, this needs a GUI. Either a Spec2 UI or a web app UI (with Seaside or Teapot). But I would need help with that! So I'll start by creating a message-based solution, and maybe get help to add a UI later.

I did some prototyping, then got what I think might be a good code structure (by version 4; it took a while to "think pure OOP"; old habits are hard to fight against). It runs, it works.

But.. Is it "good Pharo code"? I'm not experienced enough to answer that question. I need a code review, criticism, guidance. Point me in the right direction and I'll keep working on it, and start thinking about how to express the "meta" elements (how to use the IDE to make/test the code, etc.).

...

...

What does the community think of this idea?

I love it. I did Pharo by example so that I can get of rid of the beginner parts. After I did learning OOP and Pharo with style so that I do not have to talk about it again.

So definitively.

Okay, great. I'll do most of the work. But I need help...

I don't want to go any further without someone much more experienced than I am to review what I have and let me know what I'm doing right & what I'm doing "no quite so right". Yes, it runs, it works -- but that's *not* good enough. The goal here isn't to "hack out a solution and move on", the goal is to "create an example and tutorial that's high enough quality to use to teach Pharo to other people". I don't want to be teaching *my* bad habits!

Also, I know next to nothing about Spec2 or Seaside/Teapot. I just know that I need to learn it, and I need to use it to give my tutorial a UI (or two). Newcomers will show up wanting to learn Pharo, and they need to be reassured that they can create nice (enough) UIs without a huge effort. (Not everyone is a command line hacker, and end-users certainly don't want to be.)

The more I learn (from you), the more I can be independent, and the more tutorials I could produce -- without a lot of help. I'm willing to do the work, because that will help make me a Pharo "master programmer". (I don't want to be a hack, and I can't really be a trainer if I'm just a hack myself.)

I'll pay back the community by helping to attract and advance more developers' skills. I just have to have the more advanced knowledge & skills myself. So, train the (future) trainer, anyone??

-Ted

-- Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html <http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html>

-------------------------------------------- Stéphane Ducasse http://stephane.ducasse.free.fr <http://stephane.ducasse.free.fr/> / http://www.pharo.org <http://www.pharo.org/> 03 59 35 87 52 Assistant: Aurore Dalle FAX 03 59 57 78 50 TEL 03 59 35 86 16 S. Ducasse - Inria 40, avenue Halley, Parc Scientifique de la Haute Borne, Bât.A, Park Plaza Villeneuve d'Ascq 59650 France

-- Russ Whaley whaley.russ@gmail.com <mailto:whaley.russ@gmail.com>

Stéphane Ducasse http://stephane.ducasse.free.fr / http://www.pharo.org 03 59 35 87 52 Assistant: Aurore Dalle FAX 03 59 57 78 50 TEL 03 59 35 86 16 S. Ducasse - Inria 40, avenue Halley, Parc Scientifique de la Haute Borne, Bât.A, Park Plaza Villeneuve d'Ascq 59650 France

I would put it in class comment. We are about to release a nicer rendering of comments. S.

On 4 Aug 2020, at 06:46, tbrunz <wild.ideas@gmail.com> wrote:

I wrote a "theory of operation" document for my app, https://github.com/tbrunz/logic-puzzle

But then I realized, "Where do I put it??"

I thought of a few possibilities:

* Commit it to the git repo, but then it wouldn't be easy to access from Pharo, * Add it to a top-level Pharo class comment, * Make it into a string in Pharo, put it in a method in a class.

What's the standard practice for "attaching" non-code documents to Pharo applications?

-t

-- Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html

-------------------------------------------- Stéphane Ducasse http://stephane.ducasse.free.fr / http://www.pharo.org 03 59 35 87 52 Assistant: Aurore Dalle FAX 03 59 57 78 50 TEL 03 59 35 86 16 S. Ducasse - Inria 40, avenue Halley, Parc Scientifique de la Haute Borne, Bât.A, Park Plaza Villeneuve d'Ascq 59650 France

Okay, I'll do that. But this brings up a more general question...

If I wanted to add a diagram, or maybe a document with equations (rendered in LaTex), then a class comment wouldn't work.

...Unless that's intended to be part of the newer format??

Microdown supports latex via external services (I should check that the implementation uses the same cache than the one for pictures). For diagram you can use png but we will have to spot glitches. S.

-t

...

I would put it in class comment.

We are about to release a nicer rendering of comments.

S.

...

On 4 Aug 2020, at 06:46, tbrunz <wild.ideas@> wrote:

I wrote a "theory of operation" document for my app, https://github.com/tbrunz/logic-puzzle

But then I realized, "Where do I put it??"

I thought of a few possibilities:

* Commit it to the git repo, but then it wouldn't be easy to access from Pharo, * Add it to a top-level Pharo class comment, * Make it into a string in Pharo, put it in a method in a class.

What's the standard practice for "attaching" non-code documents to Pharo applications?

-t

-- Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html

-------------------------------------------- Stéphane Ducasse http://stephane.ducasse.free.fr / http://www.pharo.org 03 59 35 87 52 Assistant: Aurore Dalle FAX 03 59 57 78 50 TEL 03 59 35 86 16 S. Ducasse - Inria 40, avenue Halley, Parc Scientifique de la Haute Borne, Bât.A, Park Plaza Villeneuve d'Ascq 59650 France

Hi, On 5/08/20 9:43 a. m., tbrunz wrote:

...

...

Okay, I'll do that. But this brings up a more general question...

If I wanted to add a diagram, or maybe a document with equations (rendered in LaTex), then a class comment wouldn't work.

...Unless that's intended to be part of the newer format??

Microdown supports latex via external services (I should check that the implementation uses the same cache than the one for pictures). For diagram you can use png but we will have to spot glitches. One more thought on this... I assume you've seen Jupyter Notebooks? They're starting to see some use where I work (we now have our own 'enterprise server'). I recently took an intro class to see how it works, and how to use them.

How much of a "Jupyter-style" notebook capability would the community be interested in? By that I mean having the ability to mix 'rich' documentation with code and data to produce interactive 'notebooks' with similarities to what Jupyter does -- but simpler! Jupyter is much too complicated...

I can't speak for the wider community, but I think that there is some interest as we have 3 Smalltalk interactive notebooks alternatives. Two of them where mentioned as a long talks [1][2] in the last ESUG and Grafoscopio was presented there also as a speed talk (someday I need to make a proper ESUG long talk, but being self funded means that my participation has been always confirmed in last moments). I share your concern about Jupyter being overcomplicated and in fact I started Grafoscopio in part out of my frustration with the incidental complexity in the Python notebook ecosystem (see [3]). We can be more lean and agile. [1] https://www.slideshare.net/esug/polyglot-notebooks-with-squeaksmalltalk-on-t... [2] https://www.slideshare.net/esug/building-a-scientific-workbench-in-pharo [3] http://mutabit.com/offray/static/blog/output/posts/grafoscopio-idea-and-init... One of the differences of Grafoscopio with other Smalltalk notebooks is that is has an older diverse community (since 2015), beyond academia and software developers, including activists, journalists, librarians, philosophers, designers, among others. A key concern is to balance practical choices in such communities with the PhD research that created Grafoscopio (which was on Design and Creation with immersive community research). For example a simple extensible format to exchange Grafoscopio notebooks was an early concern and for that I used the excellent STON  format to mix documentation markup (Markdown) and Pharo code. Also I bridged external tools (Pandoc, Lua) to make format conversions (Markdown to LaTeX, HTML and PDF). The only other Smalltalk notebook I know that has a notebook format is Documenter's[4] Xdoc, which is a compressed folder mixing Pillar, JSON, txt and external files referred in the Pillar document. Our approach for that composed documents is to use Fossil [5], so such composed document or any collection of documents in fact is just a self contained Fossil repository, adding history, web interface and collaboration, while keeping documents self contained and storage simple and portable. It's aligned with ideas of SQLite as and application format[5a] and the Panama Papers 2016 prototypes [6][6a] even predate the idea of Fossil as a repository document[5b]. [4] https://gtoolkit.com/components/documenter/ [5] https://fossil-scm.org/ [5a] https://www.pgcon.org/2014/schedule/attachments/319_PGCon2014OpeningKeynote.... [6] https://mutabit.com/offray/blog/en/entry/panama-papers-1 [6a] https://mutabit.com/repos.fossil/panama-papers/dir [5b] https://fossil-scm.org/forum/forumpost/2ac0171524 What I want to point is that different approaches to rich interactive documentation related with Pharo exist and they're exploring interesting alternative spaces beyond what Jupyter has done, despite of lacking the maturity, momentum and/or visibility behind Jupyter's. Scientific Workbench, Documenter, or polyglot notebooks for sure are providing valuable explorations and would be nice to be more aware of each others work and approaches.

What you describe for enhanced comments sounds like a step in that direction... Obviously Pharo is already oriented toward mixing code and data in one document, and enhancing the comments moves it closer to a notebook with richer documentation possibilities.

So it seems to me that generalizing this "enhanced document capability" and making it more prominent (such as giving it its own type of window, rather than it being a browser pane tied to the code?) would take it closer yet to realizing a general, flexible "Pharo Notebooks" concept.

My understanding is that Offray's Grafoscopio is essentially what I'm describing, but maybe more oriented to data analysis & presentation..?? (He can say better than I, as I'm not sure how accurate that is.) I am thinking of something that would include that, but maybe be more general-purpose.

In Grafoscopio, interactive notebooks play an essential role with their own window and usage metaphor (document as an interactive tree). When I started, microdown was not in the radar and I would like explore further integration with it, instead of relaying on (excellent) Pandoc for format conversion. I have scripted Pandoc with Lua and is a pretty powerful combination and an interesting language, but nothing beats the Pharo's live coding experience and I would like to have that also for document exporters and (pre)processors. I think that Grafoscopio is already general concept-purpose enough. I wrote the Grafoscopio manual[7] in Pharo. We have done other non-coding and visualization documents on it, like porting the Data Journalism Handbook[8][8a] and Data Feminism Book[9][9a] to our pocket infrastructures. [7] https://mutabit.com/repos.fossil/grafoscopio/uv/Docs/En/Books/Manual/manual.... [8] https://mutabit.com/repos.fossil/mapeda/doc/tip/intro.md [8a] https://mutabit.com/repos.fossil/mapeda/uv/mapeda.pdf [9] https://mutabit.com/repos.fossil/datafem/ [9a] https://mutabit.com/repos.fossil/datafem/uv That being said, Grafoscopio was the "first real app" I ever did. The one that allowed me to go from scripting and formal modelling to programming and development. Its development has been directed by necessity and I have conceptual gaps and rookie code here and there. Development has been improved as I learn more, and I have being fortunate enough to have the attention and support from several community members, from testing and installing, to answering newbie questions, to my PhD internship, to bug reporting and even one offered to pair program with me (but I was too newbie, non-native speaker and shy to accept at that moment). Our last collaborator is Santiago Bragragnolo and he has been working on some refactoring. August will be kind of busy for me until 21th, but I would gladly be more involved with Grafoscopio after and meanwhile, retaking slowly some workshops and solving bugs.

Part of this idea is to feature a "semi-automated" subset of Spec2 that makes it easier to get nice graphical UIs in a notebook fashion -- but does not require as much depth of understanding Spec2. (All of Spec2 allows anyone to build anything.. but not everyone needs to build so much..? This is the value of frameworks and selectable motifs, yes?)

Could what I'm describing be a way for everyone to step easily into Spec2 when its full flexibility for making GUIs isn't needed (yet)? By this I'm implying code generators that create common/typical Spec2 framework classes & methods that would make up the front-end of the 'documentation' element of "Pharo Notebooks". Pharo being Pharo, one could then customize further...

My idea was to use a "self referential system" to explore the question about "How can we change the digital artifacts that change us?", from the perspective of a PhD in design and creation (not in computer science). But the idea was to create/introduce a tool inside a community (Grafoscopio) see how the community learn such tool and was able to change it. Interactive notebooks was my bridge to approach Pharo to non-coders. We are still far away of changing the tool itself, as Pharo and Grafoscopio has been kind of behind scenes in the projects we do and the more visible part has been documentation and a little bit of scripting. But I hope that the Indie Web workshops talked in other thread, make more visible the coding and scripting part so people can use it to customize their web sites, then notebooks and, at some point Grafoscopio or Pharo. The idea is to use interactive notebooks to automatize and customize Pharo to user needs and make such learning a bridge to customize Pharo.

Because "it's always easier to edit something than to create from a blank page", yes?

I can see Pharo taking away "market share" from Jupyter Notebooks, by being simpler and easier to work with. Data + Code + Document: All three elements being "live" and interactive. Pharo has the first two.. What about the third?

You could check the "Data continuum environment: data <-> queries <-> code <-> visuals <-> docs" of the Panama Papers blog post [10], that points in the same direction. [10] https://mutabit.com/offray/blog/en/entry/panama-papers-1 Cheers, Offray

One more thought on this... I assume you've seen Jupyter Notebooks? They're starting to see some use where I work (we now have our own 'enterprise server'). I recently took an intro class to see how it works, and how to use them.

How much of a "Jupyter-style" notebook capability would the community be interested in? By that I mean having the ability to mix 'rich' documentation with code and data to produce interactive 'notebooks' with similarities to what Jupyter does -- but simpler! Jupyter is much too complicated…

I would not go that road for class and package comments. Now we have a good infrastructure for doing this with Pillar.

What you describe for enhanced comments sounds like a step in that direction... Obviously Pharo is already oriented toward mixing code and data in one document, and enhancing the comments moves it closer to a notebook with richer documentation possibilities.

So it seems to me that generalizing this "enhanced document capability" and making it more prominent (such as giving it its own type of window, rather than it being a browser pane tied to the code?) would take it closer yet to realizing a general, flexible "Pharo Notebooks" concept.

In the future (once I have finished making sure that we can write book in microdown) we could think about loading book in notebooks with a bit more liveness. Now it requires man power and we are busy on other topics. GT is already doing it.

My understanding is that Offray's Grafoscopio is essentially what I'm describing, but maybe more oriented to data analysis & presentation..?? (He can say better than I, as I'm not sure how accurate that is.) I am thinking of something that would include that, but maybe be more general-purpose.

Part of this idea is to feature a "semi-automated" subset of Spec2 that makes it easier to get nice graphical UIs in a notebook fashion -- but does not require as much depth of understanding Spec2. (All of Spec2 allows anyone to build anything.. but not everyone needs to build so much..? This is the value of frameworks and selectable motifs, yes?)

Could what I'm describing be a way for everyone to step easily into Spec2 when its full flexibility for making GUIs isn't needed (yet)? By this I'm implying code generators that create common/typical Spec2 framework classes & methods that would make up the front-end of the 'documentation' element of "Pharo Notebooks". Pharo being Pharo, one could then customize further…

To me documenting framework is another level. For now I would be more than happy if we would have a good old way book containing tutorials about Spec2.

Because "it's always easier to edit something than to create from a blank page", yes?

I can see Pharo taking away "market share" from Jupyter Notebooks, by being simpler and easier to work with. Data + Code + Document: All three elements being "live" and interactive. Pharo has the first two.. What about the third?

Having a document renderer is a first step then after we can decide what is the semantics of certain boxes inside the texte and get some live and others not. But this requires coding effort. S.

Hi, Is nice to see this thread. Our approach to building documentation is a problem/local first one. So we go from particular problems/projects as need of the community  dictate them. We do workshops and create the documentation while the workshop is happening and then we compile such documentation in booklets (see for example Documentathon: Agile and resilient tools and techniques to write and publish together -- In Spanish [1]). Is similar to the book sprints[1a] but we did a parallel development without knowing them. We use CodiMD[2] for collaborative workshop note taking and then we combine Pandoc, Markdeep[3], Fossil[4] and others with Pharo and Grafoscopio to create the publication and collaborate on it asynchronously. This problem based approach means that we are kind of intermediate level oriented by design and tt also means that we have gaps in our knowledge (particularly on the TDD front), as we have learn as we go/need. We are combining stuff from data and file (STON, JSON, FileLocator) serialization and manipulation and also calling external programs and scheduling taks (OSSubprocess, TaskIt), making visualizations (Roassal) and coming with solutions on how to combine such technologies to solve/easy the tasks at hand and making compelling arguments to (h)ac(k)tivists, researchers or/and journalist (see for example the Panama Papers as reproducible research[5] or domain specific visualizations for governments medicine information[5a]). All this is powered by Pharo technologies and communities, but I think that we still can make a compelling case for wider audiences about Pharo and making it more visible. Now with Covid, the need for self/autonomous publishing is becoming more visible again, as educators, activists, communities are turning to more activities online and also need more autonomy over their online presence beyond what is provided by oligopolistic providers. So we're going to start a series of workshops on agile and resilient Indie Web[6] with Pharo, building blogs, wikis and portfolios with it (and Fossil, Markdeep, etc), using Pharo for orchestration and articulation of other technologies, but making it more visible also (as agility and resilience are not properties of the overcomplicated web of today). Usually I try to bootstrap the problem solving environment, so probably the web presences we build in the the workshops (starting on August 15th) will serve to document and share the experience. The workshops will be given in Spanish (I'll share the invitation in the Pharo Spanish discord channel), because of our local first approach, but the software we develop to support the experience will be useful to non Spanish speakers also. So I hope this contribute to showcase the Pharo usage in solving intermediate ("real life") level problems and even to involve non Spanish speakers with code reviews and testing, making suggestions and helping us to improve the software engineering parts behind such problems/projects, as I greatly appreciate the experience and teachings of this community. I'll keep you informed. Cheers, Offray [1] https://mutabit.com/repos.fossil/documentaton/ [1a] https://en.wikipedia.org/wiki/Book_sprint [2] https://demo.codimd.org/ [3] https://casual-effects.com/markdeep/ [4] https://fossil-scm.org/ [5] https://mutabit.com/offray/blog/en/entry/panama-papers-1 [5a] https://mutabit.com/offray/blog/en/entry/sdv-infomed [6] https://indieweb.org/ On 2/08/20 12:51 p. m., tbrunz wrote:

...

...

I've been thinking lately that it would be nice to expand the number of Pharo tutorials we have available. But rather than (or along with) creating more "beginner" level tutorials, I'd like to see some good "intermediate" level Pharo tutorials. Me too :) Let's do it, then. I'll volunteer to do most of the work. :^)

My hope is that participating in this will make me capable of creating advanced tutorials all by myself.

...

...

I think that programmers who already know the Pharo syntax and messaging semantics could benefit from more advanced tutorials that demonstrate how to develop "real world" Pharo code for "real world" processing needs. Yes yes I would love that. That was part of my motivation for creating a Pharo app to solve the Zebra Puzzle. First, of course, I wanted to solve it. ;^)

...

...

What I'm talking about is something that assumes you know the language, the basics of the IDE (but not necessarily how to leverage its capabilities to aid development), and the basics of the foundation classes (but not its details). I'd like a tutorial for intermediate Pharo programmers who want to become experts with Pharo. Something that can show you how to apply the tools of the IDE and the features of the language and base classes to create solutions that solve complex problems. do you have ideas? I do!

As I started building the Logic Puzzle app, it occurred to me that I could probably find several different, common structures in OOP (specifically, Pharo) to add to the solution. And then each would be its own example of "what real Pharo code looks like". I.e., be good examples.

But first, I needed to explore "how to do it in Pharo" for myself, which naturally would have me working the IDE strongly.

Then I thought, the entire application can/should be an example, so it should be a tutorial.

That means that I need more than just a completed application (that's "just an example"). To be a *tutorial*, it means starting from scratch, showing how to approach the solution, how to start a Pharo app, how to use the IDE, how to write tests, how to refactor code, etc.

Then I thought, this needs a GUI. Either a Spec2 UI or a web app UI (with Seaside or Teapot). But I would need help with that! So I'll start by creating a message-based solution, and maybe get help to add a UI later.

I did some prototyping, then got what I think might be a good code structure (by version 4; it took a while to "think pure OOP"; old habits are hard to fight against). It runs, it works.

But.. Is it "good Pharo code"? I'm not experienced enough to answer that question. I need a code review, criticism, guidance. Point me in the right direction and I'll keep working on it, and start thinking about how to express the "meta" elements (how to use the IDE to make/test the code, etc.).

...

...

What does the community think of this idea? I love it. I did Pharo by example so that I can get of rid of the beginner parts. After I did learning OOP and Pharo with style so that I do not have to talk about it again.

So definitively. Okay, great. I'll do most of the work. But I need help...

I don't want to go any further without someone much more experienced than I am to review what I have and let me know what I'm doing right & what I'm doing "no quite so right". Yes, it runs, it works -- but that's *not* good enough. The goal here isn't to "hack out a solution and move on", the goal is to "create an example and tutorial that's high enough quality to use to teach Pharo to other people". I don't want to be teaching *my* bad habits!

Also, I know next to nothing about Spec2 or Seaside/Teapot. I just know that I need to learn it, and I need to use it to give my tutorial a UI (or two). Newcomers will show up wanting to learn Pharo, and they need to be reassured that they can create nice (enough) UIs without a huge effort. (Not everyone is a command line hacker, and end-users certainly don't want to be.)

The more I learn (from you), the more I can be independent, and the more tutorials I could produce -- without a lot of help. I'm willing to do the work, because that will help make me a Pharo "master programmer". (I don't want to be a hack, and I can't really be a trainer if I'm just a hack myself.)

I'll pay back the community by helping to attract and advance more developers' skills. I just have to have the more advanced knowledge & skills myself. So, train the (future) trainer, anyone??

-Ted

-- Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html

Hi Ted, On 5/08/20 10:11 a. m., tbrunz wrote:

Hi Offray,

I think you're addressing many of the same concerns as I am, with more of a web/browser orientation perhaps...

Which is good. Pharo can make nice, interactive web sites as well as nice, interactive documents, can it not?

For me web is kind of an "exportation format" as I dislike pretty much programming and writing in the native formats and languages that entangle the web (HTML, CSS, JavaScript) and they seem to me as verbose and/or inelegant. But web is an ubiquitous platform so thinking in it as a "compilation target" seems wise. I will try to Live code as much as I can in Pharo and export interactive documents to PDF and HTML as needed. That's the approach we have followed here so far and it had worked, so it will be the one we use for the indie web[1] workshops powered by Pharo. [1]https://indieweb.org/

...

I think that we still can make a compelling case for wider audiences about Pharo and making it more visible. I agree! What do the 'wider audiences' need? What will attract their attention? Being visible is necessary, but is it sufficient? How can we make them want to learn this new tool? (Everyone is so strained for time, and attention is hard to come by these days...)

Totally agree. We have this "attention economy" and almost everything/everyone is sending notifications and messages. Focused attention and effort are a luxury these days. In the case of grassroots communities, they have huge necessities but they're not a "compelling market". So what solves their needs is the stuff that will attract their attention and working with them and their needs is the best way to inquiry about this. Because we are in a Hackerspace and not in a startup or research facility, we are pretty close with such communities. Retaking the upcoming Indie Web workshop was a product of our voluntary work with grassroots communities. Grafoscopio interactive notebooks are a way to "package" expert knowledge in a low barrier way for non programmers in such communities. They can open and run the notebook and its nodes as they need and the output will be an updated web site that addresses their web presence needs not covered by big corp social media or overcomplicated CMS. The interactive notebook produces a static web site. And the idea is to use personalization of such community web sites via interactive notebooks to introduce them to programming (I will share more details as I have them).

...

agility and resilience are not properties of the overcomplicated web of today So, so true...

...

.. making suggestions and helping us to improve the software engineering parts behind such problems/projects, I am also interested in contributing to that. Better tools & methods for solving the problems, better documentation to further understanding and engagement, and better ways for users to employ the results.

Thanks a lot :-)! I will be sharing the interactive notebooks we do and the software packages we create/modify for the Indie Web Worshops and the problems and solutions as they arise. While notebooks and workshops documentation will be mostly in Spanish, the code will be in English, so I think that this is a good bridge exercise and give us this intermediate level tutorials for Pharo. One of the things I like the most about Pharo and I remember and share in local workshops from  Markcus' Nomads do not build Cathedrals talk[2] is the idea that to solve mode complex problems we need to change the infrastructure behind the projects. I tell the workshop attendants that Pharo's uniformity and readability is key to understand and traverse increased complexity in the platform (there is also a fight to decrease incidental complexity that is deeply rooted in Smalltalk cultures). So even if the "intermediate level" tutorials are a moving target the fact that we read/extend the infrastructure in a similar fashion, despite its complexity could help to address increasing complexity problems with such intermediate level entry knowledge, at least at the beginning. [2] https://www.slideshare.net/MarcusDenker/2014-esugcathedral Cheers, Offray

Hi Ted, Don't worry and take your time. I tend to write looong (this list should be thankful of English not being my first language and I mostly self learned after crappy courses, if not, you will have me writing even longer ;-P). About entry points, one of the things I like about Pharo is that you can  traverse complexity in a similar way, because the liveness of the environment helps you to do it. It's like writing and reading. Once you learn to do it, core strategies are the same despite of addressing huge or small books. I felt that with other languages/environments, traversing infrastructure have pretty particular approaches depending on the particular tool/architecture I was trying to make sense of (infrastructure at some point becomes architecture, but I digress). So we are preparing new entry points with the upcoming Indie Web Workshop [1]. Those entry points have the same level of complexity for new comers, despite of being evolving prototypes and hopefully will attract more experienced ones with Intermediate Level Tutorials. Even they will have the added value of allow ourselves to create some web portfolios for showcasing what we are doing here, in a more attractive and visual way. I will share advances with the list, Cheers, Offray [1] Invitation poster in Spanish at: https://docutopia.tupale.co/uploads/upload_51d7d8be27bb53d5dc1eb96d71979313.... On 11/08/20 12:58 p. m., tbrunz wrote:

Hi Offray,

Just wanted to let you know that I enjoyed your several responses, and that I'm working on following-up to them.

But first I wanted to look at all your links and make as thoughtful a reply as you have, and that takes a while...

I think what you've been working on could be a good entry point for some groups where I work, so I do want to learn more.

Cheers! -Ted

-- Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html